优化REST API DTO设计：消除请求与响应模型冗余的策略

DTO设计中的冗余挑战

在构建spring boot restful应用程序时，将http请求体和响应体映射到特定的数据传输对象（dto）是一种常见的模式。这种做法有助于将业务逻辑与数据传输细节解耦，并提供清晰的数据契约。然而，当请求dto和响应dto包含大量相同字段时，往往会引发代码冗余问题。

例如，一个典型的场景是响应DTO需要包含额外的系统元数据，如ID、版本、创建时间、修改时间等，这些数据通常通过继承一个 BaseResponseDTO 来实现。

public abstract class BaseResponseDTO {
    protected UUID id;
    protected Integer version;
    protected Date created;
    protected Date modified;
}

public class RequestUserDTO {
    private String firstName;
    private String lastName;
}

public class ResponseUserDTO extends BaseResponseDTO {
    private String firstName;
    private String lastName;
}

在上述结构中，RequestUserDTO 和 ResponseUserDTO 都包含了 firstName 和 lastName 字段，这导致了显而易见的代码重复。理想情况下，我们希望 ResponseUserDTO 能够同时继承 BaseResponseDTO 和 RequestUserDTO，但这在Java中是不允许的（不支持多重继承）。

传统解决方案及其局限性

为了解决上述冗余问题，开发者可能会尝试以下几种方案：

1. 使用组合模式封装共享字段

一种常见的尝试是引入一个通用的 UserDTO 来封装共享字段，然后让 RequestUserDTO 和 ResponseUserDTO 通过组合的方式引用它：

public abstract class BaseResponseDTO {
    protected UUID id;
    protected Integer version;
    protected Date created;
    protected Date modified;
}

public class UserDTO {
    private String firstName;
    private String lastName;
}

public class RequestUserDTO {
    private UserDTO payload; // 或者直接是 UserDTO user;
}

public class ResponseUserDTO extends BaseResponseDTO {
    private UserDTO payload; // 或者直接是 UserDTO user;
}

局限性：

• 并未彻底消除代码冗余： 尽管 firstName 和 lastName 被封装到了 UserDTO 中，但 RequestUserDTO 和 ResponseUserDTO 依然需要声明 UserDTO 类型的 payload 字段，这本身也是一种重复。
• 客户端使用不便： 这种设计强制客户端在请求体中将业务数据包装在 payload 字段下（例如 {"payload": {"firstName": "...", "lastName": "..."}}），这增加了API的复杂性和客户端的开发负担。

推荐策略：统一DTO模型

针对上述挑战，当请求和响应的核心业务字段高度一致，且响应的额外字段主要是元数据时，一个更简洁高效的策略是统一请求和响应的DTO模型。

核心思想

该策略的核心在于，创建一个单一的DTO，它既可以用于接收客户端的请求数据，也可以用于向客户端返回响应数据。这个统一的DTO将继承包含通用元数据的基类（如 BaseResponseDTO），从而在响应时提供完整的字段信息。而在请求时，客户端只需发送业务相关的字段，继承自基类的元数据字段即使被发送（通常不会），也会在服务器端被忽略或默认为空，因为它们对请求处理通常不具备业务意义。

实现方式

我们将 RequestUserDTO 和 ResponseUserDTO 合并为一个 UserDTO，并让 UserDTO 直接继承 BaseResponseDTO：

public abstract class BaseResponseDTO {
    protected UUID id;
    protected Integer version;
    protected Date created;
    protected Date modified;
}

public class UserDTO extends BaseResponseDTO {
    private String firstName;
    private String lastName;
}

工作原理：

• 作为请求DTO时： 客户端发送的JSON请求体通常只包含 firstName 和 lastName 等业务字段。BaseResponseDTO 中的字段（如 id, version, created, modified）不会被客户端发送。Spring框架在反序列化时，会根据请求体的内容填充 UserDTO 对象，未提供的字段将保持其默认值（如 null）。服务器端的业务逻辑在处理请求时，只会关注 firstName 和 lastName，而忽略 BaseResponseDTO 中的字段。
• 作为响应DTO时： 服务器端在构建响应时，会创建 UserDTO 实例，并填充 firstName、lastName 以及从 BaseResponseDTO 继承的 id、version、created、modified 等所有相关字段。这些字段随后会被序列化为完整的JSON响应体发送给客户端。

优势分析

采用统一DTO模型的主要优势包括：

1. 彻底消除代码冗余： firstName 和 lastName 只定义了一次，极大地减少了重复代码。
2. 简化DTO结构： 减少了DTO类的数量，使得项目结构更清晰，更易于理解。
3. 提高可维护性： 当业务字段发生变化时，只需修改一个DTO类，降低了维护成本和出错风险。
4. API使用友好： 客户端在发送请求时无需额外包装，直接发送业务数据，使API接口更加直观和扁平。

注意事项与适用场景

尽管统一DTO模型具有显著优势，但并非适用于所有情况。在采纳此策略时，需要考虑以下几点：

• 适用场景： 此方法最适用于请求和响应的核心业务字段高度一致，且响应额外字段仅为通用元数据（如ID、时间戳、状态码等）的场景。
• 字段差异性： 如果请求和响应的业务字段存在较大差异（例如，请求只需要部分字段，而响应需要更多或完全不同的字段），则强行统一可能导致DTO臃肿或语义不清。在这种情况下，可以考虑以下替代方案：
  • 使用 @JsonView： Spring框架提供的 @JsonView 注解允许在序列化/反序列化时根据不同的视图来包含或排除DTO的字段。这使得同一个DTO可以根据不同的上下文（请求或响应）呈现不同的结构。
  • 使用映射工具： 如 MapStruct，可以在不同DTO之间进行字段映射，从而保持请求和响应DTO的独立性，同时避免手动复制字段的繁琐。
• 请求验证： 在请求处理时，如果对传入的字段有严格的验证要求（例如，不允许客户端发送响应特有的元数据字段），则需要在验证逻辑中明确处理。通常，服务器端会忽略请求中与业务逻辑无关的字段，但这需要确保不会引发意外行为或安全漏洞。
• 版本控制： 在API版本迭代中，如果请求和响应的字段演变路径不同，统一DTO可能会增加复杂性。

总结

通过将请求和响应的数据传输对象进行统一，并利用继承机制处理通用元数据，我们能够有效消除REST API设计中的代码冗余，简化DTO结构，并提高系统的可维护性。这种策略在请求和响应的核心业务字段高度重合的场景下尤为有效，为开发者提供了一种简洁而强大的解决方案。然而，在实际应用中，仍需根据具体的业务需求和API复杂性，权衡其适用性，并考虑配合其他技术如 @JsonView 或映射工具来应对更复杂的场景。

以上就是优化REST API DTO设计：消除请求与响应模型冗余的策略的详细内容，更多请关注php中文网其它相关文章！