Java 后端 / 系统课时

使用 DTO 隔离接口模型

使用 DTO 隔离接口模型

本课完成请求 DTO、响应 DTO 与数据库实体的分离,并用显式转换建立稳定边界。完成后,控制器不再直接暴露持久化对象,字段变更、敏感信息隐藏和接口版本演进都会更可控。

学习目标

  • 区分请求 DTO、响应 DTO 与实体模型的职责
  • 编写可测试的 DTO 转换逻辑
  • 识别直接返回实体造成的接口风险

为什么不能直接暴露实体

数据库实体服务于持久化,通常包含主键、审计字段、逻辑删除标记、关联关系和内部状态;接口模型服务于客户端,关注可提交字段、展示字段与兼容性。两者变化节奏不同,直接共用会让数据库改表影响接口,也可能把密码摘要、内部状态等字段意外返回。

请求 DTO 只接收客户端允许写入的内容,响应 DTO 只暴露客户端需要读取的内容,实体则保留在应用内部。转换边界应位于应用服务或专用 Mapper 中,而不是散落在控制器与实体方法里。

DTO 与实体模型的隔离边界

定义请求与响应模型

下面的完整 Java 示例使用 record 定义不可变 DTO,并通过 Mapper 完成双向转换。实体中的 passwordHash 和 deleted 不会进入响应 DTO,客户端传入的 role 也不会被直接信任。

java
import java.util.UUID;

public class DtoIsolationDemo {
    public static void main(String[] args) {
        CreateUserRequest request =
                new CreateUserRequest("alice", "alice@example.com", "plain-text");

        UserEntity entity = UserMapper.toEntity(request);
        entity.id = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");

        UserResponse response = UserMapper.toResponse(entity);
        System.out.println(response);
    }

    record CreateUserRequest(String username, String email, String password) {}

    record UserResponse(UUID id, String username, String email) {}

    static final class UserEntity {
        UUID id;
        String username;
        String email;
        String passwordHash;
        String role;
        boolean deleted;
    }

    static final class UserMapper {
        static UserEntity toEntity(CreateUserRequest request) {
            UserEntity entity = new UserEntity();
            entity.username = request.username();
            entity.email = request.email();
            // 示例中简化哈希过程,真实项目应使用 PasswordEncoder。
            entity.passwordHash = "HASH(" + request.password() + ")";
            entity.role = "USER";
            return entity;
        }

        static UserResponse toResponse(UserEntity entity) {
            // 响应只选择公开字段,避免实体新增字段后被自动泄露。
            return new UserResponse(entity.id, entity.username, entity.email);
        }
    }
}

预期输出:

text
UserResponse[id=123e4567-e89b-12d3-a456-426614174000, username=alice, email=alice@example.com]

放置转换边界

在 Spring Boot 项目中,控制器应接收请求 DTO,并把业务调用结果转换为响应 DTO。Repository 只处理实体,避免 DTO 侵入持久化层。

java
@PostMapping("/users")
public UserResponse create(@RequestBody CreateUserRequest request) {
    UserEntity saved = userService.create(UserMapper.toEntity(request));
    return UserMapper.toResponse(saved);
}

这是片段示例,依赖已经定义的 UserService、UserMapper 和 DTO。接口成功时返回公开字段;实体中的密码摘要、角色和删除标记不会出现在 JSON 中。可通过接口测试断言响应不存在 passwordHash、role 和 deleted 字段。

处理更新与版本演进

创建、更新和查询通常应使用不同 DTO。更新 DTO 只包含允许修改的字段,不要把实体整体覆盖,否则客户端可能越权修改角色、状态或审计字段。接口需要升级时,可以新增 UserResponseV2 或独立转换器,在不改实体的前提下维护旧契约。

Mapper 应保持纯转换,复杂业务规则放在 Service 中。例如“普通用户不能修改角色”属于授权规则,不应隐藏在字段复制代码里。项目较小时可手写 Mapper;字段较多时可使用 MapStruct,但仍需显式忽略敏感字段并编写映射测试。

验收检查

完成实现后,至少验证三点:请求 JSON 中的额外字段不会写入实体;响应 JSON 不包含内部字段;实体新增数据库列时,现有接口响应保持不变。这样才能证明 DTO 真正形成了隔离层,而不是仅换了类名。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 DTO 隔离接口模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通