Java HashMap key 修改后为什么 get 不到值：从 hashCode 到不可变 key

Java 项目里偶尔会遇到一个很迷惑的问题：对象已经作为 HashMap 的 key 放进去了，后面再用同一个对象去 get，结果却返回 null。对象没换，Map 也没清空，为什么值突然找不到了？

这篇文章从一个最小复现开始，带你一步步看清原因：HashMap 查找位置依赖 key 的 hashCode 和 equals。如果 key 放入后又修改了参与哈希计算的字段，后续查找可能会跑到另一个桶里，自然就拿不到原来的值。

问题现场：HashMap key 改了以后 get 不到值

假设我们用一个用户对象当 key，把用户对应的配置放入 HashMap。放入时 key 的 id 是 7，name 是 old；随后业务逻辑把 name 改成 new；再用这个 key 去查，结果返回 null。

这个现象看起来像 Map 把数据弄丢了，其实数据还在原来的桶里。问题是当前 key 的哈希结果变了，查找时已经走到了新的桶。

初步判断：不是 Map 丢了，而是查找路径变了

HashMap 的查找大致分两步：

1. 先根据 key 的 hashCode 计算桶位置。
2. 再在桶里用 equals 判断哪个 key 真正匹配。

所以 key 有一个很重要的约定：放入 Map 后，参与 hashCode 和 equals 的字段最好不要再变。否则同一个对象可能被计算到另一个位置，后续查找就会失败。

动手验证：用一段代码复现返回 null

先写一个可变 key：

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

class UserKey {
    private final long id;
    private String name;

    UserKey(long id, String name) {
        this.id = id;
        this.name = name;
    }

    void setName(String name) {
        this.name = name;
    }

    @Override
    public int hashCode() {
        return Objects.hash(id, name);
    }

    @Override
    public boolean equals(Object other) {
        if (this == other) {
            return true;
        }
        if (!(other instanceof UserKey that)) {
            return false;
        }
        return id == that.id && Objects.equals(name, that.name);
    }
}

再复现一次查不到值：

Map map = new HashMap();

UserKey key = new UserKey(7L, "old");
map.put(key, "profile-cache");

key.setName("new");

System.out.println(map.get(key)); // null

这里的关键不是对象引用换了，而是 name 参与了 hashCode 计算。修改 name 后，桶位置可能变化。

定位原因：hashCode 改变后找到了另一个桶

为了更直观，可以打印修改前后的哈希值：

UserKey key = new UserKey(7L, "old");
int before = key.hashCode();

key.setName("new");
int after = key.hashCode();

System.out.println(before);
System.out.println(after);

如果两个值不同，就说明这个 key 的定位依据已经改变。原来的键值对还挂在旧位置，但当前查找会先去新位置找。新位置没有这个条目，自然返回 null。

修复方案：让 Map 的 key 保持稳定

修复思路不是“每次 get 前多试几次”，而是从设计上保证 key 稳定。

方案一：使用不可变 key

如果 key 是业务对象，尽量让参与哈希的字段不可变。Java record 很适合表达这种含义：

record UserKey(long id, String type) {
}

Map map = new HashMap();
map.put(new UserKey(7L, "vip"), "profile-cache");

String value = map.get(new UserKey(7L, "vip"));

不可变 key 的好处是：放入 Map 后，桶位置不会因为字段变化而漂移。

方案二：用稳定 ID 当 key

很多时候不需要把整个对象作为 key。只用稳定的主键更简单：

Map map = new HashMap();

long userId = 7L;
map.put(userId, "profile-cache");

String value = map.get(userId);

如果业务上用户名称、状态、等级会变，但用户 ID 不变，就应该优先用 ID 作为 key。

方案三：必须改 key 时，先删后放

如果 key 的字段必须变化，而且变化后确实代表一个新的键，那就不要直接改已放入 Map 的 key。先删除旧 key，再放入新 key。

Map map = new HashMap();

UserKey oldKey = new UserKey(7L, "old");
map.put(oldKey, "profile-cache");

String value = map.remove(oldKey);

UserKey newKey = new UserKey(7L, "new");
map.put(newKey, value);

这样 Map 会按新 key 重新计算位置，后续 get(newKey) 才能稳定命中。

验证结果：重查、遍历和单测一起确认

修复后可以从三个角度确认：

1. 用新 key 执行 get，结果能正常返回。
2. 遍历 entrySet，确认没有遗留旧 key 对应的脏数据。
3. 补单元测试，锁住 key 稳定性和查询行为。

UserKey key = new UserKey(7L, "vip");
Map map = new HashMap();

map.put(key, "profile-cache");

String value = map.get(new UserKey(7L, "vip"));

if (!"profile-cache".equals(value)) {
    throw new IllegalStateException("HashMap key lookup failed");
}

如果项目使用 JUnit，可以把这个行为写成测试，避免后续有人把不可变 key 改回可变对象。

总结清单

• HashMap 查找先看 hashCode 定位桶，再用 equals 判断匹配。
• key 放入 Map 后，不要修改参与 hashCode 和 equals 的字段。
• 优先使用不可变对象作为 key。
• 如果有稳定主键，优先使用 Long、String 这类稳定值作为 key。
• 必须改变 key 含义时，先 remove 旧 key，再 put 新 key。
• 对缓存、索引、去重集合这类关键 Map，补单测确认查询行为。