缓存命中率离奇趴在 0%:Java equals 与 hashCode 避坑

一个跑得好好的 Java 服务,某次我顺手看了眼它的缓存命中率监控,当场愣住:命中率常年趴在接近 0% 的地方。这缓存等于白做——每次查询都穿透到后端,该慢还是慢,内存里那个缓存 map 倒是越涨越大,光占地方不干活。可代码逻辑看上去毫无破绽:同样的查询条件,理应命中同一个缓存项才对。

我打了点日志,把每次查询的 key 和缓存里已有的 key 打出来对比,结果更迷惑了:两个 key 在日志里长得一模一样,可 map.get(key) 就是返回 null。一样的东西,怎么会查不到?带着这个"见鬼了"的疑问,我扒开了那个作为 key 的自定义类——真相一下子就清楚了,而且经典得让我有点不好意思:这个类重写了 equals,让"业务上相等"的两个对象被判为相等;却偏偏忘了同时重写 hashCode。

就这一个疏漏,整个缓存就废了。因为 HashMap 找一个 key,是先看 hashCode 落在哪个桶,再在桶里用 equals 比对。两个 equals 相等的对象,hashCode 却不一样(用了默认的、基于对象地址的实现),于是它俩被扔进了不同的桶,永远照不了面——存进去的那个,查的时候根本找不着。这篇文章,就是我把这次"缓存全 miss"事故彻底复盘后,整理出的一份 Java 对象相等性避坑指南。它不堆术语,只讲清楚一件被无数人轻视、却能让缓存、去重、查找集体失灵的小事:在 Java 里,"两个对象相不相等",远不是你以为的那么简单。

先纠正几个关于"相等"的常见误解

动手之前,先把几个我曾经深信、后来被这次事故狠狠纠正的误解摆出来。如果你也这么以为,这篇大概率能帮你提前堵上那个让缓存集体失灵的洞。

第一件事:看懂 == 与 equals,以及那个被忽视的契约

要理解缓存为什么全 miss,得先把 Java 里两种"相等"分清楚。== 比较的是"引用"——对于对象,它问的是"这俩变量是不是指向同一个对象实例"(地址相同)。equals 比较的是"逻辑相等"——它问的是"这俩对象在业务含义上算不算一回事"。Object 自带的 equals 默认实现其实就是 ==,所以你不重写它,它就只认"同一个对象"。

而 HashMap、HashSet 这些基于哈希的容器,定位元素靠的是一套两步走的机制:先用 hashCode() 算出该去哪个桶(bucket),再在那个桶里用 equals() 逐个比对找到目标。这就引出了 Java 里那条神圣却常被无视的契约:如果两个对象 equals 相等,它们的 hashCode 就必须相等。反过来不要求(hashCode 相等的对象可以不 equals,那叫哈希冲突,正常现象)。我那次的 bug,正是把这条契约践踏得明明白白——equals 说"它俩相等",hashCode 却给出两个不同的值,直接把容器的两步走机制送进了死胡同。

看懂这张图,事故的本质就清楚了:HashMap 的高效,建立在"hashCode 先把范围缩小到一个桶"之上;一旦 equals 和 hashCode 不同步,这套机制就从根上瓦解——存得进、却取不出,因为存和取算出的桶号根本对不上。所以第一步,就是把这两个方法成对地、正确地重写好。

第二件事:equals 和 hashCode,必须成对地、正确地重写

定位到病根后,修法很明确:既然重写了 equals,就必须同时重写 hashCode,而且要保证"equals 用到哪些字段,hashCode 就基于哪些字段计算"。下面是那个 key 类修复前后的对比。

// ❌ 反例:只重写了 equals,hashCode 用的还是 Object 默认的(基于地址)
public class OrderKey {
    private final String userId;
    private final String region;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof OrderKey)) return false;
        OrderKey k = (OrderKey) o;
        return userId.equals(k.userId) && region.equals(k.region);
    }
    // ⚠️ 没重写 hashCode!两个 equals 相等的对象 hashCode 却不同 → 落不同桶
}

// ✅ 正例:equals 和 hashCode 基于同一组字段,成对重写
public class OrderKey {
    private final String userId;
    private final String region;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof OrderKey)) return false;
        OrderKey k = (OrderKey) o;
        return Objects.equals(userId, k.userId)
            && Objects.equals(region, k.region);
    }

    @Override
    public int hashCode() {
        return Objects.hash(userId, region);   // 用同样的字段算哈希
    }
}

java.util.Objects 提供的 Objects.equals 和 Objects.hash 是写这两个方法的利器:前者自带 null 安全(两个都为 null 算相等,不会 NPE),后者能把多个字段一把揉成一个合理的哈希值。记牢这条铁律:重写 equals 和 hashCode 是一个"绑定操作"——你动其中一个,就必须动另一个,且两者依据的字段集合必须完全一致。这是 Java 里最经典的契约,违反它的代价,就是我经历的那种"存进去取不出来"的灵异事件。修完之后,那个缓存的命中率当天就从 0% 跳到了 90% 以上。

第三件事:包装类型用 == 比较,那颗藏在 -128~127 里的雷

修好缓存后我顺藤摸瓜,又在代码里揪出一处更隐蔽的相等性陷阱——用 == 比较两个 Integer。这个坑的恶劣之处在于:它在小数值下表现完全正常,数值一大就突然出错,偶发得让人抓狂。

Integer a = 100, b = 100;
System.out.println(a == b);    // true  ← 别高兴太早

Integer c = 1000, d = 1000;
System.out.println(c == d);    // false ← 同样的写法,结果却反了!

// 原因:Integer 自动装箱会复用 [-128, 127] 的缓存对象
//   100 在缓存范围内 → a、b 指向同一个缓存对象 → == 为 true
//   1000 超出缓存 → c、d 是两个新对象 → == 比地址 → false

// ✅ 正确做法:比较数值一律用 equals,或拆成基本类型 int 比
System.out.println(c.equals(d));            // true,比的是数值
System.out.println(c.intValue() == d.intValue()); // true

这个坑当年咬过我们一次:有段代码用 == 比较订单状态码,状态码小的时候(在缓存范围内)一切正常,直到某个新业务用了个大于 127 的状态码,判断逻辑突然就错乱了,排查时还一度怀疑是数据脏了。记住一条死规矩:只要是包装类型(Integer、Long、Character 等),比较"值相等"永远用 equals 或先拆箱成基本类型,绝不用 ==。== 对包装类型问的永远是"是不是同一个对象",而自动装箱带来的对象复用机制,会让这个问题的答案变得诡异且不可靠。

第四件事:字符串的 == 陷阱,以及 intern 的迷思

同样的雷,在 String 上换了个壳又埋了一遍。很多人写 str1 == str2 比较字符串,在某些情况下"碰巧"是对的,于是误以为可以这么用——直到某天换了个来源的字符串,结果就翻车。根源还是那句话:== 比的是"是不是同一个对象",不是内容。

String a = "hello";
String b = "hello";
System.out.println(a == b);          // true:字面量都指向常量池里同一个对象

String c = new String("hello");
System.out.println(a == c);          // false:new 出来的是堆上的新对象,地址不同
System.out.println(a.equals(c));     // true:equals 比内容,这才是你想要的

String d = c.intern();               // intern:把它换成常量池里的那个引用
System.out.println(a == d);          // true:现在指向同一个池中对象了

// ✅ 死规矩:比较字符串内容,永远用 equals(或 equalsIgnoreCase)
//   想防 NPE,可以把常量写前面:"hello".equals(str)
//   或用 Objects.equals(str1, str2) —— 两边为 null 也安全

字面量字符串之所以 == 也相等,是因为编译期它们被放进了同一个字符串常量池,多个相同字面量复用同一个对象。但只要字符串来自 new、来自网络/数据库/文件读取、来自拼接计算,它就是堆上的新对象,== 立刻失灵。intern() 能把字符串"归一"到常量池,但滥用 intern 反而有风险——大量不重复的字符串 intern 会撑大常量池、增加 GC 负担。结论简单粗暴:比较字符串内容,一律 equals,别碰 ==,也别为了能用 == 去 intern。

第五件事:拿"会变的对象"当 key,等于亲手埋雷

解决了相等性,还有一个和它孪生的坑:用可变对象做 HashMap 的 key,然后在放进去之后又改了它参与 hashCode 计算的字段。这会导致一个比"全 miss"更诡异的现象——同一个对象,刚放进去能取到,改了个字段之后,就再也取不到了。

// ❌ 反例:可变对象做 key,放进去后又改了它的字段
class MutableKey {
    int id;                          // 非 final,可变
    MutableKey(int id) { this.id = id; }
    @Override public boolean equals(Object o) { /* 基于 id */ ... }
    @Override public int hashCode() { return Integer.hashCode(id); }
}

Map<MutableKey, String> map = new HashMap<>();
MutableKey key = new MutableKey(1);
map.put(key, "value");               // 此刻按 hashCode(1) 放进了 1 号桶

key.id = 2;                          // 💥 改了 id,hashCode 现在变成 hashCode(2)
System.out.println(map.get(key));    // null!按新 hash 去 2 号桶找,可它在 1 号桶
System.out.println(map.get(new MutableKey(1))); // 也 null,1 号桶里那个对象 id 已是 2

// ✅ 正解:用不可变对象做 key —— 所有参与 hashCode 的字段都设为 final

这个坑的本质是:HashMap 假定 key 放进去之后,它的 hashCode 和 equals 结果永不改变。你一旦在放入后修改了 key 参与哈希的字段,就违背了这个假定,对象会卡在"按旧 hash 入桶、按新 hash 查找"的错位里,永远团聚不了。所以做 key 的对象,最好是不可变的——把所有字段设成 final,从根上杜绝"放进去之后被改"的可能。String、Integer 这些天生不可变的类型,正因如此特别适合当 key。

第六件事:别再手写了,让工具替你保证正确

说到底,equals/hashCode 手写实在太容易出错——漏个字段、两个方法依据的字段不一致、忘了重写其一……每一种都是线上事故的种子。所以现代 Java 的最佳实践是:能不手写,就不手写。

// ✅ 方案一:JDK 16+ 的 record —— 自动生成基于全部字段的 equals/hashCode/toString
public record OrderKey(String userId, String region) {}
// 就这一行!equals、hashCode、构造器、访问器全自动且绝对正确,还天生不可变

// ✅ 方案二:Lombok 注解(项目用 Lombok 时)
@EqualsAndHashCode
@Getter
public class OrderKey {
    private final String userId;
    private final String region;
}

// ✅ 方案三:让 IDE 自动生成(IntelliJ: Alt+Insert → equals() and hashCode())
//   选好参与的字段,生成的代码契约一致、不会漏

这三种方案里,我最推荐 record:它专为"不可变数据载体"而生,一行声明就把 equals/hashCode/toString/构造器/访问器全部正确生成,而且天生不可变——简直是为"做 map key"量身定做的。用 record 重写那个 OrderKey 之后,我那个酿成事故的类从二十多行缩成了一行,而且再不可能犯当初那个错。这就是好工具的价值:它不是让你少写几行,而是把一整类错误从可能性里直接抹掉。如果 JDK 版本还不支持 record,那就退而求其次用 Lombok 或 IDE 生成,核心原则不变——把这件易错的事,交给不会犯错的工具。

一张图收束:要比较对象 / 拿对象做 key,该怎么办

把这次的经验串成一条决策路径,下次再碰到"对象比较"或"拿对象做 key/放进 Set",照着走一遍,基本不会踩雷。

这套打法的内核就一句话:先认清"在比什么类型",再用对应的正确手段——基本类型用 ==,包装类型和字符串用 equals,自定义对象成对重写 equals/hashCode 且做 key 时保证不可变。把这条路径走顺,Java 里那一整类"相等性"引发的灵异 bug,基本就和你绝缘了。

七条铁律,直接抄进你的 code review 清单

最后把这次事故沉淀成七条可以直接执行的铁律。它们不深奥,但每一条背后都对应着一次"缓存失灵 / 去重失效 / 莫名 NPE"的可能——抄下来贴在 review 模板里,比读十篇原理文章都管用。

1. 重写 equals 必须同时重写 hashCode:两者依据的字段集合必须完全一致。
2. 引用类型比内容一律用 equals:== 比的是地址,不是内容。
3. 包装类型别用 == 比数值:-128~127 缓存内碰巧 true,出了范围就是 false。
4. 字符串比较永远 equals:字面量碰巧 == 相等,new/拼接/读取来的就翻车。
5. 做 key 的对象要不可变:参与 hashCode 的字段设 final,放进去后绝不修改。
6. 能用 record / Lombok / IDE 生成就别手写:把易错的事交给不会犯错的工具。
7. 防 NPE 用 Objects.equals 或常量在前:"x".equals(s) 比 s.equals("x") 安全。

一张速查表:到底什么时候用 == ,什么时候用 equals

这次事故之后,我把"相等性"这件事整理成了一张速查表,贴在团队 wiki 上。它不复杂,但能在你落键的那一刻就给出正确答案,省得每次都要回忆一遍原理。

这张表里我想特别点出最后一行的价值:Objects.equals(a, b) 几乎是"防御性比较"的标准答案——它内部先判 null、再调 equals,两边都为 null 算相等、一边为 null 算不等,永远不会抛 NPE。很多由"比较"引发的线上 NPE,换成它就能根治。还有枚举那行也值得记:枚举用 == 比较不仅安全(枚举值是 JVM 保证的单例),还比 equals 多一层好处——左边是 null 时 == 不会 NPE,而 null.equals(x) 会炸。这些细节单拎出来都不起眼,可它们正是"老手"和"新手"在 code review 时一眼就能分出高下的地方。

顺手补上的一道防线:静态检查

修完所有相等性的坑,我没就此打住,而是给项目补了一道自动化防线——把相关规则接进了静态检查工具。因为人的注意力总会松懈,但工具不会。

我们用的是 SpotBugs(配合 Error Prone),它能在编译期就揪出好几类相等性问题:重写了 equals 却没重写 hashCode、用 == 比较字符串或包装类型、equals 的参数类型写错(比如误写成 equals(OrderKey o) 而非 equals(Object o),这会变成重载而非重写,坑得无声无息)。这些规则一旦接进 CI,以后谁再不小心写出"只重写 equals 不重写 hashCode",流水线当场就会拦下,根本到不了生产。这次事故教会我的不只是"相等性的原理",更是一种思路:凡是"人容易犯、且后果严重"的错误,最好的对策不是更努力地记住别犯,而是找一个工具,让这类错误从一开始就编译不过、合不进去。

同一个病根,会以好几种面孔出现

那次我是从"缓存命中率为 0"这个症状切入的,但 equals/hashCode 不一致这同一个病根,在不同场景下会换上完全不同的面孔。复盘时我特意把它的几张"脸"都列了出来,免得下次它换个马甲我又认不出来。

// 面孔一:HashSet 去重失效 —— 明明"相等"的对象却被当成两个塞了进去
Set<OrderKey> set = new HashSet<>();
set.add(new OrderKey("u1", "cn"));
set.add(new OrderKey("u1", "cn"));   // 业务上和上一个相等
System.out.println(set.size());      // 没重写 hashCode 时:2(去重失效!)
                                      // 正确重写后:1

// 面孔二:contains 永远 false —— 列表里明明有,却说找不到
List<OrderKey> list = List.of(new OrderKey("u1", "cn"));
boolean has = list.contains(new OrderKey("u1", "cn"));
// List.contains 用 equals 比 —— 只要 equals 写对就 true;但若连 equals 都没重写,就 false

// 面孔三:remove 删不掉 —— map.remove(key) 静默失败,内存只增不减

这三张面孔——去重失效、查找落空、删除失败——看起来八竿子打不着,病根却是同一个:容器在用 hashCode 和 equals 判断"两个元素是不是一回事"时得到了错误答案。它们还有个共同的阴险之处:都不会抛异常、不会报错,程序照常运行,只是行为悄悄地不对。HashSet 越长越大(去重没生效),缓存越占越多(remove 删不掉),全是"内存慢慢涨"的温水煮青蛙。所以当你遇到"集合行为诡异、却没有任何报错"时,第一个该怀疑的,就是元素的 equals/hashCode 是不是出了问题——这条排查直觉,是这次事故塞给我的一份意外收获。

写在最后

这次"缓存全 miss"的事故,起因小得几乎可笑——就是漏写了一个 hashCode 方法。但它狠狠提醒了我:Java 里"对象相等"这件看似最基础的事,底下藏着 == 与 equals 的分野、equals 与 hashCode 的契约、自动装箱的缓存、字符串常量池、可变对象做 key 的禁忌……每一条单独看都不难,可一旦在某个不起眼的角落踩中一个,引发的却是缓存失灵、去重失效、查找返回 null 这类"逻辑明明没错、结果就是不对"的灵异 bug,排查起来格外费神,因为你的第一反应永远是"这不可能啊"。

所以现在写 Java,我对"相等"多了一份敬畏:每写一个要放进 HashMap/HashSet 的类,先确认 equals/hashCode 成对且正确,首选直接上 record;每写一个 ==,先确认两边是不是基本类型,不是就换 equals;每拿一个对象做 key,先确认它不可变。这些念头谈不上高深,却把"相等性"从"出了灵异 bug 再扒源码救火",前移到了"落键时就写对"。而当静态检查那条规则第一次飘红、拦下一个漏写的 hashCode 时,我特别踏实——它替我挡下的,可能就是又一个让人对着监控百思不得其解的深夜。把基础打扎实,远比记住一堆高级特性更能让你睡得安稳,这大概就是这场事故留给我最值钱的东西。

如果你也维护着用到 HashMap、HashSet 的 Java 代码,不妨今天就花十分钟做两件小事:把所有"自定义类做 key / 放进 Set"的地方翻出来,逐个确认它有没有成对、正确地重写 equals 和 hashCode;再在项目里搜一搜 ==,看看有没有哪处在拿它比字符串或包装类型。这两件事花不了多少时间,却可能拦下一个正潜伏着、等流量上来或数据变大就发作的灵异 bug。基础的东西最不起眼,也最容易被跳过,可线上那些"逻辑没错结果不对"的诡异故障,十有八九就藏在这些被跳过的基础里。

说到底,这场事故让我重新敬畏了"基础"二字。== 和 equals 的区别、equals 与 hashCode 的契约,这些是 Java 入门第一周就会讲到的内容,可正因为太基础,反而最容易在日复一日的编码里被想当然地略过。真正的功力,往往不在于记住多少冷门 API,而在于把这些"人人都懂"的基础,在每一次落键时都不打折扣地写对。把这份对基础的认真刻进习惯,你会发现自己被这类灵异 bug 叫醒的深夜,正变得越来越少。

最后留一句与你共勉:在 Java 里,"看起来相等"和"容器认为相等"是两件事,而后者只听 equals 和 hashCode 这两个方法的。把它俩写对、绑定地写对、最好交给工具替你写对,你的缓存、去重和查找,才会如你所愿地老老实实工作。这条朴素的纪律,值得你在往后每一个 HashMap 面前都默念一遍。

毕竟,能让人睡个安稳觉的,从来不是多花哨的架构,而是这些被认真对待的基础细节。

—— 别看了 · 2026