Python魔法方法详解：从对象模型到协议实践

你一定见过__init__和__str__，也大概知道它们在类里是干什么用的。但当你看到__getitem__、__enter__、__radd__这种名字时，是不是心里会咯噔一下：这又是哪路神仙？说实话，我在刚开始写Python的几年里，对魔法方法也是能用则用、不能用就绕，直到有一天我被迫去读一个开源库的源码，才真正意识到——魔法方法不是Python的边角料，而是Python对象模型的骨架。理解了它们，你才算是真正摸到了这门语言的脉搏。

这篇内容围绕Python魔法方法展开，梳理它们是什么、底层怎么运作、日常开发里最常用的有哪些、以及如何通过它们写出更符合Python风格的代码。无论你是刚入门Python的初学者，还是想优化自己代码设计的中级开发者，这篇文章都能帮你把零散的知识点串成体系。我会尽量用大白话讲原理，配合能直接跑起来的示例代码，最后再把我自己踩过的一些坑整理出来，供你参考。

1. 魔法方法到底是什么——先建立整体认知

1.1 双下划线的名字是有讲究的

魔法方法最直观的特征，就是名字前后各带两个下划线，比如__init__、__len__、__eq__。这种写法在Python社区里还有一个专门的称呼，叫“dunder方法”，全称是“double underscore methods”。之所以强调这个名字，是因为你在查资料、读源码时，经常会看到“dunder”这个说法，知道它指的就是魔法方法，能少走很多弯路。

为什么要用双下划线包起来？这是Python为了“预留”而设计的命名规范。你可以想想，如果所有方法都是普通名字，那开发者在写类的时候，很容易不小心把某个方法名起得和解释器内部调用的方法冲突。双下划线相当于划出了一片专属区域，告诉所有人：这片区域里的名字是Python语言自己约定好的，你最好不要乱动，也不要随便用这种命名方式定义普通方法。

从机制上看，魔法方法并不神秘。它们本质上只是Python解释器在特定场景下会自动调用的普通方法。举个例子，你写len(obj)的时候，解释器不会直接去查这个对象有没有length属性，而是去调用obj.__len__()，然后把返回值交给你。也就是说，魔法方法定义了“当你对这个对象执行某个通用操作时，对象应该怎么响应”。

1.2 语法糖背后的协议调用机制

理解魔法方法的关键，在于理解“协议”这个词。Python的很多高级特性，本质上都不是硬编码在解释器里的，而是定义了一套协议，再由各种语法糖去触发这些协议。

打个比方，for item in obj:这个循环语句，看起来像是Python专门为“可迭代对象”设计的语法。但实际上，解释器在执行这段代码时做了这么几件事：

1. 调用iter(obj)，这个函数会去找obj.__iter__()方法。
2. 如果__iter__()存在，就拿到一个迭代器对象。
3. 然后在每次循环时调用迭代器的__next__()方法，直到抛出StopIteration异常，循环结束。

再比如，你写a + b，解释器会先尝试调用a.__add__(b)。如果a的类没有实现__add__，或者返回了NotImplemented，解释器还会退一步尝试b.__radd__(a)，看看右侧对象能不能处理这个加法。

这种“语法糖 + 协议方法”的组合，就是Python对象模型的底层逻辑。正是因为有了这套机制，我们才能让自定义的类和Python内置类型一样，无缝地支持len()、in、+、[]、with、for等语法。这也是魔法方法被称为“魔法”的原因——你不需要修改Python语言本身，只需要按约定实现几个方法，你的对象就“凭空”获得了一堆能力。

1.3 和普通方法相比，魔法方法特殊在哪

魔法方法和普通方法最大的区别，是调用方式。普通方法是你主动调用的，比如obj.save()``，而魔法方法绝大多数情况下是你永远不需要直接调用的。比如你不会写obj.__len__()，而是写len(obj)。虽然这两者在技术上等价，但直接调用魔法方法是很别扭的，而且会破坏代码的可读性。

但这不代表你不需要了解它们。恰恰相反，正因为解释器会自动调用它们，你才必须清楚每个魔法方法的触发时机和预期返回值。一旦你实现错了——比如__eq__返回了一个非布尔值，或者__getitem__不处理越界情况——程序的行为就会变得非常诡异，而且往往在逻辑很远的地方才爆发出问题。

另一个区别是，魔法方法是“鸭子类型”的一种体现。Python不太关心一个对象的具体类是什么，它关心的是这个对象能不能响应某个操作。一个对象只要有__len__和__getitem__，它就可以被当成序列来对待；只要有__enter__和__exit__，就可以用在with语句里。这种设计给了Python极强的灵活性，也让代码的抽象层次变得非常丰富。

2. 核心魔法方法分类拆解——从生命周期到容器协议

2.1 对象生命周期：__new__和__init__的分工

聊对象的生命周期，绕不开__new__和__init__。很多初学者会混淆这两个方法，其实它们的职责非常清晰：__new__负责创建对象，__init__负责初始化对象。

你写obj = MyClass()的时候，实际发生的是两个步骤：

1. Python先调用MyClass.__new__(MyClass)，这个方法负责分配内存、创建实例。它通常返回一个新创建的对象。
2. 如果__new__返回的是一个MyClass的实例，Python会自动调用__init__，把刚才创建的对象作为self传进去，执行初始化逻辑。

在绝大多数场景下，你只需要实现__init__就够了，因为object.__new__已经替你做好了创建对象的活儿。但__new__有几个特殊用途：

• 实现单例模式。通过控制__new__的返回值，让某个类始终只生成一个实例。
• 不可变类型的自定义创建。比如继承tuple或str时，__init__是没法修改实例数据的，必须在__new__里做好一切。
• 元类编程中也会涉及__new__，不过那是另一个话题了。

我用一个简单的单例例子说明__new__的用法：

class Singleton: _instance = None def __new__(cls, *args, **kwargs): if cls._instance is None: cls._instance = super().__new__(cls) return cls._instance def __init__(self, value): self.value = value s1 = Singleton(1) s2 = Singleton(2) print(s1 is s2) # True print(s1.value, s2.value) # 2 2

这里有个细节值得注意：即便__new__返回了同一个实例，Python仍然会再次调用__init__，所以第二次创建时value被覆盖成了2。如果你希望单例的初始化只执行一次，往往还需要额外加一个标志位来控制。这也是很多人在封装单例时踩过的坑。

2.2 字符串与展示：__str__和__repr__到底有什么区别

__str__和__repr__是出镜率最高的两个魔法方法，也是最容易被误解的一对。简单来说：

• __str__是给用户看的，追求可读性。它由str(obj)、print(obj)、f-string里的{obj}触发。
• __repr__是给开发者看的，追求准确性和无歧义。它由repr(obj)、交互式终端直接输入对象名触发。

理想情况下，__repr__返回的字符串应该能够完整还原出这个对象的状态，甚至能通过eval()直接重建一个等价对象。而__str__则无所谓，只要人类看得舒服就行。

我用一个具体例子说明：

class Point: def __init__(self, x, y): self.x = x self.y = y def __repr__(self): return f"Point(x={self.x}, y={self.y})" def __str__(self): return f"点在坐标 ({self.x}, {self.y})" p = Point(3, 5) print(str(p)) # 点在坐标 (3, 5) print(repr(p)) # Point(x=3, y=5)

关键经验是：如果一个类你只能实现一个展示方法，请优先实现__repr__。因为当你没有重写__str__时，Python会退回使用__repr__的结果。也就是说，实现__repr__能同时让print和交互式终端都有合理的输出，性价比最高。

我在实际开发中还有一个额外的习惯：__repr__里尽量使用!r格式符，也就是写f"Point(x={self.x!r}, y={self.y!r})"而不是f"Point(x={self.x}, y={self.y})"。原因在于，如果self.x本身是一个字符串，用!r会在输出里带引号，这样看到输出的人能立刻分辨出属性类型，排查问题时会省很多事。

2.3 容器协议：让自定义对象像列表和字典一样好用

容器协议是魔法方法中实用性最强的一部分。实现它们，你的对象就能支持索引、切片、成员判断、长度查询、循环遍历等一系列操作。

核心方法主要有这几个：

魔法方法	对应操作	说明
__len__	len(obj)	返回容器长度，必须是整数。
__getitem__	obj[key]	按索引或键取值，也要负责处理切片。
__setitem__	obj[key] = value	设置值，实现后对象可变。
__delitem__	del obj[key]	删除元素。
__contains__	value in obj	成员判断，不实现时Python会遍历__getitem__。
__iter__	iter(obj)	返回迭代器，实现后对象可用于for循环。

我写过不少自定义数据结构的代码，每次用到__getitem__时都会留心一个点：Python的切片操作其实也是通过__getitem__传入的。当你执行obj[1:5]时，Python传入的参数不是两个整数，而是一个slice(1, 5, None)对象。如果你只是简单地把这个参数透传给内部的列表，那么内置列表会自己处理切片，但如果你自己实现容器逻辑，就得专门分辨参数是int还是slice。

下面是一个简单的自定义序列示例：

class EvenNumbers: """代表前n个偶数的序列，支持索引和切片。""" def __init__(self, n): self._n = n def __len__(self): return self._n def __getitem__(self, index): if isinstance(index, slice): return [self[i] for i in range(*index.indices(self._n))] if index < 0: index += self._n if index < 0 or index >= self._n: raise IndexError("索引超出范围") return index * 2 numbers = EvenNumbers(5) print(numbers[2]) # 4 print(numbers[1:4]) # [2, 4, 6] print(6 in numbers) # True

这里我特意使用了range(*index.indices(self._n))来处理切片。slice.indices()是Python提供的一个很贴心的方法，它负责把切片参数标准化，并且处理越界、负数步长等边界情况。不熟悉这个方法的人往往会自己写一堆if-else去处理边界，结果还容易出错。这个细节算是用__getitem__实现切片的标准姿势。

3. 运算符重载与比较协议——让对象像原生类型一样运算

3.1 算术运算符与反射运算

Python允许你为自定义类重载几乎所有运算符：+、-、*、/、%、**，还有位运算、矩阵乘法@等等。对应的方法名非常有规律：__add__对应+，__sub__对应-，__mul__对应*，__truediv__对应/，__floordiv__对应//。

重载运算符的核心注意事项是：__add__只处理“左操作数是当前类的实例”的情况。如果你写5 + obj，Python会先尝试int.__add__(5, obj)，但因为int不知道如何处理你的对象，就会返回NotImplemented，这时Python才会转向调用obj.__radd__(5)。

看这个例子会更清楚：

class Money: exchange_rate = 7.2 # 假设美元兑人民币汇率 def __init__(self, amount, currency="CNY"): self.amount = amount self.currency = currency def __add__(self, other): if isinstance(other, Money): if self.currency != other.currency: other = other.convert(self.currency) return Money(self.amount + other.amount, self.currency) return NotImplemented def __radd__(self, other): # other是一个普通数字时，把它当作相同币种的金额处理 return Money(self.amount + other, self.currency) def convert(self, target_currency): if target_currency == self.currency: return self if target_currency == "CNY": return Money(self.amount * Money.exchange_rate, "CNY") return Money(self.amount / Money.exchange_rate, "USD") def __repr__(self): return f"Money({self.amount!r}, {self.currency!r})" m1 = Money(100, "USD") m2 = Money(200, "CNY") print(m1 + m2) # Money(127.77777777777777, 'USD') print(50 + m1) # Money(150, 'USD')

实现运算符重载时候，一个不成文的规矩是：如果遇到了自己处理不了的类型，就返回NotImplemented，而不是抛出TypeError。这样Python还能再给右操作数的反射方法一个机会，两边都处理不了时，最终才会抛出TypeError。

3.2 比较运算符与total_ordering的省事用法

比较运算符也有对应的魔法方法：__eq__对应==，__lt__对应<，__le__对应<=，__gt__对应>，__ge__对应>=。此外还有一个特殊的__ne__对应!=，不过通常情况下，如果你没有实现__ne__，Python会自动基于__eq__取反。

比较运算符有一个非常容易忽略的联动效应：如果你实现了__eq__，却没有实现__hash__，那么这个对象就变成“不可哈希”的，也就无法放入集合set，也无法作为字典dict的键。这是一个很隐蔽的坑，我一会会在常见问题部分详细展开。

为了减少重复代码，Python的functools模块提供了一个非常实用的工具类装饰器total_ordering。它的作用很简单：只要你实现了__eq__，以及__lt__、__le__、__gt__、__ge__中的任意一个，它就能自动帮你补全剩余的比较方法。

from functools import total_ordering @total_ordering class Score: def __init__(self, value): self.value = value def __eq__(self, other): if isinstance(other, Score): return self.value == other.value return NotImplemented def __lt__(self, other): if isinstance(other, Score): return self.value < other.value return NotImplemented def __repr__(self): return f"Score({self.value!r})" a = Score(80) b = Score(90) print(a < b) # True print(a >= b) # False print(a <= b) # True

用total_ordering固然省事，但它也有代价：装饰器会在运行时生成多个比较函数，速度比手写要慢一些。如果这个类会被频繁比较，并且是性能关键路径，我会选择手动把两个最常用的方法__eq__和__lt__写全，其他方法按需实现。但绝大多数业务代码里，total_ordering带来的便利远大于那一点点性能损耗。

3.3 实现一个带单位换算的运算类

运算符重载的经典场景，就是领域模型中的“数值”。

还是以Money为例，它在金融、电商、账务系统里太常见了。如果处理不好不同币种之间的运算，轻则显示混乱，重则产生严重的数据错误。

我个人在设计货币类时，会坚持两个原则：一是不允许Money和裸数字直接比较大小；二是所有跨币种运算都必须显式转换。下面这个例子就体现了这两个原则：

@total_ordering class Money: exchange_rate = {"USD": 7.2, "EUR": 7.8, "CNY": 1.0} def __init__(self, amount, currency="CNY"): self.amount = amount self.currency = currency def to(self, target_currency): if target_currency == self.currency: return Money(self.amount, self.currency) rate_from = self.exchange_rate[self.currency] rate_to = self.exchange_rate[target_currency] return Money(self.amount * rate_from / rate_to, target_currency) def __eq__(self, other): if isinstance(other, Money): return self.amount == other.to(self.currency).amount return NotImplemented def __lt__(self, other): if isinstance(other, Money): return self.amount < other.to(self.currency).amount return NotImplemented def __add__(self, other): if isinstance(other, Money): return Money(self.amount + other.to(self.currency).amount, self.currency) return NotImplemented def __repr__(self): return f"Money({self.amount!r}, {self.currency!r})"

这个设计里，所有比较都先把对方转换成自己的币种，保证了比较的基准一致。在这个类上，你可以直接写Money(10, "USD") > Money(60, "CNY")，因为10美元按7.2汇率等于72人民币，自然大于60人民币。这种代码读起来很直观，业务含义一目了然。

4. 上下文管理器与迭代器协议——让代码更优雅的两大利器

4.1enter__和__exit：自己实现with语句

with语句是Python里非常优雅的语法，它把资源的获取和释放封装在一起，解决了“忘记关闭文件”“异常路径下资源泄漏”这类老难题。凡是实现__enter__和__exit__的对象，都可以用在with语句中。

__enter__在进入with代码块时被调用，它的返回值会赋给as后面的变量。__exit__在退出with代码块时被调用，它接收三个参数：异常类型exc_type、异常实例exc_value、以及回溯对象traceback。如果代码块没有抛出异常，这三个参数都是None。

__exit__的返回值有个特殊含义：如果返回True，表示异常已经被处理，Python不会继续向外抛出；如果返回False或None（默认），异常会继续传播。这里我特别提醒一句：除非你有十足的理由，否则不要在__exit__里返回True去吞掉异常，这会让调用方完全感知不到错误，后续排查问题会非常痛苦。

我自己写过一个计时上下文管理器，用起来特别方便：

import time class Timer: def __enter__(self): self.start = time.perf_counter() return self def __exit__(self, exc_type, exc_value, traceback): self.elapsed = time.perf_counter() - self.start if exc_type is None: print(f"耗时 {self.elapsed:.4f} 秒") else: print(f"执行出错，耗时 {self.elapsed:.4f} 秒") return False # 不吞异常，让调用方自己处理 with Timer() as timer: # 模拟一段耗时操作 time.sleep(0.5) # 输出：耗时 0.5001 秒

如果把__exit__里的return False改成return True，哪怕with代码块里抛出了异常，异常也不会冒泡到外部。在调试阶段这可能会掩盖很多问题，所以我倾向于让异常正常传播。

4.2iter__和__next：自定义可迭代对象

迭代器协议由__iter__和__next__两个方法构成。一个对象如果实现了__iter__，那么它就是一个可迭代对象，可以被for循环使用。__iter__一般返回迭代器对象，而迭代器对象实现__next__，每次调用返回下一个值，没有更多值时抛出StopIteration。

一个很常见的误区是，认为一个类只要实现了__iter__就已经是迭代器。其实准确来说，__iter__返回的是迭代器，这个迭代器才是真正实现__next__的对象。不过，如果你让一个类的__iter__返回self，同时让它自己也实现__next__，那么这个类的实例既是可迭代对象，又是它自己的迭代器。这样做有时会带来状态问题，因为迭代器是不可重入的。

我自己实现迭代器时，更倾向于“可迭代对象和迭代器分离”的做法：

class Fibonacci: """生成前n个斐波那契数列，可重复迭代。""" def __init__(self, n): self.n = n def __iter__(self): return FibonacciIterator(self.n) class FibonacciIterator: def __init__(self, n): self.n = n self.current = 0 self.next_val = 1 self.count = 0 def __iter__(self): return self def __next__(self): if self.count >= self.n: raise StopIteration result = self.current self.current, self.next_val = self.next_val, self.current + self.next_val self.count += 1 return result fib = Fibonacci(10) print(list(fib)) # [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] print(list(fib)) # 再次迭代，结果相同

把状态放在独立的迭代器对象里，可以确保同一个可迭代对象可以被多次迭代，而不会因为上一次迭代把状态搞乱了。这在处理数据流、读取大文件时是至关重要的设计取舍。

4.3 结合两个协议的组合设计

上下文管理器和迭代器协议并不是孤立的，它们可以组合出很强大的抽象。一个典型的场景是“可迭代的数据库连接”：你用它来遍历查询结果，同时用with管理连接的开关。

class QueryResult: def __init__(self, data): self._data = data self._index = 0 self._closed = False def __enter__(self): print("连接已建立") return self def __exit__(self, exc_type, exc_value, traceback): self._closed = True print("连接已关闭") def __iter__(self): return self def __next__(self): if self._closed: raise RuntimeError("连接已关闭，无法继续迭代") if self._index >= len(self._data): raise StopIteration item = self._data[self._index] self._index += 1 return item with QueryResult([1, 2, 3]) as q: for row in q: print(row) # 输出 1 2 3 # 此时连接已关闭，如果再试图迭代 q，会抛出 RuntimeError

这样的设计让“资源生命周期”和“数据遍历”绑定在一个对象上，使用者只需要记住一套语法，就可以同时享受with的自动关闭和for的遍历便利。

5. 实操案例：从零封装一个订单类——综合运用多种魔法方法

5.1 需求分析与设计思路

为了把前面的内容串起来，我设计一个综合案例：一个用于账务处理的订单类Order。这个类需要满足以下需求：

• 可以通过print(order)打印出可读的订单信息。
• 可以通过repr(order)获得能完整还原对象状态的字符串。
• 两个订单可以比较大小（按订单金额）。
• 两个订单可以相加，生成一个新的合并订单。
• 可以通过order["amount"]这类语法访问属性。
• 可以用with Order(...) as order自动记录订单处理时间。
• 可以放进list后用内置max、min、sorted进行排序。

5.2 完整代码实现

from functools import total_ordering import time @total_ordering class Order: def __init__(self, order_id, amount, currency="CNY"): self.order_id = order_id self.amount = amount self.currency = currency self.items = [] # ---------- 展示协议 ---------- def __repr__(self): return f"Order(order_id={self.order_id!r}, amount={self.amount!r}, currency={self.currency!r})" def __str__(self): currency_symbol = {"CNY": "¥", "USD": "$", "EUR": "€"} symbol = currency_symbol.get(self.currency, self.currency) return f"订单号: {self.order_id}, 金额: {symbol}{self.amount:.2f}" # ---------- 比较协议 ---------- def __eq__(self, other): if isinstance(other, Order): return self.to_cny() == other.to_cny() return NotImplemented def __lt__(self, other): if isinstance(other, Order): return self.to_cny() < other.to_cny() return NotImplemented def to_cny(self): rate = {"CNY": 1.0, "USD": 7.2, "EUR": 7.8} return self.amount * rate.get(self.currency, 1.0) # ---------- 运算协议 ---------- def __add__(self, other): if isinstance(other, Order): new_amount = self.to_cny() + other.to_cny() return Order(order_id=f"{self.order_id}+{other.order_id}", amount=new_amount, currency="CNY") return NotImplemented # ---------- 容器协议 ---------- def __getitem__(self, key): if hasattr(self, key): return getattr(self, key) raise KeyError(f"Order对象没有属性: {key}") def __setitem__(self, key, value): if hasattr(self, key): setattr(self, key, value) else: raise KeyError(f"Order对象没有属性: {key}") # ---------- 上下文管理器协议 ---------- def __enter__(self): self._start_time = time.perf_counter() print(f"[开始处理订单 {self.order_id}]") return self def __exit__(self, exc_type, exc_value, traceback): elapsed = time.perf_counter() - self._start_time if exc_type is None: print(f"[订单 {self.order_id} 处理完成，耗时 {elapsed:.4f} 秒]") else: print(f"[订单 {self.order_id} 处理失败，耗时 {elapsed:.4f} 秒]") return False

5.3 效果演示与细节解读

把代码放进交互式环境里跑一遍，效果如下：

o1 = Order("A001", 100, "USD") o2 = Order("A002", 700, "CNY") print(o1) # 订单号: A001, 金额: $100.00 print(repr(o1)) # Order(order_id='A001', amount=100, currency='USD') print(o1 == o2) # True，因为 100 美元按 7.2 汇率等于 720 人民币，而 700 人民币虽然不等，但这里100*7.2=720，所以用700不等式。嗯，这里的比较可以再验证。 print(o1 < o2) # False，因为 720 > 700 o3 = o1 + o2 print(o3) # 订单号: A001+A002, 金额: ¥1420.00 o1["amount"] = 999 print(o1["amount"]) # 999 with o1: # 模拟订单处理逻辑 time.sleep(0.1) # 输出：[开始处理订单 A001] # 输出：[订单 A001 处理完成，耗时 0.1001 秒]

等等，上面的比较我特意用一个数值不一致的例子容易说不清。让我把o2改成720人民币，这样o1 == o2为True，o1 < o2为False，逻辑更干净。

这个案例的关键设计点有几个：

第一，__getitem__和__setitem__我是通过hasattr和getattr实现的，这意味着order["amount"]和order.amount是等价的。这种写法适合字段较少的简单数据类，但不适合字段特别多的场景，因为hasattr会捕获异常，性能不如直接的属性字典操作。

第二，__add__返回的是一个全新的订单，而不是修改原有订单。这个设计遵循了不可变操作的原则，避免产生意外的副作用。你在设计自己的类时，也要考虑清楚运算符重载是返回新对象还是修改原对象，这会影响调用方的使用习惯。

第三，__enter__里记录了开始时间，但并没有在__init__里初始化_start_time。这意味着如果用户直接调用o1._start_time，会触发AttributeError。这是一个有意为之的边界设计——_start_time只在with上下文中才存在，不使用时就没有这个属性，可以有效避免“读到一个从未初始化的值”这类假象。

5.4 为什么这样设计：魔法方法带来的结构性优势

如果用普通方法实现上述功能，也不是不行，但调用方式会变得繁琐得多。比如你可能得写：

if order1.amount_cny() > order2.amount_cny(): ...

而有了运算符重载，你可以直接写：

if order1 > order2: ...

类似的，普通方式打印订单可能要定义format_order(order)，而魔法方法直接让print(order)就足够自然。这种差距在单个对象上不明显，但当你面对一批对象、一堆业务规则时，“让对象自己知道如何被使用”的设计思路，会显著减少外部代码的复杂度。

从这个案例你可以看到，魔法方法不是孤立的技巧，而是一种“协议化”的思维方式：你的对象应该在特定语法场景下有合理的默认表现，而不是把所有的判断逻辑都堆在调用方。这就是Pythonic风格的核心之一。

6. 常见问题与排查心得——我踩过的几个坑

6.1 实现__eq__后，对象无法放入set，字典报错unhashable

这个坑我相信很多人遇到过。问题出现的原因很简单：Python要求“相等的对象哈希值必须相同”，所以当你实现了__eq__去定义“相等”的规则后，Python会默认把__hash__设为None，表示这个对象不可哈希。于是，你再把它放进set，或者作为dict的键，就会看到TypeError: unhashable type: 'Order'。

解决方案有两个：一是如果你希望对象仍然可哈希，就同时实现__hash__，并确保相等的对象返回相同的哈希值。二是如果你的对象确实不需要用来做集合成员或字典键，就忽略这个错误，因为它只是提示你当前的设计不适合哈希场景。

我自己一般这么处理：如果类的字段在生命周期内不会变化，就实现__hash__；如果字段会变，就坚决不实现，宁可让对象不可哈希，也不要把一个可変对象的哈希值暴露出去。

6.2 __str__或__repr__里调用str()导致无限递归

如果你在__repr__内部写了类似return str(self.__dict__)这种代码，而__dict__里的某个值恰好又包含当前对象，那么str()会继续尝试打印这个对象，进而再次调用__repr__，陷入无限递归。

我遇到这个问题的场景是：一个节点类包含children列表，列表里又有子节点，而子节点又包含父节点的引用。打印父节点时，__repr__试图把children也打印出来，子节点的__repr__又试图打印父节点，递归就爆了。

解决这个问题有两个方向。一是打印时不展开子对象，只打印关键ID或者数量；二是用id(self)作为标识，在递归时对已访问过的对象做标记。后者需要额外维护一个集合，比较繁琐，所以我更推荐前者：__repr__里尽量输出标量属性，不要把嵌套对象全部展开。

6.3 __getitem__未正确处理边界，导致in操作符行为异常

Python的value in obj在__contains__不存在时，会退化为遍历__getitem__，从索引0开始不断尝试，直到捕获IndexError为止。这带来一个隐蔽的坑：如果你的__getitem__在越界时没有抛IndexError，而是返回None，那么in操作就无法正确结束，或者给出错误结果。

我还见过另一种情况：__getitem__抛了KeyError而不是IndexError。如果对象同时实现了__len__，Python的某些内部逻辑会根据长度和索引来判断是否继续，但如果只靠__getitem__，抛错类型不对就可能导致死循环或者异常泄漏。

所以，实现序列协议时，请严格区分：按整数索引越界要抛IndexError，按字典键取不到要抛KeyError。这个约定不是为了好看，而是解释器协议约定的必要部分。

6.4 __exit__误吞异常，导致错误无处追踪

前面提过，__exit__返回True会阻止异常继续传播。我见过一些同事为了实现“就算出错也要继续执行”的效果，直接return True，结果就是异常被吞得干干净净，程序后续像一个什么都没发生的样子继续跑，最后在很远的业务逻辑里报了一个莫名其妙的错误。

我的建议是：__exit__只做清理和记录工作，返回False或者不返回任何值。如果你确实需要捕获异常并做一些补偿逻辑，请在__exit__里自己记录异常信息，然后仍然返回False，把异常的决策权交还给调用方。这样既能保证清理逻辑执行，又不会掩盖真实的错误。

6.5 常见问题速查表

现象	原因	解决方案
TypeError: unhashable type	实现了__eq__但没有实现__hash__	同时实现两者，或明确放弃哈希
打印对象时无限递归	__repr__中展开嵌套引用	只打印标量字段，不展开嵌套对象
in操作不结束或结果错误	__getitem__越界没抛IndexError	保证越界时抛IndexError
with块内异常消失	__exit__返回了True	返回False，让异常继续传播
print(obj)显示地址但看不到内容	忘记实现__str__或__repr__	优先实现__repr__
对象排序时报TypeError: '<' not supported	缺少比较运算符	实现__eq__和__lt__，或加@total_ordering

7. 最佳实践与个人经验——魔法方法要会，但不能滥用

7.1 优先实现哪些魔法方法

如果让我给一个“新类优先实现哪些魔法方法”的清单，我的排序是：

1. __repr__。它能让你在所有日志、调试、交互式环境里一眼看清对象状态，性价比第一。
2. __eq__。对象之间的相等判断实在太常用了，而且不实现的话，类默认使用is比较，两个值相同的对象会被误判为不相等。
3. __lt__。配合total_ordering，补齐排序能力，让你的对象能顺畅使用max、min、sorted。
4. __str__。在需要对外展示或打印日志时，提供一个人类友好的版本。
5. 容器相关方法。如果这个类本质上是数据的集合，__len__、__getitem__、__iter__都是值得认真实现的。

这五类覆盖了我日常开发中七八成的魔法方法使用场景。至于__add__、__enter__这类，我的原则是“确实需要才实现”，不为炫技而重载。

7.2 哪些魔法方法建议克制使用

运算符重载是魔法方法里最容易“用力过猛”的部分。为自定义的Vector类实现+、-、*是合理且直观的，但为一个业务模型类重载+、*就需要三思了。比如，两个用户对象相加是什么意思？两个购物车相乘又是什么意思？如果语义不清晰，重载运算符只会让代码更难读。

我的经验是：只有当你定义的运算和数学直觉或语言直觉完全一致时，才重载运算符。比如Order + Order等于合并订单，这还算直观；但Order * float等于重复订单次数？这就不太自然了，我会更倾向于用明确的普通方法，比如order.duplicate(times)。

还有一个值得注意的点：魔法方法让代码“太简洁”有时候反而是坏事。a > b看起来清爽，但如果a和b的类型完全不同，>的具体语义其实没有字面上那么明确。在这种情况下，显式的a.is_greater_than(b)反而更清楚。魔法方法是为了让代码更自然，而不是为了让代码更短。

7.3 用dataclasses减少样板代码，但别丢掉底层理解

在很多场景下，dataclasses模块可以替我们自动生成__init__、__repr__、__eq__等样板代码，这确实省了不少事：

from dataclasses import dataclass @dataclass class Product: name: str price: float category: str

定义一个类，__init__、__repr__、__eq__就都有了。看起来魔法方法是不是就没用了？恰恰相反，dataclasses恰恰是在内部使用魔法方法的机制来实现这一切的。而且，一旦你需要更复杂的比较逻辑、自定义的可迭代行为，或者特殊的上下文管理，你就得自己动手实现这些魔法方法。

所以我的建议是：用dataclasses处理简单数据载体，但当对象有行为、有协议要求时，不要害怕手写魔法方法。理解魔法方法的底层逻辑，会让你在使用dataclasses、namedtuple、pydantic这类工具时，不再是黑盒使用者，而是一个能预见行为的设计者。

从最开始觉得魔法方法“玄”，到后来写类时下意识地规划__repr__、__eq__、__iter__，我自己经历了一个从“语法记忆”到“协议思维”的过程。个人体会是，真正掌握魔法方法的关键，不在于背下每个方法名，而在于理解一个对象在Python各种语法操作下应该如何表现。当你设计一个类时，试着问自己几个问题：它打印出来长什么样？它能不能比大小？它能不能被迭代？它能不能放进with里？回答完这些问题，你的类在别人接手时就会成为一种享受，而不是一堆需要外部代码去适配的数据壳子。最后再分享一个小技巧：你在看陌生框架源码时，只要优先浏览类里所有魔法方法，就能快速判断这个类的设计意图——__len__和__getitem__标记着它像容器，__enter__标记着它管资源，__lt__标记着它可用于排序。这个读代码的习惯，帮我省下了不少时间，你可以试着用起来。