Java record 怎样自定义规范化构造器

Java record 想在创建对象时做参数校验、去掉首尾空白、统一大小写或补齐默认值，应该自定义它的规范化构造器（canonical constructor）。最常用的写法是紧凑构造器：只写 public User { ... }，参数列表和字段赋值由编译器根据 record 头部补全。

官方地址：https://docs.oracle.com/en/java/javase/26/language/records.html

把所有输入约束放在 canonical constructor，优先用紧凑构造器完成简单的参数重写与校验；如果需要明确控制字段赋值、异常分层或多步计算，再写完整的显式构造器。其它构造器必须通过 this(...) 回到这条规范化路径。

规范化构造器到底约束什么

record 头部写出的组件决定了它的状态形状。例如：

public record UserId(String value) {
    // 规范化构造器的参数必须与 record 组件保持同一组分量。
    public UserId {
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("value 不能为空");
        }
        value = value.trim().toLowerCase(java.util.Locale.ROOT);
    }
}

这里的 UserId(String) 就是 canonical constructor。它的签名由 record UserId(String value) 决定，不是任意参数列表的普通构造器。紧凑构造器末尾会把经过修改的形式参数赋给 record 的私有 final 组件字段，因此示例中的 value = ... 是规范化输入，而不是给字段重新赋值。

最小配方：在紧凑构造器中规范化输入

对字符串、范围和枚举这类值对象，紧凑构造器通常已经足够。下面的例子把用户名统一为小写，并拒绝空值和过长输入：

import java.util.Locale;

public record AccountName(String value) {
    public AccountName {
        // 先拒绝 null，再去除两端空白，避免对 null 调用方法。
        if (value == null) {
            throw new IllegalArgumentException("用户名不能为 null");
        }
        String normalized = value.trim();
        if (normalized.isEmpty() || normalized.length() > 32) {
            // 规范化后的值才参与长度判断，规则与最终状态保持一致。
            throw new IllegalArgumentException("用户名长度必须在 1 到 32 之间");
        }
        // 紧凑构造器允许重写参数，末尾由编译器完成组件字段赋值。
        value = normalized.toLowerCase(Locale.ROOT);
    }
}

这里要注意两个顺序：先处理 null，再做 trim；先得到最终规范化值，再按最终值检查长度。这样对象一旦创建成功，value() 返回的就是业务约定的形态。

范围值校验：不要直接修改 record 字段

record 的组件字段是隐式生成的 private final 字段，不能在构造器中写 this.min = ... 来重新赋值。范围值可以在参数层面做换序或拒绝，最终由紧凑构造器统一落到字段：

public record PortRange(int start, int end) {
    public PortRange {
        // 端口范围必须落在合法区间内，先检查每个输入。
        if (start  65535 || end  65535) {
            throw new IllegalArgumentException("端口必须位于 1 到 65535");
        }
        if (start > end) {
            // 这里选择规范化为升序，而不是让调用方重复交换参数。
            int temporary = start;
            start = end;
            end = temporary;
        }
    }
}

如果业务语义要求调用方显式修正顺序，也可以把 start > end 改成抛异常。关键点是：修改的是形式参数，不能把 record 当作可变 JavaBean。

复杂规则再使用显式规范化构造器

当规范化需要多个临时变量、跨字段计算或不同异常信息时，可以完整写出 canonical constructor。完整构造器仍然必须覆盖所有组件，并在通过检查后为每个组件字段赋值：

import java.util.Locale;

public record Endpoint(String host, int port, String scheme) {
    public Endpoint(String host, int port, String scheme) {
        // 先准备局部变量，避免把半规范化状态写入不可变组件。
        String normalizedHost = host == null ? "" : host.trim().toLowerCase(Locale.ROOT);
        String normalizedScheme = scheme == null
                ? "http"
                : scheme.trim().toLowerCase(Locale.ROOT);
        if (normalizedHost.isEmpty()) {
            throw new IllegalArgumentException("host 不能为空");
        }
        if (!normalizedScheme.equals("http") && !normalizedScheme.equals("https")) {
            throw new IllegalArgumentException("scheme 只能是 http 或 https");
        }
        if (port  65535) {
            throw new IllegalArgumentException("port 超出范围");
        }
        // 显式 canonical constructor 必须完成每个组件的最终赋值。
        this.host = normalizedHost;
        this.port = port;
        this.scheme = normalizedScheme;
    }
}

完整写法的优点是边界清楚，缺点是字段赋值容易漏写或写错。能用参数重写解决的问题优先采用紧凑构造器；需要明确的中间状态时再升级为显式版本。

替代构造器必须回到 canonical constructor

有些调用方更方便传入一个整体字符串或另一个对象，这时可以增加非 canonical constructor，但它必须先调用 canonical constructor。下面的构造器把 host:port 转换后委托给统一入口：

public record ServiceAddress(String host, int port) {
    public ServiceAddress {
        // 所有入口最终共享同一组基础校验。
        if (host == null || host.isBlank()) {
            throw new IllegalArgumentException("host 不能为空");
        }
        if (port  65535) {
            throw new IllegalArgumentException("port 超出范围");
        }
        host = host.trim().toLowerCase(java.util.Locale.ROOT);
    }

    public ServiceAddress(String text) {
        // 第一条语句直接委托，拆分工作放到静态辅助方法中。
        this(parseHost(text), parsePortFromAddress(text));
    }

    private static String parseHost(String text) {
        // 替代入口只负责拆出 host，基础校验仍由 canonical constructor 完成。
        int separator = text == null ? -1 : text.lastIndexOf(':');
        if (separator 

Java 要求构造器调用 this(...) 出现在构造器体的第一条语句，所以解析动作放在静态辅助方法中。上面的分解保持了清晰职责：替代入口负责转换，canonical constructor 负责最终不变量。

反序列化为什么也值得放进判断范围

Oracle 文档说明，record 反序列化会调用 canonical constructor，而不是像普通可序列化类那样绕过目标类构造器后直接写入字段。这意味着把关键不变量放进 canonical constructor，不仅覆盖普通 new 调用，也能让反序列化数据经过同一条约束。

这并不等于可以省略版本兼容和异常处理。跨版本数据仍要考虑组件变化，构造器中的规则也应该保持稳定、明确，不要把依赖外部服务或随机状态的副作用放进去。

紧凑构造器和显式构造器怎么选

最后的判断标准

自定义 Java record 的规范化构造器，核心不是把普通类构造器语法搬过来，而是把“输入如何变成稳定状态”固定在 record 的 canonical constructor 上：

• 能直接检查和重写参数时，用紧凑构造器减少重复赋值。
• 需要完整控制中间值时，用显式构造器并逐一赋值。
• 增加其它入口时，先转换输入，再用 this(...) 委托。
• 不要把文件、网络或随机副作用塞进构造器，让对象创建保持可解释。

这样写出来的 record，调用方不需要记住每个入口的校验差异；只要对象成功创建，它的组件就已经处于约定好的规范化状态。

相关问题

• 紧凑构造器里为什么不用写 this.field = field？ 因为编译器会在构造器末尾把形式参数赋给对应组件字段。
• 能不能在 record 中声明普通实例字段保存临时值？ 不能；record 不允许额外的非 static 实例字段，临时值应放在构造器局部变量中。
• 替代构造器能不能自己重复做一套校验？ 可以做输入拆分和格式转换，但基础不变量应交给 canonical constructor，避免多入口漂移。
• 规范化构造器能不能返回 null？ 不能，构造器没有返回值；不合法输入应抛出明确异常，合法输入则完成不可变状态。