Spring Boot 接口协议设计实战：Entity-Param-DTO如何划边界

Spring Boot 接口协议设计实战：Param、DTO 与 Entity 的边界

问题现场： REST 接口直接接收或返回数据库 Entity，短期能少写几个类，长期却会把表结构变成对外契约。一次字段新增、重命名或关联加载，都可能无意间改变接口。

企业系统还要面对批量赋值、敏感字段泄露、前后端版本兼容和内部模型演进。Param、DTO 与 Entity 的价值不是“分层形式”，而是分别控制可写字段、可见字段和持久化字段。

MetaLite 在外部请求、内部业务参数和响应对象之间保留明确转换点。本文先用接口演进问题说明为什么 Entity 不能成为协议，再结合 MetaLite 的参数与响应写法验证这些边界。

一、请求为什么应该使用 Param

创建用户与更新用户即便字段相似，也不代表调用方可以提交 Entity 的全部属性。

例如数据库实体可能包含：

• 主键与审计时间；
• 密码摘要或内部状态；
• 乐观锁版本；
• 只允许系统计算的字段。

使用 SaveSysUserParam 可以只开放业务允许修改的字段，并通过 Jakarta Validation 描述输入约束。接口契约不会因为数据库新增一列而自动扩大。

MetaLite 还提供 StringIdParam、IntIdParam、LongIdParam 等小参数模型，避免为了删除操作接收一个字段过多的实体。

二、响应为什么应该优先使用 DTO

DTO 的价值不是换一个类名，而是建立输出白名单。用户详情、用户列表和登录结果需要的字段不同，应该分别定义响应模型。

如果直接返回 Entity，常见风险包括：

• 新增数据库字段后被 JSON 自动输出；
• 内部状态或密钥类字段意外泄露；
• 表字段重构迫使外部接口同步变化；
• 同一实体在不同场景只能依赖复杂的序列化忽略规则。

DTO 让接口兼容性由业务契约决定，而不是由表结构决定。

三、Entity 应该停留在哪一层

较清晰的流向是：

Controller Param
  → Service
  → Entity / DAO
  → Service DTO
  → Resp<DTO>

Entity 可以在 Service 与 DAO 之间流动。跨公网、跨微服务或进入前端之前，应评估是否转换为 DTO。

这不是绝对禁止任何内部接口传 Entity，而是要求团队明确耦合成本和字段暴露范围。

四、MetaLite 的 BeanConverter 解决什么

模型隔离经常被反对，因为转换代码太多。MetaLite 的 BeanConverter 与 PropertyConverter 支持 Bean、Map 等属性转换，并缓存转换路径，减少手工 setXxx。

但自动转换只能搬运同名或可转换属性，不能替团队决定：

• 哪些字段可以输出；
• 枚举如何解释；
• 嵌套对象如何组装；
• 多表字段如何聚合；
• 敏感字段是否应该存在于 DTO。

转换工具降低机械成本，不替代接口设计。

五、当前源码为什么必须诚实说明尚未完全隔离

MetaLite 已定义 Param、Dto、Entity，但当前 SysUserApi 等部分接口仍返回：

Resp<SysUserEntity>
Resp<PageResultDto<SysUserEntity>>

甚至 getUserDtoByUserId 的方法名返回类型仍是 SysUserEntity。这意味着语义模型已经建立，输出隔离尚未在所有管理接口完成。

准确的宣传应是：框架提供了分层基础和转换能力，并在持续收紧边界；不能仅凭三个标记接口就宣称数据库实体从未跨层。

这也是源码型文章最重要的可信度：不仅讲设计亮点，也指出设计与当前实现之间的距离。

六、是不是所有接口都要创建很多类

不需要机械地“一接口六个类”。可以按变化和风险决定：

• 单 ID 删除：复用通用 ID Param；
• 无数据成功：返回 Resp<Void>；
• 稳定的下拉选项：复用 SelectOptionDto；
• 分页结构：复用 PageResultDto<T>；
• 业务字段不同或含敏感数据：定义专用 Param/DTO；
• 内部短生命周期接口：可适度复用，但记录耦合边界。

复用的是稳定协议结构，不是把数据库实体当万能对象。

七、更新接口尤其不能直接绑定 Entity

全字段 Entity 更新容易产生“未提交字段被覆盖为空”的问题，也容易让调用方修改本不该修改的状态。

Param 应表达允许更新的字段，Service 再读取旧实体、校验业务规则并执行明确更新。MetaLite ORM 支持实体差异比较和按字段更新，但底层能力仍需要正确的接口白名单配合。

八、如何逐步改造已有接口

不必一次重写所有模型，可以按风险排序：

1. 密码、Token、密钥、身份信息相关接口先改 DTO；
2. 对外开放 API 与跨团队接口优先隔离；
3. 高频变更表对应的接口优先隔离；
4. 为 Entity 输出增加自动化字段检查；
5. 再逐步处理低风险后台列表。

MetaLite 的下一步也应是让现有 Resp<Entity> 逐步收敛到面向场景的 DTO，而不是只保留类型名称上的分层。

九、用一次字段污染验证 Param、DTO 与 Entity

最容易暴露边界问题的不是查询，而是更新。假设用户资料表新增了内部字段 status 和 userType，前端仍提交旧页面参数。如果 Controller 直接绑定 SysUserEntity，调用方可以在请求中额外构造这两个字段；后续只要出现一次“整对象保存”，内部字段就可能被越权覆盖。

可执行的回归测试应至少包含三组断言：

1. SaveSysUserParam 不声明的字段无法进入业务更新集合；
2. BeanConverter 只转换显式契约允许的属性，转换后仍由 Service 决定哪些字段可写；
3. 响应使用 DTO，数据库新增字段后不会自动暴露给外部调用方。

这也是 Param 和 DTO 的真正价值：不是为了让类名更多，而是让数据库字段演进不会无意改变外部 API。

框架简介
MetaLite 是面向企业生产环境的新一代 Java 微服务技术底座。系列文章重点分享代码背后的设计思路、技术取舍与工程实践。

源码基线
JDK 21、Spring Boot 3.2.9、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.3，具体组件版本以项目 backend-bom 为准。

作者简介
15 年 Spring 体系企业级开发经验，专注于 Java 微服务架构、工程治理与生产实践。

持续更新
MetaLite 系列内容将持续更新，围绕核心设计、源码链路、技术取舍与生产实践展开。欢迎关注作者，及时获取后续内容。

在线演示
演示地址: https://admin.metalite.top/
演示账号: guess
演示密码: admin@2026