Python的哈希机制，有时候确实会让人摸不着头脑。你写了一个自定义类，兴冲冲地想把它当成字典的键，结果啪一下，抛了个 TypeError: unhashable type。这到底是为什么？又该怎么解决？这篇文章就来彻底讲清楚这件事。
直说吧，核心问题就出在“可变性”上。Python的字典和集合，底层依赖哈希表来快速定位元素。如果对象的哈希值能变，那它之前存进去的位置就找不到了，整个数据结构会乱套。所以，对于默认的自定义类，Python采取了最保守的策略：干脆不给你提供 __hash__ 方法，从源头上杜绝隐患。
为什么直接给类加 __hash__ 会报错
这才是问题的关键。你可能会想，我自己写一个 __hash__ 方法不就行了？没错，但在动手之前，必须理解一个更隐蔽的陷阱：哈希契约。这个契约规定，两个相等的对象，它们的哈希值必须相等。如果你只重写了 __hash__，却忘了重写 __eq__，那Python会默认用 is（即内存地址）来比较两个对象是否相等。这会导致什么后果？两个内容完全相同的实例，在 __eq__ 看来是不相等的，但在 __hash__ 看来哈希值却是一样的。这直接违反了哈希契约，字典的行为就会变得诡异——你可能查不到一个明明存在的键，或者同一个键被重复插入。
另一个更常见的问题是，即使你同时重写了 __hash__ 和 __eq__，但如果参与哈希计算的字段是可变对象（比如一个列表），那哈希值依然存在被破坏的风险。一旦字段内容变了，哈希值就变了，这个对象在字典里就“丢了”。
如何安全地实现 __hash__ 和 __eq__
理解了上面的风险，实现起来就清晰了。核心原则就一条：只对不可变字段进行哈希和相等判断，并且这两个判断必须基于完全相同的字段集。
- 最省心的方式：
@dataclass(frozen=True)。这是Python官方推荐的做法，它会自动将类设为不可变，并基于所有字段生成正确的__hash__和__eq__。代码简洁，逻辑正确，是首选。 - 手动实现时，务必小心。你需要确保
__hash__返回的是像hash((self.id, self.name))这样的元组哈希，并且这些字段在对象创建后绝对不能被修改。任何试图修改它们的操作，都意味着你设计了一个有缺陷的类。 - 避免在
__hash__中调用动态方法。比如，不要用hash(self.current_status())，因为current_status返回的值可能随时间变化，哈希值也因此不稳定。 - 如果类本身需要可变性，比如有缓存或状态标记，那就别强求哈希化了。改用
id(obj)作为字典键，或者设计一个不可变的唯一ID字段，这在很多场景下是更可控的方案。
@dataclass(frozen=True)class Point: x: float y: floatp1 = Point(1.0, 2.0)p2 = Point(1.0, 2.0)d = {p1: "origin"}print(p2 in d) # True —— 正常工作
__hash__ 返回 None 的实际用途
显式地将 __hash__ 设为 None，是一种非常清晰的防御性声明：“这个类无论如何都不能被哈希”。这通常用在基类或模板类中，防止子类误用。比如，Django的 Model 类就是这么干的。它强制开发者用 .pk 或 .id 作为键，避免了ORM实例在状态未同步时可能出现的哈希错乱问题。
相比之下，写一个 def __hash__(self): return 0 的“空实现”是极其糟糕的做法。这会让所有实例的哈希值都一样，导致字典性能直接退化为链表，查找效率从O(1)变成O(n)。
所以，如果你正在设计一个可变配置类，又担心别人不小心把它当字典键用，直接设 __hash__ = None 是最干净利落的写法。
序列化与哈希化不是一回事，别混用
有个常见的误解，认为可以用 pickle.dumps(obj) 或 json.dumps(vars(obj)) 的结果来“通用化”实现 __hash__。这听起来很巧妙，但实际操作中隐患重重。
- 跨进程/跨版本不兼容：
pickle的输出格式依赖于Python版本和对象内部结构，不同进程之间算出来的哈希值可能完全不同。 - 哈希依据不完整：
vars()拿不到私有属性、描述符或__slots__中定义的字段，哈希依据是残缺的。 - 性能开销巨大：序列化本身就是一个重量级操作，哈希化是字典查找的热点路径，频繁调用序列化会带来严重的性能下降。
- 场景错位：如果你真的需要跨进程或跨语言共享哈希，比如在分布式缓存中，应该用明确的字段拼接加上一个稳定的哈希算法，比如
hashlib.sha256。Python内置的hash()函数仅用于进程内的字典键查找，它不保证跨进程的稳定性。
记住，哈希化的本质是快速区分对象身份，而不是做数据摘要。只要你的字段选得准、不可变、并且严格遵守了哈希契约，一个简单的 return hash((self.id, self.name)) 就足够可靠了。别把事情想复杂了。
