Java record 中可变组件为什么会破坏 hashCode 稳定性

把 record 当作“天然不可变对象”通常只对了一半。record 自己的组件字段不能重新赋值，但字段引用指向的 List、Map 或普通可变类仍可能在外部发生变化。由于自动生成的 equals 和 hashCode 会依据组件值工作，record 一旦被当作 HashMap 或 HashSet 的键，组件变化就可能让查找失效。

record 的 final 字段不等于深不可变

Java 官方对 record 的定义是“浅不可变”的透明数据载体：组件字段是 private final，但组件类型本身的可变性由类型决定。下面的 roles 是一个典型风险点。

import java.util.ArrayList;
import java.util.List;

// record 不能改写 roles 引用，但外部仍能改写同一个 List 对象。
record UserKey(String userId, List roles) {}

var roles = new ArrayList();
roles.add("reader");
var key = new UserKey("u-17", roles);
int before = key.hashCode();

// 这里没有给 key.roles 重新赋值，却改变了参与哈希计算的组件内容。
roles.add("auditor");
int after = key.hashCode();

record 的自动方法关注组件字段的值，而不是替你把组件深拷贝一份。因此 before 和 after 可能不同。这里的“可能”很重要：具体哈希算法不应被业务代码依赖，但组件状态变化导致哈希结果不再稳定，是设计风险本身。

HashMap 为什么会找不到原来的 record 键

HashMap 存入键时，会根据键的哈希值确定候选桶；查询时又根据当前键的哈希值定位。若 roles 在存入后发生变化，查询使用的是新哈希，便可能落到与原来不同的位置。键对象还在 map 内，却不一定能通过原来的对象找回来。

import java.util.HashMap;
import java.util.Map;

// 这个示例只演示风险：不要把后续会变化的 record 当哈希键。
Map cache = new HashMap();
var roles = new ArrayList();
roles.add("reader");
var key = new UserKey("u-17", roles);
cache.put(key, "允许读取");

// key 的组件内容变化后，查询的哈希定位依据也变了。
roles.add("auditor");
String value = cache.get(key);       // 可能得到 null
boolean present = cache.containsKey(key); // 也可能为 false

// 这不是并发问题；即使只有一个线程，也应避免修改哈希键的有效状态。

这类问题常被误判成缓存丢失、并发可见性或 HashMap bug。实际上，Java Map 契约明确提醒：如果对象作为键期间，其影响 equals 比较的状态发生变化，map 的行为就不再有可靠保证。

用不可变组件或构造期快照修复键设计

第一选择是让键只包含稳定值，例如 String、基本类型包装类或真正不可变的值对象。如果业务输入必须是集合，可以在紧凑构造器里复制集合，再返回不可变视图：

import java.util.List;

// 构造时切断外部 List 的后续修改，键的有效状态保持稳定。
record SafeUserKey(String userId, List roles) {
    SafeUserKey {
        // 先复制，再生成不可变 List；null 元素检查可按业务需要补充。
        roles = List.copyOf(roles);
    }
}

var input = new java.util.ArrayList();
input.add("reader");
var safeKey = new SafeUserKey("u-17", input);
input.add("auditor");

// safeKey.roles() 不会随 input 改变，适合作为哈希集合中的键。
Map safeCache = new HashMap();
safeCache.put(safeKey, "允许读取");

List.copyOf 同时完成复制和不可变封装；如果组件元素本身仍是可变对象，它只保证列表结构不变，不能替元素做深拷贝。键的每个参与相等性判断的层级都要满足稳定要求。

常见问题

record 的组件声明为 final 就能避免这个问题吗？

不能。final 防止组件字段重新指向另一个对象，但不会阻止原对象的 add、put 或 setter 改变内容。

把 HashMap 换成 HashSet 能解决吗？

不能。HashSet 同样依赖元素的 equals 与 hashCode；可变元素在加入后改变，也会带来包含判断和删除失败。

只在单线程代码里才需要担心吗？

不需要。根因是键的相等性状态变化，与线程数量无关；并发只会让复现更难观察。