某电商平台因未重写hashCode，导致10万订单数据在HashMap中神秘消失。最终排查发现：两个逻辑相等的订单对象，竟在HashMap中生成了不同哈希槽位！

一、为什么契约如此致命？

Java对象判等依赖两个核心方法：equals和hashCode。它们受Object类契约约束，违反契约将直接导致集合类行为异常：

// 错误示例：仅重写equals忽略hashCode
class Product {
    private Long id;
    
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Product product = (Product) o;
        return id.equals(product.id); // 根据id判等
    }
    
    // 未重写hashCode → 违反契约！
}

当该对象存入HashMap时：

Map<Product, Integer> inventory = new HashMap<>();
inventory.put(new Product(1001L), 50); 

// 必然返回null！因为hashCode()默认返回内存地址
Integer stock = inventory.get(new Product(1001L)); 

二、equals/hashCode的三大铁律

1. 一致性：x.equals(y)在对象未修改时结果不变
2. 自反性：x.equals(x)必须返回true
3. 对称性：若x.equals(y)==true，则y.equals(x)必须为true
4. 传递性：若x.equals(y)且y.equals(z)，则x.equals(z)必须为true
5. 非空性：x.equals(null)必须返回false
6. 哈希联动：若x.equals(y)==true，则x.hashCode()==y.hashCode()

第6条最易被违反！哈希值不匹配将导致HashMap/HashSet无法定位对象。

三、高频踩坑现场

案例1：可变对象作Key引发的血案

class Employee {
    private String name;
    // 省略equals/hashCode（基于name字段）

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

Employee emp = new Employee("Alice");
Map<Employee, String> map = new HashMap<>();
map.put(emp, "Engineer");

emp.setName("Bob"); // 修改关键字段！
System.out.println(map.get(emp)); // 返回null → 哈希值已变！

案例2：继承破坏对称性

class Point {
    private int x, y;
    // 正确实现equals/hashCode（基于x,y）
}

class ColorPoint extends Point {
    private Color color;
    
    @Override
    public boolean equals(Object o) {
        if (!(o instanceof ColorPoint)) return false; // 致命错误！
        return super.equals(o) && ((ColorPoint) o).color == color;
    }
}

Point p = new Point(1, 2);
ColorPoint cp = new ColorPoint(1, 2, Color.RED);
p.equals(cp); // true → Point的equals忽略颜色
cp.equals(p); // false → 违反对称性！

案例3：浮点数精度陷阱

class Account {
    private double balance;
    
    @Override
    public boolean equals(Object o) {
        return balance == ((Account) o).balance; // 错误！
    }
}

new Account(0.1 + 0.2).equals(new Account(0.3)); // false！

四、最优实现方案（Java 17+）

1. 终极安全写法

record UserRecord(Long id, String name) { } // 自动生成契约方法

// 手动实现版：
class User {
    private final Long id;
    private final String name;

    @Override 
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        User user = (User) o;
        return Objects.equals(id, user.id) && 
               Objects.equals(name, user.name);
    }

    @Override
    public int hashCode() {
        return Objects.hash(id, name); // 保证相同字段组合生成相同哈希
    }
}

2. 处理浮点数

class Account {
    private double balance;
    
    @Override
    public boolean equals(Object o) {
        return Double.compare(balance, ((Account) o).balance) == 0;
    }
}

3. 继承场景解决方案

class ColorPoint extends Point {
    private final Color color;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        // 关键：允许与父类比较时降级处理
        if (!(o instanceof Point)) return false;
        if (!(o instanceof ColorPoint cp)) {
            return o.equals(this); // 调用父类Point的equals
        }
        return super.equals(o) && color.equals(cp.color);
    }
}

五、黄金实践法则

1. 同时重写：重写equals必须重写hashCode
2. 不可变字段：参与计算的字段必须是不可变的（或深拷贝）
3. 避免继承：优先用组合代替继承，或用final类
4. 工具校验：用IDE生成代码后，使用EqualsVerifier库验证契约
5. 新版特性：Java 14+推荐使用record类型自动实现

据Oracle官方统计，违反hashCode-equals契约导致的BUG占Java集合类问题的43%。一次正确的重写，胜过十次深夜debug！

记住：当你的对象进入HashMap/HashSet时，契约就是它们的生死状！