Java record 需要自定义校验时怎么写紧凑构造器

Java record 需要自定义校验时，最简洁的做法是在 record 体内声明紧凑构造器（compact constructor）。它不重复写参数列表，方法体里的 value、name 等标识符代表隐式构造参数；方法正常结束后，编译器再把这些参数写入组件字段。

从普通构造器迁移到 record：校验放在哪里

普通类通常在构造器中手动保存字段：先接收参数，再执行校验，最后写入 this.field。record 的规范构造器仍然存在，但可以改成紧凑形式。它的参数由 record 头部自动推导，因此适合承载“这个值能不能进入对象”和“进入前是否需要标准化”这两类逻辑。

迁移时有三个边界需要先记住：紧凑构造器只能在 record 中声明；同一个 record 不能同时声明普通规范构造器和紧凑构造器；如果 record 是 public，显式规范构造器也必须至少是 public。

紧凑构造器的写法：校验和归一化都改参数

下面的例子把用户编号统一去掉首尾空白，并拒绝空值。注意构造器名字后面没有圆括号，这就是紧凑形式。value 是隐式参数，不是已经初始化好的字段。

public record CustomerId(String value) {
    public CustomerId {
        // 先拒绝 null，再把外部输入归一化为稳定格式
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("customer id 不能为空");
        }
        value = value.trim();
        // 构造器正常结束后，编译器会把 value 写入组件字段
    }
}

范围检查也遵循同一套路，例如 record PageSize(int value) 中判断 1 到 100。不要在紧凑构造器里写 this.value = value，也不要写 return 或再次调用另一个构造器；这些都不符合紧凑构造器的语法约束。

浅不可变不是深拷贝：集合字段要自己处理

record 的组件字段是 final，record 本身也不能通过继承扩展，但这不代表组件对象的内部状态不可变。把 List 直接放进去后，调用方仍可能通过原列表改变 record 看到的内容。需要稳定快照时，在紧凑构造器里替换隐式参数：

import java.util.List;

public record UserProfile(String name, List roles) {
    public UserProfile {
        // List.copyOf 同时拒绝 null 元素，并返回不可修改的快照
        if (name == null || name.isBlank()) {
            throw new IllegalArgumentException("name 不能为空");
        }
        roles = List.copyOf(roles);
    }
}

这里保护的是列表容器，不是列表元素本身。如果元素也是可变对象，还要在边界层复制元素或改用不可变值对象。数组同理，不能只因为 record 字段是 final 就省略数组复制。

反射读取 record 组件时检查什么

框架需要通用地读取 record 时，不要把“有几个 final 字段”当成 record 判断条件。先调用 isRecord()，再读取 RecordComponent 数组，组件顺序就是 record 头部声明顺序。

import java.lang.reflect.RecordComponent;

static void printRecordShape(Class> type) {
    // 先确认类型身份，避免把普通类误当成 record
    if (!type.isRecord()) {
        throw new IllegalArgumentException("不是 record 类型");
    }
    for (RecordComponent component : type.getRecordComponents()) {
        // name 和 type 用于建立字段映射或序列化描述
        System.out.println(component.getName() + ": " + component.getType().getName());
    }
}

反射只能告诉你组件的声明结构，不能替代构造器的业务校验。框架创建实例时，仍应通过规范构造器传入已准备好的值；如果校验失败，应让异常回到调用方，而不是悄悄绕过 record 的构造约束。

迁移回归清单

• 空值、空白值、范围边界和归一化后的访问器结果是否符合预期。
• 构造器访问级别是否不低于 record 类，是否误写了第二个规范构造器。
• List、数组和可变元素是否需要复制；复制后 equals、序列化和日志输出是否仍稳定。
• 反射代码是否使用 isRecord() 和 getRecordComponents()，并覆盖普通类输入。

常见问题

紧凑构造器里能直接给 record 字段赋值吗？

不能。应给同名隐式参数赋值，构造器正常结束后由编译器完成字段初始化。

record 的 List 组件天然不可变吗？

不是。record 只提供浅不可变语义；需要隔离外部列表时使用 List.copyOf 或其他明确的快照策略。

普通构造器和紧凑构造器能同时存在吗？

不能同时作为同一个 record 的规范构造器。需要额外参数的构造器可以存在，但必须委托到规范构造器。

官方语义可对照 Java Language Specification 8.10.4.2 的 Compact Canonical Constructors，以及 Java SE 25 的 Record 和 RecordComponent API 文档。