Java Record 构造校验与不可变字段设计

Record 的组件字段虽然是 private final，但这只保证字段引用不会被重新指向，并不自动保证引用对象本身不可变。设计一个可靠的 Record，通常要同时处理两件事：在规范构造器中建立对象不变量；对 List 这类可变输入做防御性复制。

官方规范：https://docs.oracle.com/en/java/javase/26/docs/specs/jls/jls-8.html#jls-8.10.4

一、先把 Record 的不变量写清楚

假设订单请求由购买者、商品编号集合和金额组成。可执行的规则应该具体到输入边界：购买者不能为空白；商品集合不能为空且不能含空元素；金额必须大于零。它们不是控制器层的临时检查，而是这个值对象一旦创建就必须成立的条件，因此应收口到构造入口。

Record 会为每个组件生成同名的组件字段和访问器。字段本身是 final，但如果组件类型是可变集合，调用方仍可能通过原集合引用改变其内容。把“字段不能重新赋值”误当成“对象深度不可变”，是 Record 设计里最常见的漏洞。

二、用紧凑规范构造器完成校验与规范化

紧凑规范构造器只写 Record 名称和构造器体，不重复组件参数列表。构造器体里的 buyerId、itemIds 和 amount 是隐式参数。可以校验它们，也可以把规范化后的值重新赋给这些参数；构造器正常结束后，编译器按组件声明顺序把参数写入字段。

import java.math.BigDecimal;
import java.util.List;
import java.util.Objects;

public record OrderRequest(
        String buyerId,
        List itemIds,
        BigDecimal amount) {

    public OrderRequest {
        // 先拒绝 null，再去掉标识两端无意义的空白。
        buyerId = Objects.requireNonNull(buyerId, "buyerId 不能为空").strip();
        if (buyerId.isEmpty()) {
            throw new IllegalArgumentException("buyerId 不能为空白");
        }

        // copyOf 同时拒绝 null 元素，并保存独立的不可修改快照。
        itemIds = List.copyOf(Objects.requireNonNull(itemIds, "itemIds 不能为空"));
        if (itemIds.isEmpty()) {
            throw new IllegalArgumentException("itemIds 至少包含一项");
        }

        // 金额是值对象，校验范围后再统一小数表示。
        amount = Objects.requireNonNull(amount, "amount 不能为空");
        if (amount.signum() 

这里不要写 this.buyerId = buyerId。Java 语言规范禁止在紧凑构造器中给组件字段赋值，因为隐式字段初始化由编译器完成。参数规范化与字段初始化分开，正是紧凑形式减少重复代码的关键。

三、不可变字段不等于深度不可变

List.copyOf 解决的是集合容器别名问题：调用方之后向原列表添加商品，不会改变 Record 保存的快照；通过访问器取得的列表也不能直接增删。但它是浅复制。如果列表元素是可变的 Product 对象，元素内部状态仍可能变化。

因此组件类型最好也是不可变值，例如字符串、枚举、BigDecimal 或另一个经过同样约束的 Record。确实要保存可变元素时，应在构造器中逐个转换为不可变快照，而不是只复制外层列表。数组也有同样问题；Record 自动生成的数组访问器会返回数组引用，通常需要改成不可变集合，或显式复制输入和输出。

四、什么时候改用普通规范构造器

如果需要给参数添加与组件不同的构造器注解，或希望显式展示字段赋值，可以声明普通规范构造器。它的参数名称和类型必须与组件匹配，并由构造器自己完成全部字段赋值。对于单纯的校验和规范化，紧凑形式更短，也更不容易在新增组件后漏掉赋值。

public record Range(int start, int end) {
    public Range(int start, int end) {
        // 普通规范构造器要显式校验并给每个组件字段赋值。
        if (start > end) {
            throw new IllegalArgumentException("start 不能大于 end");
        }
        this.start = start;
        this.end = end;
    }

    public Range(int point) {
        // 非规范构造器必须先委托给同一 Record 的其他构造器。
        this(point, point);
    }
}

不要在辅助构造器里复制一套校验规则。让所有入口最终经过同一个规范构造器，才能保证新增入口不会绕过不变量。

五、测试校验失败和集合别名

只测访问器返回值还不够。至少覆盖合法输入、每条非法规则，以及“构造后修改原集合”这类别名场景。下面的 JUnit 5 示例集中验证最容易被漏掉的两条边界。

import static org.junit.jupiter.api.Assertions.*;

import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;
import org.junit.jupiter.api.Test;

class OrderRequestTest {
    @Test
    void shouldKeepIndependentItemSnapshot() {
        var source = new ArrayList(List.of("sku-1"));
        var request = new OrderRequest(" buyer-1 ", source, new BigDecimal("12.00"));

        // 修改调用方原列表，不应穿透 Record 保存的快照。
        source.add("sku-2");

        assertEquals("buyer-1", request.buyerId());
        assertEquals(List.of("sku-1"), request.itemIds());
        assertThrows(UnsupportedOperationException.class,
                () -> request.itemIds().add("sku-3"));
    }

    @Test
    void shouldRejectInvalidAmount() {
        // 非正金额在对象创建时立即失败，不把非法状态带到业务层。
        assertThrows(IllegalArgumentException.class,
                () -> new OrderRequest("buyer-1", List.of("sku-1"), BigDecimal.ZERO));
    }
}

测试目标不是证明 Record 语法能编译，而是证明所有构造路径都只能产出合法状态。若规范化会改变业务含义，例如用户标识是否允许去空格，应先把规则写进领域约定，再决定是否在构造器中转换。

相关问题

紧凑构造器可以给组件字段赋值吗？

不可以。紧凑构造器应校验或重写隐式参数，字段由编译器在构造器体正常结束后隐式初始化。

List.copyOf 能保证元素也不可变吗？

不能。它提供不可修改的外层列表快照，但不会深复制元素；可变元素仍要单独转换或复制。

Record 适合保存 JPA 实体吗？

Record 更适合边界清晰的值对象和数据传输对象。若对象依赖可变状态、延迟加载或框架代理，应先确认框架契约，不要只因为语法简短就强行改成 Record。