我最早接触Python魔法方法（Magic Methods）时的第一反应是：这不就是C++的运算符重载加Java的toString吗？抱着这个理解写了一段时间代码，直到有一次在项目的模拟数据类里同时实现了__eq__却没有处理__hash__，程序在运行时直接抛了TypeError，我才意识到魔法方法根本不是几个语法糖的堆砌，而是Python对象模型给所有类型定下的一套隐形契约。今天想把这套契约的底层逻辑讲清楚，顺带把我踩过的坑和一些实践中沉淀下来的用法一起分享出来。
这篇文章适合两类读者：一类是写过一段时间Python、见过各种双下划线方法但一直没系统梳理过的人；另一类是正准备用Python做数据处理或后端开发、需要自定义数据类型和对象行为的同学。读完你至少能回答三个问题：魔法方法为什么能自动被调用；自定义类时该实现哪些方法、不该碰哪些方法；遇到TypeError: unhashable type这类报错时该怎么排查。
1. 先搞清楚魔法方法的底层身份：它们是协议，不是语法糖
1.1 解释器如何调用特殊方法
先看一个最简单的例子。你写len(obj)的时候，解释器做的不是直接读取某个长度属性，而是尝试调用obj.__len__()。如果这个类没有实现__len__，len()就会抛TypeError: object of type 'X' has no len()。也就是说，魔法方法是解释器在特定时机、对特定操作约定的"回调接口"。这种约定无处不在：for循环会先调iter(obj)，iter()又会找__iter__或者回退到__getitem__；in操作符会优先走__contains__；str(obj)会找__str__，找不到再降到__repr__。理解了这一点，你就会明白：写魔法方法不是在"重载运算符"，而是在向Python解释器声明"我这个类型支持某某行为协议"。
用一个很好记的类比：解释器像是一套建筑工程标准，魔法方法就是墙上的电源插座接口。你的自定义类只要按标准形状做了一个插座，任何用电器（语法、内置函数、标准库工具）插上来就能用。不做这个接口，哪怕你内部有一个叫做length的属性，内置len()也不会认它。
常见语法和魔法方法的对应关系可以整理成这样一张表：
| Python语法/内置函数 | 实际被调用的魔法方法 |
|---|---|
len(obj) | obj.__len__() |
obj[i] | obj.__getitem__(i) |
x in obj | obj.__contains__(x) |
for x in obj | iter(obj)找__iter__()或__getitem__() |
str(obj) | obj.__str__()，回退__repr__() |
with obj as f | obj.__enter__()/obj.__exit__(...) |
这种"调用"还有一个容易忽略的细节：大多数特殊方法是通过类型（type）层面的查找完成的，而不是直接在实例上查找。解释器在找__len__这些名字时，通常是直接在对象的类型上找，很少去实例的__dict__里找。所以你在实例上动态给obj.__len__ = ...，len(obj)很可能仍然不会调用它。这是我见过不少人困惑的点。
1.2 两个流传很久的误解
第一个误解：魔法方法等于运算符重载。实际上魔法方法覆盖的范围远比运算符大。对象从创建到销毁有__new__、__init__、__del__；属性访问有__getattr__、__setattr__、__getattribute__；容器行为有__getitem__、__setitem__、__len__、__contains__；上下文管理有__enter__、__exit__；迭代有__iter__、__next__；甚至对象能不能被调用，都靠__call__。运算符重载只是其中一小块。
第二个误解：魔法方法实现得越多越专业。恰恰相反，很多魔法方法之间存在隐式联动和优先级关系。比如__bool__没实现时会回退到__len__，__len__为0则bool(obj)为False；__eq__定义了但__hash__没定义，Python会直接把类的__hash__设为None，对象变成不可哈希。盲目堆方法，很容易让对象行为变得不可预测。正确的思路是：先想清楚这个类在Python生态里应该充当什么角色，需要哪种协议，就只实现那组协议。
2. 对象的从生到死：new、init、__del__的真实分工
2.1 __new__负责创建，__init__负责初始化
很多面向对象的教材把__init__叫构造函数，这个叫法在Python里其实不太准确。严格说，创建实例分两步：__new__是真正的"构造"，它是一个类方法（第一个参数是cls），负责分配对象并返回实例；__init__接收__new__返回的实例，只做初始化。也就是说，__init__执行的时候，对象已经存在于内存里了。默认情况下，__new__返回一个cls的实例后，解释器会自动用这个实例去调__init__，所以绝大部分类根本不用重写__new__。
什么时候必须碰__new__？答案是需要控制"实例创建过程"本身而不是"实例内容"的时候。典型场景有两个。第一个是单例，想让整个进程只有一个实例，在__new__里判断类变量有没有被赋值，没有就创建，有就直接返回已存在的。第二个是自定义不可变类型，一个类一旦在定义上不可变（比如继承tuple），就无法在__init__里正常赋值，初始化逻辑就得放进__new__。我见过一个坐标点类型就是这么写的：
class ImmutablePoint: __slots__ = ("_x", "_y") def __new__(cls, x, y): instance = super().__new__(cls) object.__setattr__(instance, "_x", x) object.__setattr__(instance, "_y", y) return instance @property def x(self): return self._x @property def y(self): return self._y def __repr__(self): return f"ImmutablePoint({self._x}, {self._y})" def __eq__(self, other): if not isinstance(other, ImmutablePoint): return False return self._x == other._x and self._y == other._y def __hash__(self): return hash((self._x, self._y))注意这里的object.__setattr__调用，它绕过类里可能存在的自定义__setattr__逻辑，直接走object的默认实现。这是比较进阶的技巧，但确实管用。
这种不可变类型的价值在于可以安全地作为字典的key、放进set，因为它的哈希值从创建之后就不会变。如果只是想让数据不可变，用namedtuple或者@dataclass(frozen=True)往往更省事，__new__属于真正需要自定义创建流程时才用的手段。
2.2 __del__的时机问题：为什么不要依赖它做资源清理
__del__是对象被销毁时的钩子，但它不是C++的析构函数，时机并不可控。Python使用引用计数为主、垃圾回收为辅的内存管理，一个对象的__del__真正执行，通常要等它的引用计数降到零；如果存在循环引用，还要等gc模块的收集周期触发。更麻烦的是，解释器在退出时会对所有模块进行清理，如果__del__里访问的是一个已经被清理掉的模块对象，很可能直接抛NameError。
我自己的经验是：释放文件、网络连接、锁这些资源，永远优先使用with语句的__enter__/__exit__，或者try/finally，而不是在__del__里做。__del__适合做什么？适合做"最后兜底的调试日志"，不适合做"关键资源的唯一释放点"。如果你确实需要精确控制资源的生命周期，上下文管理器才是Python给出的正解。
3. 运算符与比较协议：怎样让自定义类无缝融入Python生态
3.1 算术运算符的三种方法：add、iadd、radd
一个类实现了__add__，它就能参与+运算。比如自定义一个金额类型：
class Money: def __init__(self, amount): self.amount = amount def __add__(self, other): if isinstance(other, Money): return Money(self.amount + other.amount) if isinstance(other, (int, float)): return Money(self.amount + other) return NotImplemented def __radd__(self, other): return self.__add__(other) def __repr__(self): return f"Money({self.amount})"这里有几个细节值得展开。
第一个是__radd__。当解释器执行100 + money时，左边的int并没有实现__add__来认识Money，解释器就会尝试调用右边对象的__radd__，也就是反向运算方法。所以只写__add__的话，money + 10能用，10 + money会抛TypeError。很多自定义数值类型都忘了这一点。
第二个是NotImplemented。在__add__里遇到不认识的类型，不应直接抛TypeError，而应该返回NotImplemented这个单例，告诉解释器"我处理不了这种类型"，让它继续尝试别的方案。如果双方都返回NotImplemented，最终解释器才会抛TypeError。这个习惯能避免一些奇怪的类型兼容问题。
第三个是__iadd__，对应+=。如果没有实现__iadd__，Python会退化成执行__add__然后重新赋值，结果通常一样但性能稍差，而且新对象替换了旧对象。对于可变容器，实现__iadd__以后，+=是在原地修改，更高效。写自定义容器时值得关注。
3.2eq、__hash__必须成对设计
这是魔法方法联动中最出名的一个坑。Python规定，一个对象作为字典的key、放进set，必须可哈希；而一个对象一旦重写了__eq__，默认的hash实现就会被禁用——Python会把这个类的__hash__设为None。这个设计是有道理的：两个对象相等意味着它们在哈希容器里应该被视为同一个元素，如果它们的哈希值不同，哈希容器就找不到它们了。代价就是，初学者只写__eq__不写__hash__，一放进set立刻报TypeError: unhashable type: 'X'。
实际项目中定义数据类时，如果只是做相等性比较，可以两者都写上：
class Money: def __init__(self, amount, currency): self.amount = amount self.currency = currency def __eq__(self, other): if not isinstance(other, Money): return False return (self.amount, self.currency) == (other.amount, other.currency) def __hash__(self): return hash((self.amount, self.currency))需要注意，__hash__必须和__eq__保持一致，相等的对象哈希值必须相同。最简单省事的做法是：把参与相等判断的字段打包成元组，直接hash。另外提醒一句，用@dataclass(eq=True, frozen=True)可以自动生成这两个方法，但理解原理仍然重要，因为在复杂的继承场景下，自动生成并非永远符合预期。
3.3repr__与__str：调试体验的分水岭
__repr__的目标是"无歧义"，理想情况下，repr(obj)的结果可以直接用来重建一个等价对象；__str__的目标是"可读"，面向终端用户。print(obj)优先找__str__，找不到了才用__repr__；而在列表、字典这些容器里显示元素时，用的是__repr__。我见过不少代码只写了__str__，结果打印列表时对象显示成<__main__.X object at 0x...>，调试起来一头雾水。
我的建议很简单：自定义类至少把__repr__写好。哪怕只是返回self.__class__.__name__加上关键字段的字典形式，都能让日志和交互式调试舒服很多。有个常见的偷懒写法是：
def __repr__(self): return self.__str__()我不推荐这样。它把两个语义不同的方法强行绑在一起，一旦想给用户显示更友好的字符串，又要回头重构。不如一开始就分开写：__repr__给出构造参数的准确展示，__str__再根据需要做用户友好包装。
4. 属性访问与可调用对象：getattr、setattr、__call__的经典用法
4.1 __getattr__和__getattribute__的分工差异
两个方法名字很像，但触发条件完全不同：__getattr__只在正常查找找不到属性的时候触发；__getattribute__则是每次任何属性访问都会触发。正因如此，__getattribute__雷区极多，一个不小心在里面访问self.xxx，就会无限递归。相比之下，__getattr__是更常用、更安全的扩展点。
一个典型使用场景是"懒加载"或者"虚拟属性"。比如一个配置对象，希望访问config.api_key时，如果本地没有，就去环境变量里取，同时把结果缓存下来：
import os class Config: def __init__(self, defaults=None): self._defaults = defaults or {} def __getattr__(self, name): if name in self._defaults: value = self._defaults[name] else: value = os.getenv(name.upper(), "") setattr(self, name, value) return value这里有个细节很多人踩过坑：setattr(self, name, value)会把值写入实例的__dict__，之后再次访问config.api_key时，解释器在实例字典里直接找到了值，不会再进入__getattr__，所以缓存成立。如果写的是self.__dict__[name] = value也可以，但setattr更直白。要提醒的是，__getattr__里做任何普通属性赋值都会再次走属性访问逻辑，如果类里重写了__setattr__，还会触发它，设计时要综合考虑。
4.2 用__setattr__统一做字段校验
如果一个数据类有好几个字段，每个字段都有类型要求，散落在构造函数里逐个if判断，业务代码会变得很啰嗦，而且新增字段时很容易漏掉校验。把校验逻辑集中在__setattr__里，是这类场景里相当实用的做法：
class Point: def __init__(self, x, y): self.x = x self.y = y def __setattr__(self, name, value): if name in ("x", "y") and not isinstance(value, (int, float)): raise TypeError(f"{name} must be int or float, got {type(value).__name__}") super().__setattr__(name, value)这段代码看起来简单，但内部有个值得注意的递归问题：__init__里的self.x = x会触发__setattr__，而__setattr__里用super().__setattr__绕过自己，调object的默认实现，这才避免无限递归。如果直接用self.__dict__[name] = value，效果类似但绕过了描述符协议，在属性是property或slot时可能出错，所以super().__setattr__是更稳妥的写法。
实际使用中，我一般只在字段数量少、约束明确的类上用这种方式；字段多了还是用数据验证库更清晰。这个手法最适合的，是给那种内部流转的简单值对象加一层轻量约束，防止脏数据混进核心逻辑。
4.3 用__call__管理调用状态
实现了__call__之后，类的实例就可以像函数一样被调用。这在需要"带状态的函数"时特别好用。比如一个简单的调用次数统计器：
class CallCounter: def __init__(self, func): self.func = func self.count = 0 def __call__(self, *args, **kwargs): self.count += 1 return self.func(*args, **kwargs) @CallCounter def process(data): return len(data) process([1, 2, 3]) process([4, 5]) print(process.count) # 2在这里，__call__让实例天然拥有了计数状态，比写闭包加nonlocal更直观。也常见于重试器、缓存包装、命令行工具的subcommand分发等场景。判断什么时候用可调用对象而不是普通函数，我的经验是：只要这个"函数"需要长期保持一些状态，或者需要多种配置方式，类加__call__通常更清晰；如果只是临时用一次，闭包就够了。
5. 接入语言语法：with语句和for循环背后的两套协议
5.1 上下文管理器协议：enter__与__exit
with语句是Python里资源管理的主流写法，它依赖的就是__enter__和__exit__这对方法。执行with语句时，解释器先调__enter__，把返回值绑定给as后面的变量；语句体结束后，无论是否发生异常，都会调__exit__。__exit__接收三个参数：异常类型、异常值、异常堆栈回溯。如果__exit__返回True，就表示异常已被处理，不会继续向上抛；返回False或None，异常会继续传播。这个"吞异常"的能力要慎用，大多数情况下应该让异常流动，偶尔用于上下文内部的错误归一化。
一个典型的连接资源封装：
class ManagedConnection: def __init__(self, conn): self.conn = conn def __enter__(self): self.conn.open() return self.conn def __exit__(self, exc_type, exc_val, exc_tb): self.conn.close() return False写这种类不需要考虑业务异常是什么，__exit__里负责清理，然后原样把异常交还上层。顺便提一句，如果只是清理资源，contextlib里的@contextmanager装饰器能省去手写类的麻烦，把一段普通的生成器函数变成上下文管理器，yield之前的代码相当于__enter__，yield之后的代码相当于__exit__。我的优先级是：标准库自带with功能的就复用；需要精细控制返回值或异常吞噬逻辑时才手写协议类。
5.2 可迭代对象与迭代器：iter__与__next
for循环能遍历一个对象，本质是两件事：先调用iter(obj)拿到一个迭代器，然后不断调用next(迭代器)直到抛StopIteration。如果一个类实现了__iter__且返回一个实现了__next__的迭代器，它就是可迭代的。这里有一个常见坑：__iter__如果不返回新迭代器而是返回self，那么同一个可迭代对象就只能被完整遍历一次，第二次遍历时迭代器已经停在末尾，得到空结果。
写一个每次遍历都从零开始的自定义序列，推荐写法是让__iter__返回一个独立的迭代器对象：
class RangeByStep: def __init__(self, start, stop, step=1): self.start = start self.stop = stop self.step = step def __iter__(self): current = self.start while current < self.stop: yield current current += self.step这里用生成器函数配合yield，实际上是Python自动创建了一个即时迭代器，每次for循环调用iter()都会重新执行生成器，所以可以反复遍历。另外，如果一个对象没有__iter__但有__getitem__，且__getitem__在越界时抛IndexError，那么它也能被for循环按索引逐个访问。这是旧式迭代协议，现在一般只在兼容场景见了。
5.3 容器协议与切片：getitem、setitem、len
容器协议的核心是__getitem__和__setitem__。实现了__getitem__的对象支持obj[key]读取；实现了__setitem__支持赋值；实现了__delitem__支持del obj[key]。一个常见用途是封装内部列表或字典，对外提供受控的访问。同时，如果想支持切片obj[1:3]，__getitem__接收到的key会是一个slice对象，需要单独判断。很多人第一次写自定义容器时，默认key是整数，遇到切片就出错。处理办法是：
def __getitem__(self, key): if isinstance(key, slice): return [self._data[i] for i in range(*key.indices(len(self._data)))] return self._data[key]slice.indices能把切片映射成具体的star、stop、step，是个很实用的工具方法。注意，如果没有实现__iter__但实现了__getitem__，for循环也能工作，因为它会从0开始不断尝试__getitem__(0)、__getitem__(1)直到遇到IndexError。这个回退机制让老版本Python里只要写__getitem__就能遍历，也解释了为什么有些代码不写__iter__也能被for循环使用。
6. 双下划线方法实战中容易踩的雷区
6.1 定义__eq__后哈希失效的现场还原
前面说过，重写__eq__会让__hash__被禁用。这个坑我在项目里真实遇到过：定义了一个带__eq__的数据类，把实例装进列表做去重，结果set(records)直接抛TypeError: unhashable type。排查时先怀疑数据里混入了什么奇怪对象，打印类型发现就是自己定义的那个类，才意识到是__hash__被自动设为None。修法就是补上__hash__，并把参与相等判断的字段打包哈希。这个问题的隐蔽性在于，代码里根本没写任何跟哈希有关的东西，错误信息却指向类型不可哈希。
如果你在用@dataclass，设置eq=True但frozen=False时，dataclass会生成__eq__并自动把__hash__设为None。想保留哈希，最简单的是加frozen=True，这样dataclass会同时生成__eq__和__hash__。不过要注意，frozen=True意味着字段在创建后不可修改，为了哈希安全，这个约束其实是有必要的。
6.2 __getattr__里访问同名属性导致无限递归
这个坑相对隐蔽。当__getattr__内部写self.name去读取一个不存在的属性时，会再次触发__getattr__，形成无限递归，程序报RecursionError。我见过不止一次这样的代码：
def __getattr__(self, name): if name.startswith("_"): raise AttributeError(name) value = self._internal_get(name) return value问题在于，self._internal_get这个属性如果本身不存在，它又要经过__getattr__，于是循环往复。更稳妥的做法是在__getattr__里避免访问任何实例属性，要么直接用object.__getattribute__(self, name)这种底层调用，要么把依赖的数据存在另一个不会触发__getattr__的地方。这是我认为最值得背下来的一个模式：在自定义属性访问逻辑时，永远先想清楚"我在这里访问的属性，会不会再次走进这个方法"。
6.3 __slots__与魔法方法互动的坑
定义了__slots__的类没有实例字典，很多魔法方法本身是按实例属性查找实现的，就会受到影响。比如一个类实现了__slots__ = ('x', 'y')，如果没有把'__weakref__'加进slots，这个类就不能被weakref；如果在__getattr__里想读写实例dict，也会直接报错。更常见的坑是我遇到过的：在__slots__类里实现了__eq__，但新代码在旧解释器进程里运行，导致新增方法访问报AttributeError。这种问题通常重启解释器就消失，但排查起来很费时间。
我的建议是：除非类会大量实例化、且性能测试证明内存占用是瓶颈，否则不要用__slots__。它带来的内存收益在常规项目中不明显，却会牺牲灵活性。如果真的要用，把会用到的魔法方法列清楚，并且记得测试代码要在干净的解释器进程里跑。
最后再分享一个我自己的习惯。拿到一个类，我会先在注释里写一句话：这个对象在Python生态里应该"像什么"。像数字，就实现算术协议；像集合，就实现容器协议；像函数，就实现__call__；像资源，就实现上下文管理器。每个协议只实现该实现的那一组方法，不多不少。这样写出来的类，放进去in判断、能进set、能for遍历、能with管理，都像是天生如此，而不是靠一堆if isinstance的临时补丁。
还有一个实际开发里很有用的小技巧：在交互式环境里对任意对象执行dir(obj)，出来的以双下划线开头的方法列表，就是你眼前这个对象支持的全部协议接口。看到哪个方法名字眼熟但不确定作用，直接试试调用或者查一下标准库文档，比死记硬背列表强得多。魔法方法这东西，理解机制比记住名字重要，机制通了，名字随时可以查。
