自定义 Key 的设计规范：分析不可变变量（Immutable）作为 Map 键名的重要性-java教程-PHP中文网

不可变类作为Map键是必须遵守的底层约束，根本原因在于哈希表依赖稳定的hashCode()和equals()行为定位键值对；若键可变，修改后hashCode()变化会导致查找时定位到错误桶，从而“静默丢失”数据。

自定义 key 的设计规范：分析不可变变量（immutable）作为 map 键名的重要性

不可变变量作为 Map 键，不是“推荐做法”，而是必须遵守的底层约束。根本原因在于哈希表的查找机制依赖于键的 hashCode() 和 equals() 行为稳定——一旦键对象内部状态改变，这两个方法的返回值就可能变化，导致键值对“消失”在 HashMap 内部结构中。

为什么可变键会让数据“找不回来”

HashMap 底层用数组 + 链表/红黑树实现。插入时，它先调用 key.hashCode() 算出索引位置，把键值对存进去；查找时，同样用 key.hashCode() 定位到那个桶（bucket），再遍历桶内元素，用 equals() 逐个比对。

如果键对象被修改后 hashCode() 变了，get() 就会去错的桶里找，自然找不到；即使 hashCode() 没变，但 equals() 判断逻辑变了（比如字段参与比较但值已不同），也会匹配失败。

哪怕只改一个字段，只要它参与了 hashCode() 或 equals() 计算，风险就存在
这个过程不报错、不抛异常，只是查不到值——属于静默失效，极难排查
多线程环境下更危险：一个线程刚 put，另一个线程立刻改 key，后续任何 get 都失败

自定义 Key 必须满足的三个硬性条件

缺一不可，否则无法可靠工作：

不可变性：所有参与 hashCode() 和 equals() 的字段，必须是 final，且构造后不可修改；不要提供 setter、不要暴露可变引用（如 ArrayList 字段）
正确重写 hashCode()：使用 Objects.hash(f1, f2, f3) 等标准方式，确保字段值相同则哈希值必然相同
正确重写 equals()：用 Objects.equals() 处理 null，且比较字段必须与 hashCode() 中使用的完全一致、顺序一致

常见错误设计与安全替代方案

以下写法看似简洁，实则埋雷：

❌ 直接用 new StringBuilder("abc") 当 key：StringBuilder 可变，hashCode() 会随内容变
❌ 把 POJO 类（如 User）直接当 key：除非该类明确声明为不可变并重写了两个方法，否则默认行为基于内存地址，完全不可用
❌ 用 SimpleEntry 组合多字段：其 setValue() 方法可修改 value 字段，破坏不可变性

✅ 推荐做法：为业务语义明确的组合字段创建专用不可变类，例如：

public final class DeviceKey {
    private final String devId;
    private final String region;
    private final int version;

    public DeviceKey(String devId, String region, int version) {
        this.devId = Objects.requireNonNull(devId);
        this.region = Objects.requireNonNull(region);
        this.version = version;
    }

    // getter only, no setters

    @Override
    public int hashCode() {
        return Objects.hash(devId, region, version);
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        DeviceKey deviceKey = (DeviceKey) o;
        return version == deviceKey.version &&
               Objects.equals(devId, deviceKey.devId) &&
               Objects.equals(region, deviceKey.region);
    }
}