Java Record 作为 API DTO 时，校验逻辑放在哪里

把 Java Record 用作 API DTO 后，最容易出现的争论就是：校验应该写在 Record 构造器里，还是交给 Jakarta Validation，或者干脆放进 Service？我的判断是先按规则的“稳定边界”分层：字段格式交给组件约束，Record 自己必须满足的不变量放进紧凑规范构造器，跨字段和外部状态规则留在应用层。这样既能让 DTO 保持可信，也不会让一个短小的 Record 偷偷承担数据库和业务流程。

先区分四类校验，不要只看代码长短

我在设计 DTO 时会先问三个问题：这条规则只依赖当前参数吗？对象离开接口层后仍然必须成立吗？判断它是否成立需要查库或调用服务吗？答案不同，落点也不同。

Record 自身的不变量放在紧凑规范构造器

Record 的规范构造器天然是对象边界。Java 官方文档也把“校验构造器参数、复制可变组件或归一化值”列为显式规范构造器的典型用途。比如用户名去掉首尾空格后仍为空，或者金额小于零，这些规则不应该等到 Service 的某个分支才发现。

// 构造完成后，用户名和金额始终满足本对象的基本不变量
public record CreateOrderDto(String username, BigDecimal amount) {
    public CreateOrderDto {
        // 归一化只处理当前对象的数据，不访问数据库或远程服务
        username = username == null ? null : username.trim();
        if (username == null || username.isEmpty()) {
            throw new IllegalArgumentException("username 不能为空");
        }
        // 金额的非负性是订单输入对象自身可以判断的规则
        if (amount == null || amount.signum() 

这里的边界是“无论谁 new 这个对象都不能违反”。但不要把数据库唯一性、库存是否足够、当前用户是否有权限写进构造器；这些判断依赖外部状态，也会让反序列化和单元测试变得难以控制。

请求格式交给组件约束与入口校验

“不能为空”“长度不超过 64”“必须是正数”通常属于 API 输入契约。Jakarta Validation 3.1 已明确补充对 Record 的支持，可以把约束写在组件上，再由接口入口统一调用 Validator。这样错误能保留字段路径和消息，也不会把 HTTP 展示格式混进领域对象。

// 组件注解描述 API 输入契约，入口层负责触发校验
public record RegisterRequest(
        @NotBlank(message = "邮箱不能为空")
        @Email(message = "邮箱格式不正确")
        String email,
        @Size(min = 8, max = 64, message = "密码长度应为 8 到 64")
        String password) {
}

// 统一收集违反项，再转换成接口需要的错误结构
Set> violations = validator.validate(request);
// violations 为空才继续进入应用服务，避免把无效 DTO 向下传递

构造器仍可做 null 防御，但不要为了“看起来校验完整”而同时在构造器和注解里复制十几条规则。重复规则一旦修改，很容易出现消息不同、边界不同和测试只覆盖一处的问题。

跨字段规则和外部依赖不要塞进 DTO

开始日期不能晚于结束日期，通常是两个字段共同组成的业务条件。它可以在应用服务中写成清晰的校验方法；如果项目已经统一使用 Bean Validation，也可以定义类型级约束，把错误挂到对象级路径。两种方式都比在构造器里抛一个模糊的 IllegalArgumentException 更容易映射为接口错误。

用户名是否重复、订单是否超过额度、操作者是否能修改资源，则必须读取数据库或权限上下文。这些规则会随外部状态变化，推荐在应用服务先做输入校验，再做业务校验，并把冲突转换成可读的领域错误。DTO 只携带请求数据，不负责打开连接、调用远程接口或决定事务。

我的选择清单：四个判断足够落地

1. 只看一个字段且是输入格式：组件注解。
2. 对象一创建就永远不能违反：紧凑规范构造器。
3. 需要两个以上字段或业务语义：应用服务或类型级约束。
4. 需要数据库、权限、时间或远程状态：应用服务，并保留可定位的错误码。

最后再决定错误呈现方式：客户端需要字段级提示，就让入口校验收集 ConstraintViolation；业务冲突则返回稳定的领域错误。Record 的价值是简洁、不可变和清晰的数据承载，不是把整个业务层压缩进一段构造器。

常见问题

Record 构造器里能不能直接加 @NotNull？

可以声明约束，但项目要确认验证器实际触发了构造器或对象校验。对 API DTO 来说，组件注解配合入口统一 validate 通常更直观。

跨字段校验一定要自定义注解吗？

不一定。规则很少时应用服务中的命名方法更容易读；需要复用、统一消息和元数据时，再考虑类型级约束。

为什么不把所有检查都放到 Service？

Service 适合业务和外部状态，但对象自身的不变量若只在某个入口检查，其他创建路径可能绕过它。稳定的局部规则应在更靠近对象的边界完成。