Java Record 自定义构造器如何保持参数校验

Java Record 的参数校验最好放在规范构造器里，而不是散落在工厂方法、Controller 或多个重载构造器中。最简洁的做法是使用 compact constructor：先把参数校验和规范化写完，再让 Record 自动完成组件字段赋值。这样无论调用方直接传入什么值，对象创建时都会经过同一条边界。

把“对象一旦创建就必须合法”当成 Record 的不变量：空值、空白、格式和范围在规范构造器中一次处理；其他构造器只负责转换输入并委托给它。

先把 Record 的不变量放进规范构造器

Record 声明头中的组件列表决定了规范构造器的参数顺序。使用 compact constructor 时不必重复写参数列表，也不能在构造器体里直接给组件字段赋值；应当修改同名参数，Record 会在构造器结束时完成隐式赋值。

public record SignupCommand(String username, String email, int age) {
    public SignupCommand {
        // 先统一处理空白，避免校验通过后组件里仍保存脏值
        username = requireText(username, "username");
        email = requireText(email, "email").toLowerCase(Locale.ROOT);

        // 这里守住对象自身的不变量，调用方无需重复猜测范围
        if (!email.contains("@")) {
            throw new IllegalArgumentException("email 格式不正确");
        }
        if (age  120) {
            throw new IllegalArgumentException("age 必须在 18 到 120 之间");
        }
    }

    private static String requireText(String value, String field) {
        // 把 null、空串和全空白统一成一种失败语义
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException(field + " 不能为空");
        }
        return value.trim();
    }
}

这里的校验顺序是有意安排的：先处理 null 与空白，再做格式和范围判断。组件最终保存的是清洗后的 username 和小写 email，而不是调用方原始输入。若业务规则更复杂，可以把 requireText 换成独立的纯函数，但入口仍应保持在规范构造器。

重载构造器不能绕开同一条校验路径

如果需要提供“只传邮箱”和“从表单对象转换”之类的便利入口，额外构造器属于非规范构造器。Java 要求它先调用另一个构造器；对 Record 来说，最稳妥的写法是直接委托给规范构造器。

public record UserProfile(String username, String email, int age) {
    public UserProfile {
        // 所有入口最终都会到达这里
        username = requireText(username, "username");
        email = requireText(email, "email");
        if (age 

不要在两个构造器中各写一套 if。一旦后续把年龄上限、邮箱格式或用户名长度改掉，复制的分支很容易只改一处，结果是同一个 Record 根据入口不同表现不同。构造器的职责可以这样分：

先规范化，再做格式和业务范围判断

参数校验最容易出错的地方不是语法，而是顺序。比如先用 isBlank() 判断再 trim()，会把空白输入正确拦下；先转小写再检查邮箱格式，可以让比较规则稳定。每个字段都应写出自己的边界，避免一个“万能校验器”把不同业务语义混在一起。

需要注意，Record 的校验只保证 Java 对象通过构造器时的状态。如果对象来自 JSON 反序列化、数据库映射或参数绑定，还要确认使用的框架确实调用了规范构造器；框架层的 @NotBlank 等声明式校验适合生成请求提示，但不应成为唯一防线。对象自身的关键不变量仍应在构造边界收口。

用检查清单确认参数校验没有旁路

改完构造器后，可以按下面的清单做一次快速复查：

1. 直接调用规范构造器时，null、空白、非法格式和越界值是否都能得到明确异常？
2. 所有非规范构造器是否第一行就通过 this(...) 委托？
3. 清洗后的值是否真的赋回同名参数，而不是只在局部变量里计算？
4. 构造器内部是否没有网络、数据库或写日志之外的副作用？
5. 请求层的提示是否与 Record 的最终不变量一致，避免前端通过但对象创建失败？

如果参数来自外部边界，异常消息不宜直接包含敏感输入。可以保留字段名和失败原因，把原始值交给调用方的结构化日志或追踪系统处理。这样既能快速定位问题，又不会把邮箱、手机号等数据写进普通错误响应。

常见问题

compact constructor 能手动给 Record 字段赋值吗？

不能。应修改隐式参数，构造器结束后由 Java 把参数写入对应组件字段；直接赋值组件字段会触发编译错误。

非规范构造器可以不做校验吗？

可以不重复校验，但必须委托到规范构造器。它只负责补默认值或转换输入，不能通过另一条路径创建绕过不变量的对象。

只用 Bean Validation 注解够不够？

如果对象可能在没有请求校验器的地方被直接创建，就不够。注解适合请求层提示，Record 规范构造器适合守住对象自身必须成立的条件。