当前位置：首页 > 文章列表 > 文章 > java教程 > RESTfulAPI设计：精简DTO提升开发效率

RESTfulAPI设计：精简DTO提升开发效率

2025-07-13 08:03:29 0浏览收藏

来到golang学习网的大家，相信都是编程学习爱好者，希望在这里学习文章相关编程知识。下面本篇文章就来带大家聊聊《RESTful API设计：优化DTO减少冗余代码》，介绍一下，希望对大家的知识积累有所帮助，助力实战开发！

RESTful API设计：优化DTO结构以消除请求与响应中的代码冗余

本文探讨了在Spring Boot RESTful API中管理请求与响应数据传输对象（DTO）时常见的代码重复问题。针对传统分离式DTO设计带来的冗余，文章提出了一种通过统一核心业务DTO并使其继承通用元数据基类来有效消除重复的策略。这种方法利用了JSON序列化/反序列化机制的灵活性，简化了DTO结构，提升了代码的可维护性与简洁性，同时避免了多重继承和不必要的客户端数据封装。

理解DTO模式与代码冗余挑战

在构建RESTful API时，数据传输对象（DTO）模式被广泛应用于封装HTTP请求体和响应体的数据。它有助于将内部领域模型与外部API契约解耦，提供清晰的数据接口。然而，在实际开发中，我们经常会遇到请求DTO和响应DTO结构相似但又存在细微差异的情况。例如，响应DTO通常会包含一些请求时不需要的额外元数据，如ID、版本、创建时间、修改时间等。

传统上，为了区分请求和响应，开发者可能会创建独立的DTO类，例如 RequestUserDTO 和 ResponseUserDTO。当核心业务字段（如 firstName, lastName）在两者之间重复出现时，便产生了明显的代码冗余。

考虑以下常见的DTO结构示例：

// 响应DTO的基类，包含通用元数据
public abstract class BaseResponseDTO {
    protected UUID id;
    protected Integer version;
    protected Date created;
    protected Date modified;
}

// 仅用于请求的用户DTO
public class RequestUserDTO {
    private String firstName;
    private String lastName;
}

// 用于响应的用户DTO，继承自BaseResponseDTO
public class ResponseUserDTO extends BaseResponseDTO {
    private String firstName;
    private String lastName;
}

在这种设计中，firstName 和 lastName 字段在 RequestUserDTO 和 ResponseUserDTO 中重复定义，这不仅增加了维护成本，也使得代码不够DRY（Don't Repeat Yourself）。

为了解决这种冗余，一些开发者可能会尝试以下方法：

多重继承： 期望 ResponseUserDTO 能够同时继承 BaseResponseDTO 和 RequestUserDTO。然而，Java 不支持类的多重继承，此路不通。
组合模式： 创建一个通用的 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; // 客户端需要包装在payload中
}

public class ResponseUserDTO extends BaseResponseDTO {
    private UserDTO payload; // 客户端需要从payload中获取
}
```
这种方法虽然解决了核心业务字段的重复定义，但引入了新的问题：客户端在发送请求时需要将数据包装在 payload 字段中（例如 {"payload": {"firstName": "...", "lastName": "..."}}），这增加了API的复杂性和客户端的使用负担。同时，从DTO结构上看，RequestUserDTO 和 ResponseUserDTO 仍然存在 payload 字段的重复定义。

优化方案：统一DTO与继承策略

解决上述代码冗余问题的更优方案是：将核心业务数据与通用元数据合并到一个统一的DTO中，并通过继承机制来处理响应所需的额外字段。

其核心思想是：

创建一个抽象的 BaseResponseDTO，包含所有响应中通用的元数据字段（如 id, version, created, modified）。
创建一个统一的 UserDTO，它不仅包含 firstName 和 lastName 等业务字段，还直接继承 BaseResponseDTO。

这样，UserDTO 既可以作为请求体（Request Body）使用，也可以作为响应体（Response Body）使用。

// 响应DTO的基类，包含通用元数据
public abstract class BaseResponseDTO {
    protected UUID id;
    protected Integer version;
    protected Date created;
    protected Date modified;
}

// 统一的用户DTO，既可用于请求也可用于响应
public class UserDTO extends BaseResponseDTO {
    private String firstName;
    private String lastName;

    // Getters and Setters (省略)
    // 构造函数 (省略)
}

这种方法的工作原理和优势：

请求时： 当 UserDTO 被用作请求体时，客户端只需发送业务字段（firstName, lastName）的数据。Spring Boot（或Jackson库）在反序列化时，会自动忽略请求JSON中未提供的 id, version 等 BaseResponseDTO 字段，而不会报错。
```
// 客户端发送的请求体示例
{
    "firstName": "John",
    "lastName": "Doe"
}
```
后端接收到此JSON后，UserDTO 实例的 firstName 和 lastName 将被填充，而 id, version 等字段将保持其默认值（例如 null）。

响应时： 当 UserDTO 被用作响应体时，后端在返回数据前，会为 id, version, created, modified 等字段填充实际值，然后将其序列化为完整的JSON响应。

// 后端返回的响应体示例
{
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "version": 1,
    "created": "2023-01-01T10:00:00Z",
    "modified": "2023-01-01T10:00:00Z",
    "firstName": "John",
    "lastName": "Doe"
}

消除代码冗余： firstName 和 lastName 只定义了一次，极大地减少了重复代码。
简化客户端交互： 客户端无需在请求中添加额外的包装字段（如 payload），直接发送业务数据即可。
提高可维护性： 字段变更只需在一个地方修改，降低了出错的风险。

实现细节与注意事项

Jackson的默认行为： Spring Boot默认使用的Jackson库在JSON序列化和反序列化时，对于DTO中存在但JSON中缺失的字段，会默认忽略；对于JSON中存在但DTO中缺失的字段，也会默认忽略。这正是上述方案能够成立的基础。如果需要更严格的校验，例如不允许请求体中出现任何未定义的字段，可以通过Jackson的 DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES 配置来控制。
适用场景： 这种模式最适用于请求和响应的核心业务数据结构高度相似，且响应仅比请求多出一些通用元数据的情况。
不适用场景： 如果请求和响应的数据结构差异巨大，或者请求和响应的业务逻辑完全不同，那么强行使用一个统一的DTO可能会导致DTO过于臃肿或职责不清。在这种情况下，保持分离的DTO可能更为合适。
数据验证： 在Spring Boot中，通常会结合 @Valid 注解和JSR 303/380 Bean Validation API进行数据验证。在统一DTO的场景下，验证规则可以直接定义在 UserDTO 中。例如，可以对 firstName 和 lastName 添加 @NotBlank 等注解。
```
public class UserDTO extends BaseResponseDTO {
    @NotBlank(message = "First name cannot be blank")
    private String firstName;
    @NotBlank(message = "Last name cannot be blank")
    private String lastName;
    // ...
}
```
在控制器方法中，使用 @RequestBody @Valid UserDTO userDTO 即可触发验证。

总结

通过采用统一的DTO并结合继承基类的方式来处理请求与响应，我们能够有效解决RESTful API中DTO代码冗余的问题。这种设计模式不仅简化了DTO结构，提高了代码的可维护性，也优化了客户端与API的交互体验。在设计API时，应根据实际业务场景权衡，选择最能体现简洁性、可读性和可维护性的DTO结构。

本篇关于《RESTfulAPI设计：精简DTO提升开发效率》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！