Java16 record 完整拆解——语法、语义、限制、反射

Java16 record 完整拆解------语法、语义、限制、反射

一句话结论：record 不是"少写几个 getter"的语法糖，而是把「类 = 透明的数据载体」升格为语言级契约------状态清单写进声明头，equals/hashCode/toString 由编译器按统一语义代工，反射与模式匹配都以这份声明为元数据。本文以我自己的项目 heart-net 里 grep 实测的 43 处 record 声明为样本，从基本语法一路吃到反射翻车现场，所有运行输出、反编译结果、编译器报错都是真机抓取，非杜撰。

写这篇文章的起因：翻自己的学习笔记，发现关于 record 的几条记载是错的（字段可见性、静态字段、私有构造器------后文 §3.5 逐条对账）。一个用了两年、在项目里写了 43 个 record 的人，笔记里仍然躺着以讹传讹的说法------这本身就说明了这个特性"看着简单"的欺骗性，也说明值得把它认真拆一遍。

先看全景图：

0. 引子：同一个项目里，一个 98 行，一个 1 行

不谈历史，先看我自己项目里真实并存的两段代码。

heart-net 的提示词治理落地时，同一片代码区出现了新旧两种写法的"化石分层"。旧的：ORM 实体 PromptTemplateDO------7 个字段，加上手写的 getter/setter、注释和 @TableName 注解，98 行 ，每一行都要人肉维护。新的：模板资产 LoadedPrompt，一行：

/** 单个模板资产：key / 全文 / 内容指纹（SHA-256 前 6 字节十六进制） */
public record LoadedPrompt(String key, String template, String hash) { }

公平起见，record 也不是魔法。如果不用 record，把 LoadedPrompt 按最普通的 IDE 风格手写出来，是下面这个样子（我逐行数过，49 行）：

public final class LoadedPrompt {

    private final String key;
    private final String template;
    private final String hash;

    public LoadedPrompt(String key, String template, String hash) {
        this.key = key;
        this.template = template;
        this.hash = hash;
    }

    public String key() {
        return key;
    }

    public String template() {
        return template;
    }

    public String hash() {
        return hash;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (!(o instanceof LoadedPrompt that)) {
            return false;
        }
        return key.equals(that.key)
                && template.equals(that.template)
                && hash.equals(that.hash);
    }

    @Override
    public int hashCode() {
        return Objects.hash(key, template, hash);
    }

    @Override
    public String toString() {
        return "LoadedPrompt[key=" + key
                + ", template=" + template
                + ", hash=" + hash + "]";
    }
}

49 行手写类对 1 行 record，这就是绝大多数人对 record 的第一印象：代写样板代码。这个印象没错，但只对了一半------它解释不了为什么编译器"敢"替你生成 equals，也解释不了后面反射和模式匹配为什么把 record 当一等公民。带着这个疑问往下拆。

（细节控注：上面手写版里我顺手用了 o instanceof LoadedPrompt that，这是 Java 16 同期定稿的另一个特性------模式匹配 instanceof，JEP 394。Java 16 一次发了两个改变写法的 JEP，record 只是其中之一。）

1. record 本身：声明头就是全部状态

1.1 语法解剖

record 的完整语法：访问修饰符 record 名字(组件列表) { 可选的类体 }。括号里不再是构造器参数，而是记录组件（record component） ------这是理解 record 的关键词：组件既是字段、又是构造器参数、又是访问器方法名，三位一体。

用项目里真实的 ReasoningRequest 看（推理模式的请求对象）：

/**
 * 推理模式请求（{@link ReasoningMode#run} 入参）。
 *
 * @param message     用户消息（进入路由前已判非空）
 * @param sessionId   会话标识（模式锁定在会话窗维度：切换模式 = 新会话，前端保证）
 * @param workDirRel  任务绑定工作目录（根内相对路径，null = 未绑定；
 *                    纯提示类模式无文件工具域，恒传 null）
 * @param modeParams  模式参数袋（可为 null）
 */
public record ReasoningRequest(String message, String sessionId,
        String workDirRel, Map<String, Object> modeParams) {

    /** 取整型参数（缺失/非法返回默认值；钳制上下界防误配） */
    public int intParam(String key, int defaultValue, int min, int max) {
        ...
    }
}

注意两件事：

1. javadoc 直接写在头部组件上 ------@param message 文档化的是组件，不是方法参数。record 出现之前，"给字段写文档"要靠字段注释 + getter 注释两处贴；现在一份 @param 跟着声明头走，我的项目里所有 record 都遵循这个惯例。
2. 类体不是空的 ------record 允许往里加方法（这个后面 §5 展开）。intParam 就是一个活生生的例子：数据载体本身也可以长出行为。

1.2 编译器代工五件套：javap 实证

"编译器帮你生成了构造器、访问器、equals、hashCode、toString"------这话谁都会说，验证它只需要一条命令。对项目里 LoadedPrompt 的编译产物执行 javap -p：

$ javap -p target/classes/com/suyou/heartnet/prompt/PromptTemplateRegistry\$LoadedPrompt.class
Compiled from "PromptTemplateRegistry.java"
public final class com.suyou.heartnet.prompt.PromptTemplateRegistry$LoadedPrompt extends java.lang.Record {
  private final java.lang.String key;
  private final java.lang.String template;
  private final java.lang.String hash;
  public com.suyou.heartnet.prompt.PromptTemplateRegistry$LoadedPrompt(java.lang.String, java.lang.String, java.lang.String);
  public final java.lang.String toString();
  public final int hashCode();
  public final boolean equals(java.lang.Object);
  public java.lang.String key();
  public java.lang.String template();
  public java.lang.String hash();
}

反编译结果信息量很大，逐条读：

生成的成员	细节	值得注意的点
字段	private final String key; × 3	字段是 private final，不是 public（常见讹传之一）
规范构造器	全参数、逐字段赋值	官方名"规范构造器"（canonical constructor）
访问器	key()、template()、hash()	没有 get 前缀，方法名 = 组件名
equals + hashCode	按全部组件生成	两个都是 final 方法------不许你重写
toString	类名[组件=值, ...] 格式	同样是 final 方法

用一张图概括编译器的分工：

flowchart TD A["record LoadedPrompt --- 组件：key、template、hash"] --> B["javac 编译器"] B --> C1["private final 字段 × 3"] B --> C2["规范构造器：全参数逐字段赋值"] B --> C3["访问器 × 3：方法名等于组件名，无 get 前缀"] B --> C4["equals 与 hashCode：按全部组件生成，final 方法"] B --> C5["toString：类名加组件键值对，final 方法"]

再看带方法的 ReasoningRequest，用户自己写的方法和编译器生成的方法平权共存，javap 一目了然：

public final class com.suyou.heartnet.reasoning.ReasoningRequest extends java.lang.Record {
  private final java.lang.String message;
  private final java.lang.String sessionId;
  private final java.lang.String workDirRel;
  private final java.util.Map<java.lang.String, java.lang.Object> modeParams;
  public com.suyou.heartnet.reasoning.ReasoningRequest(...);
  public int intParam(java.lang.String, int, int, int);      ← 我写的
  public java.lang.String strParam(java.lang.String, java.lang.String);   ← 我写的
  public java.lang.Long longParam(java.lang.String);         ← 我写的
  public final java.lang.String toString();                  ← 编译器代工
  public final int hashCode();                               ← 编译器代工
  public final boolean equals(java.lang.Object);             ← 编译器代工
  public java.lang.String message();                         ← 编译器代工
  ...（其余 3 个访问器）
}

1.3 运行现场

把 LoadedPrompt 抄进 jshell 跑一遍，五个行为全部实锤：

[toString] LoadedPrompt[key=system-chat, template=你是藏书阁, hash=a1b2c3]
[equals]  true
[hashA]   a15e90b
[hashB]   a15e90b
[accessor-no-get] system-chat
[component] key -> String
[component] template -> String
[component] hash -> String
[isRecord] true

逐条对应：toString 是 类名[key=值, template=值, hash=值]；两个内容相同的实例 equals 为 true、哈希一致；访问器 key() 直接返回组件值；反射能按组件遍历出字段名和类型。

1.4 语义契约：三句话讲完 record 的哲学

如果只记三件事，记这三件：

1. 状态透明：对象的全部状态就写在声明头上，没有藏起来的实例字段（§6 会讲到，这是强制约束）。
2. 身份 = 状态：两个 record 相等，当且仅当全部组件相等。相等不再是一个"由你负责写对"的方法，而是类型定义的一部分。
3. 形态封死：record 隐式 final，不能被继承。透明的东西不允许在背后加状态。

这三条互相咬合，才换来编译器敢替你生成 equals------因为它能拍胸脯保证"声明头就是全部状态"。普通类的 equals 之所以让人生疑，不是因为难写，而是因为没有任何机制保证它覆盖了全部字段、且未来不被子类加字段破坏。record 用契约消灭了这个信任问题。

顺带解释一个常见困惑："record 是不是就是语法糖，编译完跟手写类没区别？"------一半对。字节码层面它就是一个普通的 final 类（javap 已证），但它的类层次挂在 java.lang.Record 上，并且 class 文件里带组件元数据（后面 §7 的反射和 §8 的模式匹配都靠它）。糖是真的，但糖之外还有一张"身份证"。

2. 深度理解 immutable：final 字段 ≠ 不可变

2.1 浅不可变

record 的组件字段全是 final，没有 setter，创建之后引用不能换------这是不是就是"不可变对象"？是，但只是浅不可变 。看项目里 DeepDocService 的真实声明：

/** 节结果：index 大纲序；text 节正文；references 节内引用清单。
 * references 按节局部收集，规避共享 List 的并发写。
 */
private record SectionResult(int index, String text, List<Map<String, Object>> references) { }

references 是个 List。final 保证的是这个引用不能再指向别的 List ，但 List 内部照样能 add/remove------拿到同一个 record 实例的任何代码，都能改掉我手里的"节内引用"。上面 javadoc 里"按节局部收集，规避共享 List 的并发写"，就是这个风险在真实项目里的样子：record 挡住了引用层的篡改，挡不住内容层的。

2.2 防御性拷贝：紧凑构造器与显式访问器两处下手

想要内容也尽可能稳，record 提供两个官方位子。一是紧凑构造器（§5.1 详述），把可变容器在入口处拷贝定型：

record SectionResult(int index, String text, List<Map<String, Object>> references) {
    SectionResult {
        // 断掉与外部 List 的引用：外部后续 add/remove 不再影响本实例
        references = List.copyOf(references);
    }
}

二是显式重写访问器（注意：访问器不是 final 的，equals/hashCode/toString 才是------所以访问器可以自己实现）：

record SectionResult(int index, String text, List<Map<String, Object>> references) {
    @Override
    public List<Map<String, Object>> references() {
        return List.copyOf(references);   // 每次交付副本，改不到本体
    }
}

诚实提示：List.copyOf 是浅拷贝 ------List 结构被复制了，但里面的 Map 还是共享的。要彻底深不可变得递归拷到底，代价随之上升。我的项目里 SectionResult 最终选择的是第三条路：每节局部 new 一个 List，不共享，就不需要拷贝------并发场景下这比防御性拷贝更便宜。不可变这回事，record 给的是"引用层保底"，内容层的纪律还得自己立。

2.3 一个容易翻车的细节：编译器的 hashCode 不是 Objects.hash

手写类我惯用 Objects.hash(key, template, hash)；record 编译器生成的 hashCode 算法不同。实测同一组值：

[record hashCode] a15e90b
[Objects.hash  ] a165d6a

值不一样。这不是 bug，也不影响契约------哈希的契约只要求"相等对象哈希相等"，不要求跨实现同值。但如果你有"手动算哈希跟 record 比对"的代码（比如自造缓存键），这里会安静地错位。知道有这回事就好。

2.4 没有 setter 是契约，不是阉割

"不能改"听起来像损失，换个角度是收获：

• 身份稳定 ：既然 equals 由全部组件决定，而组件不可变，那么一个 record 放进 HashSet/HashMap 之后永远不会因为字段被改而"失联"（可变对象做 Map 键的经典事故源）。
• 线程安全免送：final 字段 + 安全发布语义（JMM 的 final 字段 guarantees），多线程共享不需要额外同步。
• 反序列化也走规范构造器 ：Java 原生反序列化 record 时，路径是"用流里的组件值调用规范构造器"，不是绕过构造器直接摆弄字段。你在紧凑构造器里写的校验，反序列化时同样生效------堵住了老式序列化"构造器校验被绕过"的注入漏洞。这是 JEP 395 明说的安全设计。（当然，原生序列化本身仍不推荐日常用，走 Jackson 更常见，§7.4 会看到框架全支持。）

3. 三代方案对比：手写 POJO、Lombok、record

3.1 主对比表

数据载体这个需求，Java 圈先后交出过三代答卷：

维度	手写 POJO	Lombok @Data	Lombok @Value	record
样板代码	全量手写	注解一步到位	注解一步到位	语言原生，无依赖
可变性	默认可变（setter 泛滥）	可变	不可变	不可变，契约级
equals/hashCode	人写，漏字段无人知	生成，但可变对象当键有坑	生成	生成 + final 封死
额外实例字段	随便加	随便加	可以加（自动 final）	禁止（唯一状态来源=声明头）
继承	可继承	可继承	可继承	隐式 final
反射元数据	无特殊语义	无特殊语义	无特殊语义	isRecord / RecordComponent
模式匹配（Java 21）	不支持	不支持	不支持	原生支持
环境依赖	无	注解处理器 + IDE 插件	同左	无，javac 内建
生效层级	源码	编译期织入	编译期织入	编译期 + 类元数据

几个表里看不出来的判断展开说：

3.2 record vs 手写 final class

如果你手写的类恰好做到了"全字段 final、全字段进 equals、类 final、无额外字段"------那它在字节码层面跟 record 几乎等价。差异只剩元数据：手写类反射不出"哪些是组件"，也永远吃不到模式匹配。"等价手写"这件事本身，就说明 record 没有引入任何运行时魔法------它把你"本该写对但经常写错"的东西标准化了。

3.3 record vs Lombok

@Value 是 Lombok 里最接近 record 的（全 final 字段 + final 类 + 全参构造），但两者有质差------Lombok 是"编译期帮你往类里塞方法"，产物是一个普通类；record 是"语言把数据载体的语义定成契约"，产物带着身份证。Lombok 能加额外实例字段这一点反而是它的优势------缓存派生值这种"字段不属于状态"的场景，record 做不到（§6） 。而 Lombok 的历史包袱（注解处理器与 JDK 升级的赛跑、早期 IDE 插件依赖）是 record 没有的。我的项目里两者共存：ORM 实体层继续 Lombok 风格（PromptTemplateDO 是纯手写 getter/setter），跨层数据全部 record------工具按场景分工，不搞宗教战争。

3.4 隔壁语言一眼

Kotlin data class / Scala case class 是 record 的"前辈"，都提供 copy()、解构。record 相比之下管得更严：不允许 var 组件、不提供语言级 copy（想要就自己写静态工厂，§5.4）。严格不是劣势------松紧背后是设计哲学：JVM 语言里 Java 选择把"透明不可变"焊死，把灵活性留给普通类。

3.5 误区澄清表：六条流传说法逐条对账

这是我写本文的直接动机------我自己的笔记里中过四条的招。逐条对账（右列全部经过本机 javac/javap/jshell 验证）：

流传说法	事实
"record 的字段是 public final"	private final。公开的是同名访问器，字段本身外部不可直达（§1.2 javap 已证）
"record 不能有静态字段（除非 static final）"	body 里静态字段随便加，可变的静态字段也合法（当然不建议）。真实限制只有"实例字段禁止"（§6）
"record 不能有 private 构造器"	附加构造器可以是 private（本机编译实测通过，§5.2）；受限的是规范构造器------它的访问权限必须跟随 record 本身
"不能直接访问 this"	无此限制。真实限制是：紧凑构造器里不能给实例字段赋值，只能改参数（§5.1，有真实报错原文）
"record 只是 final class 的语法糖"	糖之外还有类层次（java.lang.Record）与组件元数据------反射、序列化、模式匹配都靠它（§7、§8）
"getter 是自动生成的 get 方法"	生成的叫访问器 ，无 get 前缀、方法名=组件名。这是与 JavaBeans 规范的有意切割：record 不是 JavaBean

最后一条看着像抬杠，实际有工程后果：老式 Introspector/BeanUtils 那套按 getXxx() 找属性的反射，对 record 全部失灵；Jackson 2.12+、Spring 等新栈都已适配访问器与构造器绑定，但你要是引用了某个远古 Bean 工具库，它会静默地认为 record"没有任何属性"。迁移老代码时这是暗坑，不是兼容性问题，是命名约定问题。

4. 什么时候用 / 不用：43 个真实 record 普查

4.1 普查

光讲道理单薄，上真实分布。对 heart-net 全库执行 grep -rE '^\s*(public|private|protected)?\s*(static\s+)?record\s'，43 处声明、27 个文件。按用途归类：

用途分组	数量	真实代表	record 契约在这个场景的价值
提示词模板参数对象	14	AnswerParams、CriticParams、PlannerParams、GateParams...	字段名 = 模板变量名，注册表反射做双向对账（§4.2 详述）
推理链路核心与中间结果	9	ReasoningRequest、Critique、CallResult、GateDecision、Plan	多值返回打包：一次调用带回"正文+账单"、"分数+理由"，不用定义一次性类
接口层出入参	5	TraceQuery、DateRange、UsageRecord	API 形参显式化，替代 Map<String, Object> 参数袋
账号与登录域	5	UserContext、LoginResult、PairCode	敏感上下文封装进不可变对象，防止中途被篡改
资产域与 SPI 事件	6	ExternalAsset、ConnectorDescriptor、UpsertMetadata implements ConnectorEvent	跨层传输的只读快照；record 实现接口的活例
后台装配与安全令牌	4	PendingAction、Subscription、ParamSpec	私有嵌套内部结构，包内即用即弃

观察这个分布能提炼出一个信号：越靠近"数据在层与层之间流动"的地方，record 密度越高。数据一旦要跨方法、跨层、跨线程旅行，"透明 + 不可变 + 身份即状态"三个契约的价值就指数上涨；反之，数据如果在一个对象肚子里从生到死，record 提供不了什么。

4.2 杀手级场景：参数对象 + 命名变量对账

14 个模板参数 record 是全项目 record 密度最高的一族，原因值得单独立传。heart-net 的提示词模板用 {name} 占位符，渲染参数要求必须是 record，字段名就是变量名。注册表 PromptTemplateRegistry.render 的核心逻辑（真实代码节选）：

public String render(String key, Object params) {
    LoadedPrompt loaded = prompts.get(key);
    Map<String, String> values = params == null ? Map.of() : parameterValues(params);
    Set<String> expected = variableNames(loaded.template());
    Set<String> missing = new LinkedHashSet<>(expected);
    missing.removeAll(values.keySet());
    if (!missing.isEmpty()) {
        throw new IllegalStateException("提示词 " + key + " 声明的变量缺少取值：" + missing);
    }
    Set<String> extra = new LinkedHashSet<>(values.keySet());
    extra.removeAll(expected);
    if (!extra.isEmpty()) {
        throw new IllegalStateException("提示词 " + key + " 参数对象多出模板未声明的字段：" + extra);
    }
    // ...单趟正则替换，值按字面写入不被二次解释
}

关键在双向对账 ：模板声明了哪些变量、参数 record 带了哪些字段，两边集合做差，缺了炸、多了也炸。这套对账的前提，是 record 让"字段清单"成为可反射的、和语义一致的元数据：

• 换成普通类 + String.format 位置参数？参数错位是静默 的------编译期不报，运行期产出畸形但"看起来能用"的 prompt，直到某天 LLM 回答诡异才发现。项目类注释里原话：".formatted 位置参数的静默错位......在这里被第一次渲染兜住"。
• 换成 Map<String, String> 参数袋？能对账，但调用方失去编译期检查：键名写错、类型塞错，全靠运行期兜底。
• record 版本：调用方传错字段名是编译错误，字段与模板变量的对账是启动/渲染期的第二道闸。

这就是"参数对象化"为什么在 Java 16 之后从"最佳实践"升级成"近乎无脑选"------record 把参数对象的成本从"为三个变量写一个 30 行类"压到"写一行"，成本的坍塌直接改变了设计的经济学。

4.3 反例：什么时候不该用

同样真实的是另一面的清单：

1. ORM 实体 。PromptTemplateDO 不是 record 有硬理由：MyBatis-Plus 的 CRUD 惯例依赖无参构造器 + setter；record 两者皆无。JPA/Hibernate 更狠------实体要无参构造器，懒加载代理要子类化，而 record 隐式 final + 构造器封死，双重出局。
2. 需要运行时子类化的东西 。Spring AOP 的 CGLib 代理靠生成子类工作，@Transactional/@Cacheable 注在 record 类上会拿到"无法代理 final 类"的警告和失效的切面。数据载体不需要 AOP，但如果你想给 record 加事务语义------说明它不该是 record。
3. 有状态、有生命周期的对象。Service、连接池、有复杂状态机的业务对象，它们的价值恰恰在于"状态在演化"，与 record 的哲学对冲。
4. 缓存派生值 。想存"构造时算好的哈希/规范化副本"？只能另开 Map 或重写访问器------record 不给你实例字段（§6 讲这个限制的理由）。这一点上 Lombok @Value 反而更灵活。
5. 依赖老式 Bean 反射的遗留框架 。按 getXxx() 找属性的 Introspector 系工具认不出访问器（§3.5）。

4.4 决策口诀

一段话总结选型：

数据要旅行，就用 record；状态要安家，别用 record。

出了方法边界还要传、要进集合、要跨线程、要做相等比较、要当参数对象------"旅行"属性出现任意一条，record 的三个契约就开始回本。反之，对象的生命周期就是"在一个类里慢慢演化"，mutable POJO 才是对的。

5. 外显能力：一行之外的扩展面

"record 只能写一行"是误解，body 里的合法扩展面相当大。逐个过，全部有本机验证。

5.1 紧凑构造器：校验与归一化的官方位子

规范构造器的"紧凑形式"（compact constructor）省掉了机械的参数赋字段，编译器在收尾处自动补齐全部隐式赋值；你只写真正关心的逻辑------校验、归一化：

record Range(int lo, int hi) {
    Range {
        if (lo > hi) throw new IllegalArgumentException("lo > hi: " + lo + " > " + hi);
        lo = Math.max(1, lo);   // 归一化：下界至少为 1
    }
}

本机运行输出（原文）：

[compact ctor 校验] lo > hi: 5 > 1
[compact ctor 归一化] Range(0, 5) -> Range[lo=1, hi=5]

两处细节值得放大看：

• Range { ... } 没有参数列表------它不是新构造器，是规范构造器的紧凑写法，组件参数（lo、hi）"天然在作用域里"。
• 给参数 lo 重新赋值是合法的，而且必须在隐式赋值发生前完成------收尾时编译器执行的是"字段 = 最终形态的参数"。这就是"归一化"的标准姿势。

紧凑构造器有一个精确的禁忌：不能显式给实例字段赋值 （this.lo = ...），试一下的报错原文：

BadAssign.java:3: 错误: 无法为 final 变量 lo 分配值
        Range { this.lo = lo; }
                    ^

这个限制的深意：字段赋值必须统一发生在构造器收尾，保证"校验、归一化 → 赋值"的顺序不可绕过，字段不可能在逻辑中途处于半成品状态。

真实项目的对照：heart-net 的模板加载有"加载即 strip 归一"的语义（模板首尾空白无语义，template.strip() 在 load() 里做）。这类"构造即归一化"的语义其实最适合下沉进紧凑构造器------如果哪天重构 LoadedPrompt，strip 就该住在 LoadedPrompt 的紧凑构造器里，而不是住在加载它的 Registry 里。归一化跟着数据走，不跟着流程走，这是紧凑构造器教给我的设计观。

5.2 附加构造器：可以是 private 的

直接驳"record 不能有 private 构造器"的讹传------本机编译实测通过：

public record LoadedPrompt(String key, String template, String hash) {
    // 便捷构造：指纹尚未计算时，先占位（演示语义，非项目代码）
    private LoadedPrompt(String key, String template) {
        this(key, template, "未计算");
    }
}

规则只有一条：任何附加构造器必须委托规范构造器 （this(...) 链式交棒）。这保证了"全组件一起定值"的入口唯一性------不存在绕开规范构造器的口子，等于不存在"半初始化状态"。规范构造器自己倒是有一条约束：访问权限必须与 record 一致。我在 jshell 里演示时真的踩到了它，报错原文：

错误: 记录 Range 中的 规范 构造器无效
  (正在尝试分配更强的访问权限；以前为 public)
    Range {
    ^

这条约束的合理性：record 的可见性决定调用方可见性，构造器可见性若弱于类可见性，就会出现"看得见类型却造不出实例"的破洞。

5.3 实例方法：数据载体也能长行为

ReasoningRequest 是全项目最"厚"的 record------4 个组件 + 3 个方法。节选真实代码：

public record ReasoningRequest(String message, String sessionId,
        String workDirRel, Map<String, Object> modeParams) {

    /** 取整型参数（缺失/非法返回默认值；钳制上下界防误配） */
    public int intParam(String key, int defaultValue, int min, int max) {
        Object raw = modeParams == null ? null : modeParams.get(key);
        if (raw instanceof Number number) {
            return Math.max(min, Math.min(max, number.intValue()));
        }
        if (raw instanceof String text) {
            try {
                return Math.max(min, Math.min(max, Integer.parseInt(text.trim())));
            } catch (NumberFormatException ignored) {
                // 非法取值回默认，不炸请求
            }
        }
        return defaultValue;
    }
    // ... strParam、longParam 同族
}

设计意图值得说破：modeParams 是个类型松散的参数袋（Map<String, Object>），record 的 intParam 把"类型收紧 + 缺省 + 钳制"的脏活封装在数据身边------调用方拿到的是行为化的数据，而不是裸 Map。这是"贫血数据类"恐惧症的解药：record 不禁止行为，只把行为和状态放进同一个不可变的盒子里。

顺带注意 raw instanceof Number number------Java 16 的另一件同期发货（JEP 394）。同一个 record 文件里两个 16 新特性互相配合，是那一代 JDK 的味道。

5.4 静态成员：随便加

静态字段（含可变静态字段，虽然不建议）、静态方法、静态工厂都合法。静态工厂在 record 上特别香，因为new 出来的实例天然带全组件语义：

public record LoadedPrompt(String key, String template, String hash) {
    /** 静态工厂：指纹随构造自动计算，调用方不可能传错 */
    public static LoadedPrompt of(String key, String template) {
        return new LoadedPrompt(key, template, sha256(template));
    }
}

真实项目里 SectionPromptParams(String title, int index, int total, String heading, ...) 这种七字段参数对象，配上静态工厂能进一步把"必填/派生"的意图说清。另外澄清一次："record 不能有静态字段"是讹传（§3.5 表中第 2 条），唯一被禁止的是实例字段。

5.5 实现接口：可以的

record 不能 extends 任何类，但 implements 没有限制。真实例子，heart-net 连接器事件：

record UpsertMetadata(ExternalAsset asset) implements ConnectorEvent { }
record Removed(String externalId) implements ConnectorEvent { }

实现 Comparable 之类的行为接口也是常规操作：

public record User(String name, int age) implements Comparable<User> {
    @Override
    public int compareTo(User other) {
        return Integer.compare(age, other.age);
    }
}

这为 §8 的"sealed interface + record"组合埋了伏笔------接口负责定义形态家族，record 负责当具体成员。

5.6 泛型与嵌套：完整支持

泛型组件、嵌套 record 都是原生的。真实例子（ReWOO 模式的执行计划）：

private record Plan(List<PlanStep> steps) { }

Plan 持有 PlanStep（也是 record）的列表------record 套 record，构成树形结构毫无障碍。两个附带事实：嵌套 record 隐式 static （不捕获外部实例，天然适合当"包内即用即弃"的数据结构，项目里 private record 一大族的由来）；局部 record（方法内声明）Java 16 起也放开：

public Map<String, Long> summarize(List<Trace> traces) {
    record Acc(long cost, int calls) { }        // 局部 record：只在方法内存在
    Acc acc = traces.stream()
            .collect(...);
    ...
}

局部 record 把"临时凑对"从"两个平行 List"或"Object\[\]"解放出来------作用域即生命周期，方法外的世界根本看不见它。

5.7 注解传播：写一次，落四处

组件上标注解，编译器按注解的 @Target 自动分发到四个可能的位置：字段、访问器、构造器形参、组件本身。这是 record 与框架生态握手的关键机制：

public record TraceQuery(
        @NotNull @DateTimeFormat(iso = ISO.DATE) LocalDate start,   // 校验+格式化
        int days) { }

@NotNull（Bean Validation）落到构造器形参与字段，@DateTimeFormat 落到字段与访问器------Spring 的参数绑定和校验链在 record 上全链路工作。JPA 唯一注解 @Entity 落不下来的原因不在注解，在 final（§4.3）。

5.8 javadoc：@param 跟着组件走

回看 §1.1 的 ReasoningRequest------@param message 用户消息... 写在 record 声明头，javadoc 会把组件文档渲染成规范的成员说明。文档的唯一事实源又少了一处 ：字段注释 + getter 注释合并为声明头一处。我的项目规约里 record 的 javadoc 必须逐组件写 @param，43 处声明全部遵守。

6. 为什么 record 不支持......？（限制即设计）

先上类层次图，限制会好理解得多：

flowchart TD O["java.lang.Object"] --> R["java.lang.Record 抽象基类"] R --> LR["你的 record 隐式 final"] I["任意接口 可实现多个"] -. 实现 .-> LR LR -. 继承 .-> X["子类：到此为止 被封死"]

全部限制与真实报错对账（报错均为本机 javac 原文）：

限制	真实报错	设计理由
不能显式 extends 类	错误: 需要'{'------解析层直接拒绝 extends	身份超类的位置已被 java.lang.Record 占住
不能被继承（隐式 final）	错误: 无法从最终Parent进行继承	子类可加字段 = "声明头是全部状态"破产，equals 契约失效
body 不能有实例字段	错误: 字段声明必须为静态，编译器追加提示：（考虑将字段替换为记录组件）	状态清单唯一来源是声明头；javac 甚至给了修复建议
紧凑构造器不能给字段赋值	错误: 无法为 final 变量 lo 分配值	隐式赋值必须统一收尾，字段不可能中途处于半成品
规范构造器访问权限须与 record 一致	正在尝试分配更强的访问权限；以前为 public	杜绝"看得见类型、造不出实例"的破洞
没有 abstract record	------	抽象 = 组件清单无法确定；"一组固定形态"请用 sealed interface + record（§8.2）

值得停下来体会的是 javac 报错的态度：每条报错都附带出路。"实例字段必须为静态"后面跟着"考虑将字段替换为记录组件"------它不是在拒绝你，是在纠正你的建模：你想要的字段，多半本就该是组件。

三个"必须"（状态必须写头部、身份必须是全部状态、形态必须封死）环环相扣，才换来三样别人拿不到的东西：编译器敢代工 equals、框架敢做构造器绑定、语言敢为它发明模式匹配。限制不是没做完的功能，是契约的承重墙。

7. 反射视角：RecordComponent 与一次真实翻车

7.1 三个新入口

record 给反射 API 添了三个口子：Class::isRecord、Class::getRecordComponents、java.lang.reflect.RecordComponent。这是"组件元数据"身份证的直接兑现。项目里最重度的消费者是 PromptTemplateRegistry.parameterValues（真实代码）：

private Map<String, String> parameterValues(Object params) {
    if (!params.getClass().isRecord()) {
        throw new IllegalStateException(
                "提示词参数对象必须是 record：" + params.getClass().getName());
    }
    try {
        Map<String, String> values = new LinkedHashMap<>();
        for (RecordComponent component : params.getClass().getRecordComponents()) {
            Method accessor = component.getAccessor();
            // 参数 record 是调用方服务的嵌套类（多为包私有），跨包反射读
            // public accessor 也须开可达性，否则 invoke 被 Java 访问检查拒绝
            accessor.setAccessible(true);
            Object value = accessor.invoke(params);
            values.put(component.getName(), value == null ? "" : String.valueOf(value));
        }
        return values;
    } catch (ReflectiveOperationException e) {
        throw new IllegalStateException("提示词参数对象读取失败：" + e.getMessage(), e);
    }
}

注意代码里那句注释------它就是下面这场翻车的墓志铭。

7.2 翻车案还原

提示词治理落地当晚的现场：参数 record（如 EvalService$AnswerParams）是各服务的包私有嵌套类 ，而注册表住在 prompt 包，跨包反射读取。诡异之处在于------RecordComponent.getAccessor() 返回的 Method 修饰符明明是 public，invoke 却在运行期炸出：

java.lang.IllegalAccessException: ... cannot access a member of
class com.suyou.heartnet.rag.eval.EvalService$AnswerParams with modifiers public

"成员是 public 却不让访问"，第一反应用户态无解、第二反应怀疑框架。真实根因是 Java 访问检查的冷知识：可达性按"声明类"判定，不只看成员修饰符 。方法虽 public，但声明它的类 EvalService$AnswerParams 对 prompt 包不可见，跨包 invoke 依然被拒。编译期无信号、启动期无信号------只有第一个参数对象真的流经这条反射路径时才炸，炸的位置在生产调用链中段。

修复一行：accessor.setAccessible(true);（如上面代码注释所示，如今常驻在实现里）。

复盘出两条可复用教训：

1. 通用工具反射业务 record 的设计，一律先 setAccessible------不能因为访问器显示 public 就默认能 invoke。同包反射不需要；public 顶层 record 也不需要------但"通用工具"没法预知调用方把 record 声明成什么形态，防御必须建在工具侧。
2. 更彻底的出路是设计期的：把参数 record 提升为 public 顶层类型（比如收进一个 prompt.params 包）。当时选择了 setAccessible 而不是提权------因为包私有嵌套本身就是"参数对象只该本服务使用"的意图表达，为了反射方便提权，等于让工具的需求反向污染了业务的封装边界。两害相权，setAccessible 是当时更便宜的妥协。

7.3 框架支持现状（2026 年视角）

• Jackson 2.12+ ：原生支持 record，构造器绑定 + 访问器读取，@JsonProperty 等注解在组件上按 §5.7 传播。
• Spring Boot 3 / Spring 6 ：@ConfigurationProperties 用 record 直接构造器绑定，单构造器场景连 @ConstructorBinding 都不用写；Web 层 @RequestBody record DTO 全线支持。
• MyBatis 3.5.10+ ：提供按形参名的构造器映射（需 -parameters 编译 + argNameBasedConstructorAutoMapping），record 可映射------但 MyBatis-Plus 的 CRUD 惯例仍是 setter 体系，两者井水不犯河水（§4.3）。
• JPA/Hibernate ：实体不可用 record（无参构造 + final 双重冲突），但**投影（projection）**与 DTO 查询结果用 record 很顺------JPQL 构造器表达式 select new com...TraceView(...) 直接落 record 构造器。

一句话总结生态位：序列化与绑定全面支持，ORM 实体不支持、查询结果支持。

8. 与 Java 17+ 的联动：sealed 与 record patterns

record 不是孤立的 JEP，它是 Java 类型系统"代数数据类型（ADT）"路线的地基。演进时间线：

flowchart LR A["Java 14 一期预览 JEP 359"] --> B["Java 15 二期预览 JEP 384"] B --> C["Java 16 正式定稿 JEP 395"] C --> D["Java 17 sealed 定稿 JEP 409 与 record 组合"] D --> E["Java 21 record 模式匹配 JEP 440 与 switch 模式 JEP 441"]

8.1 sealed interface + record = ADT

sealed（Java 17 正式）限定"哪些类型可以 implements"，record 隐式 final 保证"成员形态封死"------两者拼起来就是函数式语言里的和类型（sum type）：一组封闭的、穷举的形态家族：

sealed interface IngestEvent permits Ingested, Skipped, Failed { }
record Ingested(long docId, String title) implements IngestEvent { }
record Skipped(long docId, String reason) implements IngestEvent { }
record Failed(long docId, String error)   implements IngestEvent { }

ADT 的杀伤力在穷举 ：switch 覆盖所有分支后连 default 都不用写，将来新增 Rejected 事件，编译器把所有漏改的 switch 全部点名报错------"忘处理新形态"从线上事故降级为编译错误。

8.2 record patterns：把组件直接拆出来

Java 21（JEP 440）起，instanceof/switch 能按组件解构 record。本机实测：

Object obj = new Range(1, 5);
if (obj instanceof Range(int lo, int hi)) {       // 组件直接拆为变量
    System.out.println("lo=" + lo + ", hi=" + hi);
}

运行输出（原文）：

[record pattern] lo=1, hi=5

注意这为什么只有 record 能享受：模式匹配要求编译器"可靠地知道对象的全部结构与组件顺序"------组件元数据就是为这一刻准备的（手写类没有这个身份证，模式匹配无从谈起）。配合 sealed 家族，可以写到很顺手：

String text = switch (event) {
    case Ingested(long docId, String title) -> "已入库: " + title;
    case Skipped(long docId, String reason) -> "已跳过: " + reason;
    case Failed(long docId, String error)   -> "已失败: " + error;
    // 无 default：穷举由编译器背书
};

heart-net 在 Java 21 上运行，instanceof Number number 这类模式已在生产代码里（§5.3），sealed + record patterns 是后续模型接入层"形态家族"（比如各模式的运行结果帧）的现成路线。

9. 性能考量：record 的性能就是 final class 的性能

先把预期管理好，三个事实：

1. 没有运行时魔法。javap 已证：编译产物是普通 final 类，无新字节码指令、无运行时组件解析。Project Valhalla 的值类型才是"物理提速"路线，record 不是------它是把"写得对的 final class"标准化。
2. final 是 JIT 的老朋友 。final 类没有子类，调用点天然单态，访问器一行 return field 内联后与直接字段访问同价；equals/hashCode 也享受同样的去虚化待遇。这不是 record 独有，record 只是让"final"从可选纪律变成必守契约。
3. 逃逸分析不吃身份饭。record 在逃逸分析/标量替换上无特殊待遇------不逃逸的实例照样可能被标量替换，逃逸了照样分配在堆上。不可变不自动等于零分配。

两个性能向的"坑护栏"要认清：

• CGLib 无法代理 final 类------Spring AOP 场景 record 得靠接口代理或直接失效。这既是坑也是护栏：它逼你想清楚"这个类需要横切逻辑吗"，答案是需要，那它就不该是 record。
• 反射读取组件 （如 §7.1）有反射开销，与普通反射同级------热点路径缓存 RecordComponent[]/Method 即可（注册表就是这么用的，getRecordComponents 每请求只跑一次的成本完全可接受）。

一句话收束：record 消灭的不是物理开销，而是"人写错"的方差------手写 equals 漏一个字段、hashCode 忘一个组件、忘了 final、忘了 toString 更新，这些的排查成本远大于任何纳秒级差异。

10. 结语：三个你会感谢 record 的时刻

写完 43 处用例的普查与四个深水区，把 record 的价值压缩成三个具体时刻：

1. 写的时候：参数对象从 30 行跌到 1 行，"要不要为这三个变量建个类"不再是一场成本辩论------你会建，因为建了。数据结构密度上升，Map 参数袋退场。
2. 调的时候 ：toString 白送，日志里永远是结构化的 LoadedPrompt[key=..., template=..., hash=...]，而不是 com.suyou...@1a2b3c------调试信息从"要不要专门打"变成"随手就有"。
3. 改的时候 ：给组件加字段，equals/hashCode/toString 自动跟着走；模板变量对账（§4.2）当场把漏改的地方炸出来。不变式由契约维护，不再靠人的记性维护。

最后留一张事实卡，方便日后对账：

事实	值
正式定稿	JDK 16，JEP 395（预览：14 期 JEP 359、15 期 JEP 384）
隐式超类	java.lang.Record（身份超类被占用，故不可 extends 任何类）
隐式修饰	final；嵌套时另隐式 static
字段	private final，body 内实例字段被禁止
访问器	与组件同名，无 get 前缀；可显式重写
equals / hashCode / toString	按全部组件生成，均为 final 方法不可重写
构造器	规范构造器（支持紧凑形式：校验/归一化）；附加构造器须委托规范构造器
静态成员	字段与方法均允许（"不能有静态字段"是讹传）
注解	组件注解按 @Target 自动传播到字段/访问器/形参/组件
反射	isRecord() / getRecordComponents() / RecordComponent；跨包读包私有 record 须 setAccessible
序列化	Java 原生反序列化走规范构造器（校验生效）；Jackson 2.12+ 全支持
生态位	DTO/参数对象/多值返回/值对象；ORM 实体与 AOP 代理场景出局
关联 JEP	394 instanceof 模式（16）、409 sealed（17）、440 record 模式（21）、441 switch 模式（21）

record 最深的一课不在语法，在于它示范了一种语言设计的手法：把某个语义（这里是"透明数据载体"）的所有不变式打包成契约，编译器代工一切可以机械推导的东西，让人类的精力只花在真正需要决策的地方------字段叫什么、校验多严、归一化怎么算。识别哪些东西"本质机械、可被代工"，是这个特性教给所有语言使用者的元能力。