每个写过几年 Python 的人心里基本都有这么几个转折点第一次看懂列表推导式、第一次用装饰器、第一次被生成器绕晕。但真正让我觉得“这门语言有点东西”的是搞明白魔法方法Magic Methods的那段时间。单看名字很玄乎那双下划线开头结尾的方法什么__init__、__str__、__getitem__刚接触时总觉得是某种黑魔法。实际上剥开来看魔法方法就是 Python 留给你的“协议接口”——只要你把对应的方法实现出来你的类就能像内建类型一样参与语法层面的运算。len(obj)能不能用、obj[0]能不能取、for x in obj能不能迭代、obj other怎么比较、with obj能不能进全部由这些方法决定。这篇文章不打算按照官方文档把几十个方法挨个念一遍而是想从“我实际写业务代码时怎么用”的角度把这些方法归类拆开讲清楚每个方法背后的设计意图、常见坑位、以及什么时候真的需要自己实现。内容适合已经掌握了类、继承、装饰器这些基础、但还不太确定“魔法方法到底怎么落地”的读者也适合回头想补一遍进阶的开发者。读完之后你至少能回答一个问题想让自己的类表现得像 list、dict、int 或者 context manager到底该实现哪几个方法、注意哪些边界条件。1. 魔法方法到底是什么——先弄清楚设计意图1.1 魔法方法在 Python 语言中的定位很多教程把魔法方法解释成“允许自定义类加入 Python 语法生态的特殊方法”这句话方向是对的但不够具体。我自己理解它更愿意把它看成一套协议Python 解释器在遇到特定语法时会去对象上查找对应名字的方法找到了就调用找不到就走默认逻辑或者报错。举个例子你写obj other解释器不会直接说“这两个对象不能相加”而是先去obj的类型里找__add__没有就去other的类型里找__radd__二者都没有才抛TypeError: unsupported operand type(s)。len(obj)会触发__len__obj[key]会触发__getitem__obj()会触发__call__。所以从另一个角度看魔法方法就是 Python 语法到对象行为的映射表。这张映射表设计得很聪明因为它让语法层保持相对稳定让具体实现开放给了用户类。你不需要改变语言本身只需要在类里实现一个方法就能让自定义对象融入语言既有的表达方式。这也是 Python“鸭子类型”哲学的延伸——不要求你的类继承自某个特定基类只要你实现了该有的方法语法就能生效。1.2 什么时候该自定义魔法方法什么时候不该一个很容易被忽略的问题不是所有类都需要魔法方法。很多业务对象的类规规矩矩地写完__init__就够了。觉得“魔法方法越多越厉害”是新手阶段常见的心态但实际项目里更重要的是知道哪些场景才值得写。我自己判断的标准主要有三条。第一对象需要参与语法层面的操作比如放进一个容器里做相等性判断、排序、拼接或者需要支持in判断这时候不实现对应的魔法方法代码写起来就会很别扭。第二对象有明确的“自然行为”比如一个学生类用str(student)打印出姓名和学号是合理的用len(student)返回选课数量也可以接受这些行为如果跟常规直觉一致实现魔法方法是加分项。第三需要控制对象的生存周期或者资源释放比如连接池、文件句柄、临时环境变量这类场景实现上下文管理器协议能让代码大幅简化。反过来说如果一个类只是单纯的数据容器未来可能还要改内部存储结构那就不适合把所有魔法方法都堆上去。过度实现会让类的接口变“胖”后续维护成本跟着上升。而且魔法方法在查找时会绕开实例字典直接走类型一旦实现的逻辑有副作用排查起来往往比普通方法更难。2. 最常用的魔法方法让类像内建对象一样工作2.1 对象创建与销毁__init__、__new__、__del__这一组是大多数人最早接触的魔法方法但里面隐藏的细节远不止“写构造函数”这么简单。__init__负责在实例创建之后做初始化动作它的第一个参数是self也就是已经构造好的实例对象。注意__init__不负责“创建”对象真正创建对象的是__new__。__new__是类方法但不需要显式加classmethod装饰器它在实例真正生成之前被调用返回值决定__init__有没有机会执行。如果你在__new__里返回了一个不属于目标类型的对象Python 会直接跳过__init__。这里有一个实用场景实现单例模式时很多人喜欢改写__new__在创建前判断实例是否已经存在存在就直接返回旧实例。这种写法比在__init__里搞状态判断更干净因为__init__在单例复用的情况下会被重复调用容易把已有数据重置掉。不过我的建议是单例尽量用模块级变量去管理真要类做单例再考虑__new__否则调试的时候“构造函数明明执行了但对象不是新的”这个现象很容易让人绕进去。__del__这个方法的坑最多。它不是在对象引用计数归零的瞬间保证执行而是在 GC 回收对象时触发并且不保证一定会被调用。程序的异常退出、解释器关闭时仍然存活的全局对象都可能不触发__del__。所以不要指望它来做关键资源释放。需要用with或try/finally保证释放的资源文件、锁、数据库连接一律走上下文管理器协议而不是__del__。2.2 字符串与显示__str__、__repr__、__format__一个非常经典的问题__str__和__repr__到底有什么区别官方解释是__repr__面向开发者目标是无歧义__str__面向用户目标是可读。但落到代码里很多人还是分不清该实现哪个。从调用时机来说print(obj)优先找__str__找不到就退回__repr__直接查看变量比如 REPL 里输入变量名回车显示的是__repr__使用 f-stringf{obj}在 Python 3 中优先找__str__但f{obj!r}会强制走__repr__。还有一个容易忘的str(obj)如果两个都没实现默认输出的是__main__.Foo object at 0x7f...完全没有信息量对调试很不友好。我的习惯是任何自定义类都先实现__repr__因为它是最低限度的调试工具。输出格式尽量做到ClassName(keyvalue)这种“能看出类型、关键状态、核心参数”的样子。比如一个表示商品的类__repr__返回Product(skuA1001, price35.9)调试时一眼就能看清对象是什么、关键属性是什么。如果这个类还要展示给最终用户再补充实现__str__返回好看的展示文本。__format__用得相对少但当你需要支持f{obj:.2f}这类格式说明符时就要自己处理格式串了这个按需实现即可不常写。2.3 比较与哈希__eq__、__hash__、__lt__的连带关系先给一个大多数入门者不知道的结论如果你在类里定义了__eq__却没有同时定义__hash__这个类的实例会变成不可哈希的。因为 Python 有一条默认规则两个对象相等的话哈希值也应该相等。__eq__一旦被重载默认的__hash__会被一并禁用防止你出现“a b 成立但 hash(a) ! hash(b)”这种违反字典和集合不变量的事。所以如果你想让对象同时支持相等比较和放进 dict/set必须成对实现这两个方法。实现时记住一条黄金法则求哈希使用的字段必须和相等比较使用的字段保持一致。比如__eq__比较id和name那__hash__就应该hash((self.id, self.name))。如果你在__eq__里比较了很多字段但__hash__只取了id那id相同但其他字段不同的对象会被塞进同一个哈希桶然后因为__eq__返回 False 而共存。功能上倒不会错但散列效果会很差性能崩得莫名其妙。还有一个更隐蔽的坑可变对象不要参与哈希。如果对象的__hash__依赖的字段在放入 dict 之后被修改了你再根据原 key 去查找时哈希值已经变了元素就找不到。这就是为什么 list、dict、set 自身不可哈希因为它们是可变容器。如果你设计的对象是可变的比如有 setter 方法就不要提供__hash__或者在文档里明确告诉用户“放进 dict 后不要修改关键字段”。关于排序__lt__是优先级比较高的一个方法。Python 3 里已经没有__cmp__了排序时只靠操作符。你写sorted(lst)如果列表里的对象是自定义类内部会用来比较。只实现__lt__而不实现__gt__、__le__、__ge__也能让sorted正常工作因为排序算法主要依赖。但如果你调用a b那还是需要__gt__的。这里可以偷个懒用functools.total_ordering装饰器只需要实现__eq__和其中一个比较方法比如__lt__装饰器会自动补出其他几个比较方法。实测下来这个装饰器很方便但有轻微性能损耗如果排序是热点路径并且对象量极大建议还是手动把几个方法写全。2.4 数值运算系列__add__、__radd__、__iadd__的数据流数值运算可能不是业务代码里最常见的魔法方法但在写一些自定义数值类型、向量类、金额类、矩阵类的时候很有用。这里最关键的其实是理解“左操作数优先、右操作数兜底”的调度规则。a b执行时会先在a的类型里找__add__如果a没有实现或者返回了NotImplemented再去b的类型里找__radd__。很多人第一次看到NotImplemented会以为它是NotImplementedError的省略写法其实是完全不同的两样东西NotImplementedError是异常抛出去表示“方法未实现”NotImplemented是单例值返回它表示“我不会处理这个操作请你试试对方的反向方法”。举个例子一个表示金额的类class Money: def __init__(self, amount): self.amount amount def __add__(self, other): if isinstance(other, Money): return Money(self.amount other.amount) return NotImplemented def __radd__(self, other): if isinstance(other, (int, float)): return Money(self.amount other) return NotImplemented这样写money 100和100 money都能工作。前一个走Money.__add__处理int后一个先尝试int.__add__但int不会处理Money于是退回Money.__radd__。这里有个常见遗漏很多人写了__add__却忘了__radd__结果100 money直接抛TypeError排查半天不知道问题出在哪。__iadd__对应的是运算。要特别注意__iadd__返回的值会被重新赋值给左边的变量。对于可变对象可以在原对象上做修改后return self对于不可变对象可以直接返回一个新对象效果等同于a a b。如果你没有实现__iadd__Python 会退回去做a a b也就是调用__add__。所以这里有一个性能选择如果对象是可变的、并且原地修改更高效就应该实现__iadd__避免无谓的新对象创建。典型例子是list和set的行为它们都是原地修改但tuple没有__iadd__执行t (1, 2)其实是生成一个新 tuple。3. 序列与容器的魔法方法让你的类支持索引和迭代3.1 索引与切片__getitem__、__setitem__、__delitem__如果深入理解 Python 的容器协议你会发现它其实很宽松你只需要实现__getitem__这个对象就可以被索引、切片、迭代甚至用in判断。但接口宽松不等于实现简单这中间有不少细节。写__getitem__时obj[0]和obj[0:3]传入的第二参数类型是不同的前者是 int后者是 slice 对象。如果你想正确处理切片需要自己解析slice.indices(length)来得到真正的起始、结束、步长。一个很容易踩坑的场景是你内部存的是一个大列表想直接透传索引逻辑class MyCollection: def __init__(self, items): self._items items def __getitem__(self, index): return self._items[index]上面的代码看起来没毛病但它把切片行为完全委托给了内部列表。如果内部数据结构换成了字典或者自定义结构index可能是任何类型。更稳妥的做法是显式处理 int 和 slice 两种分支。另外__getitem__在索引越界时应该抛IndexError这既符合惯例也是让for ... in obj停止迭代的必要条件。对你没看错一个只实现了__getitem__的类是可以直接放进for循环里迭代的。迭代器协议会先找__iter__找不到就退回__getitem__协议从 0 开始逐个递增索引调用遇到IndexError就停止。这个兼容行为在 Python 2 时代是迭代器的默认机制3.x 里虽然不推荐依赖它但它仍然有效。__setitem__对应obj[key] value__delitem__对应del obj[key]。实现它们时注意边界处理和类型校验。很多人在__setitem__里不做类型判断让任意类型的数据混入容器后面排序、计算时才发现问题那就要回头改很多地方。3.2 迭代器协议__iter__、__next__、__len__、__contains__的组合用法实现__iter__方法时最常见的方式有两种第一种是返回self并在类里同时实现__next__让对象自身成为自己的迭代器第二种是返回一个生成器对象利用yield语法惰性生成数据。两者各有适用场景。如果你要表示的是“可迭代对象”而不是“迭代器”更推荐用生成器方式。比如class Week: def __iter__(self): for day in [Mon, Tue, Wed, Thu, Fri, Sat, Sun]: yield day这个类可以反复迭代每次for循环都会新建一个生成器状态是独立的。而如果让对象自己当迭代器同一时刻只有一个迭代位置第一轮循环跑完之后再跑第二轮就不会再有数据了。当你要迭代的对象本身没有“当前位置”这个概念时用生成器是更安全的选择。__len__除了配合len(obj)调用之外还会影响bool(obj)的默认判断逻辑。如果一个类没有实现__bool__Python 会尝试调用__len__长度为零返回 False。所以很多容器类只实现__len__就能获得“空对象是假值”的行为。同理如果你希望自己的对象能直接用if obj:判断真假可以先想想这个“真”到底是什么含义——是长度非零还是某个自定义标志位。想要自定义判断逻辑就需要实现__bool__它的返回值会被自动转成布尔值。__contains__对应in运算符。如果你在类里实现了它x in obj就会走你的方法如果没有实现Python 会退化成迭代对象并逐个比较。对于包含大量数据、或者有高效查找方式的容器比如内部维护了一个 set实现__contains__能大幅提升in判断的性能。不要小看这个方法它属于典型的“不实现也能跑但实现了能救性能”的类型。3.3 让实例像函数一样调用__call__的适用场景__call__可能是所有魔法方法里最容易被忽略但最实用的一个。实现它之后类的实例可以用obj(...)这种语法调用。这个特性在几个场景下特别有用。一个非常典型的使用场景是有状态的函数替身。普通函数是无状态的但通过函数属性或者闭包可以携带状态写起来却不太方便。而用带__call__的类状态就是实例属性初始化、重置、查询都一目了然。比如一个累计统计器class Counter: def __init__(self): self.total 0 def __call__(self, value): self.total value return self.total这个类不仅可以用c Counter(); c(5)调用还能随时查看c.total重置时c.total 0比用闭包加nonlocal的方式更容易理解。另一个场景是装饰器工厂很多框架的装饰器本身就是带__call__的类这样可以让装饰器同时携带参数和状态。还有一点值得注意实现了__call__的对象callable(obj)会返回 True。这意味着你可以把它作为回调函数传给别的库比如排序的key、事件绑定、命令注册等。如果你的对象需要保存一些配置信息并在触发时执行相应动作用__call__设计比写一个普通方法要自然得多。4. 上下文管理器与属性管理的魔法方法4.1 上下文管理器协议__enter__、__exit__的完整解析with语句背后的机制是上下文管理器协议进入with块时自动调用__enter__退出时无论是否抛异常都会调用__exit__。这组魔法方法在实际工程里非常重要涉及文件、锁、连接、临时环境变量等场景时它是保证资源正确释放的最可靠方式。实现__enter__时返回值会成为as后面的变量。比如class ManagedResource: def __enter__(self): print(acquire resource) return self def __exit__(self, exc_type, exc_val, exc_tb): print(release resource) return False__exit__接收四个参数异常类型、异常实例、traceback 对象第三个参数在处理某些需要查看调用栈的场景里很有用。如果with块内没有发生异常这三个参数都是 None。__exit__的返回值决定异常是否被“吞掉”返回 True 表示已经处理了异常外部不会再收到异常返回 False 或 None 表示异常会继续向外传播。这是一个很微妙的点一般业务代码建议返回 False不要让异常被静默吞掉。一个非常实用的小技巧是在__exit__里做资源清理和异常记录然后返回 False 让异常继续传播。这样资源释放和错误处理被整齐地分开调用方仍然能看到原始异常同时你也拿到了执行 after 阶段的机会。另外提醒一句contextlib.contextmanager可以用生成器的方式快速创建上下文管理器写起来更简洁。如果你只需要一个函数级别的上下文管理而不是一个完整的可复用类用它会更顺手。但如果你需要维护复杂的内部状态、支持嵌套、或者需要继承复用那自己实现__enter__和__exit__还是更合适。4.2 属性访问控制__getattr__、__setattr__、__getattribute__的区别属性访问相关的魔法方法很容易弄混核心在于理解它们各自的触发时机和查找顺序。__getattr__只在正常属性查找失败时被调用。也就是说访问一个并不存在的属性并且实例字典、类字典、父类链上都没有找到这时才会触发__getattr__。利用这个特性可以做“惰性属性”“动态代理”“伪属性”等功能。比如一个从字典初始化的类class AttrDict: def __init__(self, data): self._data data def __getattr__(self, name): if name in self._data: return self._data[name] raise AttributeError(name)这样一来obj.name就能自动映射到self._data[name]上。注意__getattr__里如果什么属性都返回默认值会导致hasattr(obj, xxx)永远为 True排查 bug 时会非常迷惑。所以不存在的属性应该主动抛出AttributeError保持默认语义。__getattribute__则不同它是所有属性访问的入口每次访问属性都会先经过它。这意味着在这个方法里访问self.xxx会再次触发__getattribute__形成无限递归。正确的写法是使用object.__getattribute__(self, name)来访问真正的属性。这个方法的杀伤力比较大如果不是在写框架或者做代理层我建议尽量别动它。__setattr__在所有属性赋值时被调用同样存在递归风险。在__setattr__里给实例设定属性不要直接写self.xxx value而是用object.__setattr__(self, xxx, value)。通常需要覆盖__setattr__的场景包括属性值校验、设置后自动触发副作用比如设置某个字段后更新缓存、以及阻止某些属性被外部修改。还有__delattr__对应del obj.attr如果要禁止删除某些属性可以在这里做限制。4.3__slots__不只是节约内存严格来说__slots__不算是带双下划线的方法而是一个类属性但它跟属性访问机制息息相关而且在性能优化里很常见所以放在这里一起说。默认情况下Python 的类实例用字典存储属性也就是__dict__。字典灵活但内存占用偏高。在需要创建大量对象的热点场景比如解析大文件生成百万行对象、批量计算实体__slots__可以发挥明显作用。定义一个类class Point: __slots__ (x, y) def __init__(self, x, y): self.x x self.y y这样每个实例不再维护__dict__只保留固定属性的存储空间内存占用可以下降不少。不过天下没有免费的午餐用了__slots__之后实例不再能随意添加新属性。如果你想保留灵活性可以显式地在__slots__中加入__dict__但那等于又退回了字典存储模式内存收益就打折了。还有一点常被忽视继承时子类如果不定义__slots__还是会拥有__dict__。所以父类用__slots__节约下来的空间被子类一把抢了回去。子类想要继续享受这个优化需要在自己的定义里也写上__slots__。我在实际项目里见过不少这种“父类设了 slots子类没设结果内存跟没优化一样”的情况排查时很难想到是这里的问题。5. 更多进阶魔法方法知道它们能让代码更地道5.1__bool__与__copy__、__deepcopy__的边界行为__bool__用于自定义对象的真值判断。默认情况下所有实例都是 True但如果类实现了__len__长度为 0 时会返回 False。所以一个很隐蔽的坑是你的类定义了__len__并且len()的语义是“容器里的元素个数”那么if obj:就会意外地变成“非空才为真”。如果你想让“对象存在”即为真不管容器是否为空就需要显式实现__bool__返回 True。copy.copy和copy.deepcopy默认行为其实挺智能的一般不需要专门实现。但有一种情况对象持有锁、文件句柄、连接池等不可复制资源时默认复制会带来隐患。比如一个持有线程锁的对象被复制后新对象和旧对象可能指向同一个锁对象导致锁的语义被破坏。在这种情况下你需要实现__copy__和__deepcopy__明确控制复制时哪些资源要被重新创建、哪些可以被共享。这组方法属于“平时用不到用到时能救命”的类型。5.2 运算符映射的其他细节反向运算与就地运算的优先级前面讲过__add__、__radd__、__iadd__这一组。实际上整个运算符家族都存在类似的三件套__sub__和__rsub__、__mul__和__rmul__、__truediv__和__rtruediv__等。反向运算的触发规则是一致的左操作数不会处理该操作时右侧类型的反向方法才有机会执行。这里有一个值得注意的优先级细节NotImplemented是值不是异常但很多人的代码里写return NotImplemented后会习惯性地担心“是不是抛异常了”。实际上它只是告诉解释器“这个方法不处理这个类型”解释器继续尝试其他方案。如果所有方案都返回NotImplemented最终才抛出TypeError: unsupported operand type(s)。所以你在实现反向运算时一定要返回NotImplemented而不是抛出它这样 Python 才能尝试下一个路径。有一个例子可以验证对反向运算的理解money * 2和2 * money。前者走Money.__mul__后者会先从int.__mul__尝试int明显不认识Money类型于是 go toMoney.__rmul__。如果你只实现了__mul__而没有__rmul__2 * money一定会报错。很多人在写数值运算类时只做了一半导致只能用“对象在左边”的方式限制很大。5.3__getattribute__和__setattr__之外__dict__与__class__的关系不少初学者分不清obj.__dict__、type(obj).__dict__、obj.__class__这几个东西。obj.__dict__是实例自己的属性字典绝大多数实例属性都存在这里面type(obj).__dict__是类对象自己的属性字典存放类方法和类变量obj.__class__返回对象的类它是建立在类型系统之上的一个元属性。实现属性控制时经常要跟这几位打交道。一个常见误解是访问obj.attr时Python 会先找实例__dict__再找类__dict__最后沿着 MRO 找父类。这个流程在普通未重载__getattribute__的类上是成立的。但如果你重载了__getattribute__这个“先找实例__dict__”的步骤就变成了由你的代码自己控制。比如你可以先检查类上有没有某个特殊标记再决定属性查找怎么走。这种用法适合做“智能属性分发”的场景但性能开销和递归风险都不小建议只在写框架时用。6. 常见问题与排查技巧实录6.1 为什么两个“看起来一样”的对象不相等这是我在排查他人代码时非常常见的问题两个对象字段一样用比较却返回 False。原因很简单因为默认的__eq__就是“比较是否是同一个对象”也就是is的身份比较。要让两个内容相同的对象相等必须显式实现__eq__。很多人以为 Python 会像值类型那样自动比较字段实际上 Python 没有这个默认行为。实现__eq__时还要注意两点一是先判断另一个对象是否为NotImplemented状况灵活处理不同类型的比较二是不要忘了同时处理__hash__。而且实现__eq__后最好把对象设计成“关键字段不可变”避免出现前面讲过的哈希污染问题。6.2__repr__和__str__到底实现哪个我的建议是先实现__repr__再按需实现__str__。因为__repr__是调试时最直接的信息来源并且print(obj)、f-string、日志输出在找不到__str__时都会退回__repr__。很多实际方案里两个方法返回的内容可以相同也可以__str__返回更友好、更短的展示文案。如果你在 f-string 里想强制显示__repr__的结果用f{obj!r}即可。在调试日志、异常信息里我会倾向于让__repr__输出能反映对象核心字段的内容这样一条日志就能定位对象状态。这个习惯在排查线上问题时能节省大量时间。6.3 其他高频问题速查问题原因解决方式TypeError: object is not subscriptable类没有实现__getitem__根据实际语义实现__getitem__或改用.get()等普通方法TypeError: XXX object is not iterable类没有实现__iter__或者__getitem__实现__iter__返回迭代器/生成器TypeError: object does not support item assignment类没有实现__setitem__实现__setitem__或在类内部转成可变容器再赋值XXX object is not callable类没有实现__call__确认是否需要可调用语义需要则实现__call__unhashable type: XXX定义了__eq__但没定义__hash__同时实现__hash__或者用不可变字段做哈希TypeError: unsupported operand type(s) for 缺少__add__/__radd__补实现对应运算方法返回NotImplemented处理不支持的类型定义__slots__后无法添加新属性__slots__限制了实例属性集合恢复__dict__或者把需要添加的属性提前写入__slots__len(obj)结果不对__len__返回值必须是整数且不小于 0检查返回值类型必要时转成 int除了表格里的这些还有一个实操时的独家建议在实现多个魔法方法后可以做一个“协议自检”小实验。比如写一个快速的测试脚本分别测试索引、切片、迭代、比较、布尔值、in判断、with进出、callable把行为打印出来。这样能一次性暴露出大多数魔法方法之间的联动问题。很多隐藏 bug 其实是“实现了单个方法但方法之间互相冲突”导致的单独看每个方法都对组合起来就会出问题。这轮讲下来最深的感受是魔法方法并不是什么高深莫测的黑魔法它就是 Python 对“对象行为协议”的一种约定。搞清楚它们本质上是在理解 Python 解释器怎么看待你的类。平时写业务代码时不需要把所有方法都背下来但至少应该知道这几件事对象怎么被创建和销毁、怎么显示、怎么比较、怎么支持容器操作、怎么管理属性、怎么配合with和运算符。每个方向记住几个关键方法用的时候查一下签名和注意事项就够了。最后说一个小技巧也是我常用的习惯给自定义类写完魔法方法后顺手写一个对应的 dunder 方法清单标注哪些是必须同时成对出现、哪些会影响其他行为。这样过几个月回来看代码不用重新推一遍也能快速想起当时的设计意图。Python 的设计哲学是“让显式优于隐式”魔法方法恰恰是在隐式语法和显式实现之间搭了一座桥。掌握好这座桥写出来的代码会更自然也更接近这门语言本来的样子。
每个写过几年 Python 的人心里基本都有这么几个转折点第一次看懂列表推导式、第一次用装饰器、第一次被生成器绕晕。但真正让我觉得“这门语言有点东西”的是搞明白魔法方法Magic Methods的那段时间。单看名字很玄乎那双下划线开头结尾的方法什么__init__、__str__、__getitem__刚接触时总觉得是某种黑魔法。实际上剥开来看魔法方法就是 Python 留给你的“协议接口”——只要你把对应的方法实现出来你的类就能像内建类型一样参与语法层面的运算。len(obj)能不能用、obj[0]能不能取、for x in obj能不能迭代、obj other怎么比较、with obj能不能进全部由这些方法决定。这篇文章不打算按照官方文档把几十个方法挨个念一遍而是想从“我实际写业务代码时怎么用”的角度把这些方法归类拆开讲清楚每个方法背后的设计意图、常见坑位、以及什么时候真的需要自己实现。内容适合已经掌握了类、继承、装饰器这些基础、但还不太确定“魔法方法到底怎么落地”的读者也适合回头想补一遍进阶的开发者。读完之后你至少能回答一个问题想让自己的类表现得像 list、dict、int 或者 context manager到底该实现哪几个方法、注意哪些边界条件。1. 魔法方法到底是什么——先弄清楚设计意图1.1 魔法方法在 Python 语言中的定位很多教程把魔法方法解释成“允许自定义类加入 Python 语法生态的特殊方法”这句话方向是对的但不够具体。我自己理解它更愿意把它看成一套协议Python 解释器在遇到特定语法时会去对象上查找对应名字的方法找到了就调用找不到就走默认逻辑或者报错。举个例子你写obj other解释器不会直接说“这两个对象不能相加”而是先去obj的类型里找__add__没有就去other的类型里找__radd__二者都没有才抛TypeError: unsupported operand type(s)。len(obj)会触发__len__obj[key]会触发__getitem__obj()会触发__call__。所以从另一个角度看魔法方法就是 Python 语法到对象行为的映射表。这张映射表设计得很聪明因为它让语法层保持相对稳定让具体实现开放给了用户类。你不需要改变语言本身只需要在类里实现一个方法就能让自定义对象融入语言既有的表达方式。这也是 Python“鸭子类型”哲学的延伸——不要求你的类继承自某个特定基类只要你实现了该有的方法语法就能生效。1.2 什么时候该自定义魔法方法什么时候不该一个很容易被忽略的问题不是所有类都需要魔法方法。很多业务对象的类规规矩矩地写完__init__就够了。觉得“魔法方法越多越厉害”是新手阶段常见的心态但实际项目里更重要的是知道哪些场景才值得写。我自己判断的标准主要有三条。第一对象需要参与语法层面的操作比如放进一个容器里做相等性判断、排序、拼接或者需要支持in判断这时候不实现对应的魔法方法代码写起来就会很别扭。第二对象有明确的“自然行为”比如一个学生类用str(student)打印出姓名和学号是合理的用len(student)返回选课数量也可以接受这些行为如果跟常规直觉一致实现魔法方法是加分项。第三需要控制对象的生存周期或者资源释放比如连接池、文件句柄、临时环境变量这类场景实现上下文管理器协议能让代码大幅简化。反过来说如果一个类只是单纯的数据容器未来可能还要改内部存储结构那就不适合把所有魔法方法都堆上去。过度实现会让类的接口变“胖”后续维护成本跟着上升。而且魔法方法在查找时会绕开实例字典直接走类型一旦实现的逻辑有副作用排查起来往往比普通方法更难。2. 最常用的魔法方法让类像内建对象一样工作2.1 对象创建与销毁__init__、__new__、__del__这一组是大多数人最早接触的魔法方法但里面隐藏的细节远不止“写构造函数”这么简单。__init__负责在实例创建之后做初始化动作它的第一个参数是self也就是已经构造好的实例对象。注意__init__不负责“创建”对象真正创建对象的是__new__。__new__是类方法但不需要显式加classmethod装饰器它在实例真正生成之前被调用返回值决定__init__有没有机会执行。如果你在__new__里返回了一个不属于目标类型的对象Python 会直接跳过__init__。这里有一个实用场景实现单例模式时很多人喜欢改写__new__在创建前判断实例是否已经存在存在就直接返回旧实例。这种写法比在__init__里搞状态判断更干净因为__init__在单例复用的情况下会被重复调用容易把已有数据重置掉。不过我的建议是单例尽量用模块级变量去管理真要类做单例再考虑__new__否则调试的时候“构造函数明明执行了但对象不是新的”这个现象很容易让人绕进去。__del__这个方法的坑最多。它不是在对象引用计数归零的瞬间保证执行而是在 GC 回收对象时触发并且不保证一定会被调用。程序的异常退出、解释器关闭时仍然存活的全局对象都可能不触发__del__。所以不要指望它来做关键资源释放。需要用with或try/finally保证释放的资源文件、锁、数据库连接一律走上下文管理器协议而不是__del__。2.2 字符串与显示__str__、__repr__、__format__一个非常经典的问题__str__和__repr__到底有什么区别官方解释是__repr__面向开发者目标是无歧义__str__面向用户目标是可读。但落到代码里很多人还是分不清该实现哪个。从调用时机来说print(obj)优先找__str__找不到就退回__repr__直接查看变量比如 REPL 里输入变量名回车显示的是__repr__使用 f-stringf{obj}在 Python 3 中优先找__str__但f{obj!r}会强制走__repr__。还有一个容易忘的str(obj)如果两个都没实现默认输出的是__main__.Foo object at 0x7f...完全没有信息量对调试很不友好。我的习惯是任何自定义类都先实现__repr__因为它是最低限度的调试工具。输出格式尽量做到ClassName(keyvalue)这种“能看出类型、关键状态、核心参数”的样子。比如一个表示商品的类__repr__返回Product(skuA1001, price35.9)调试时一眼就能看清对象是什么、关键属性是什么。如果这个类还要展示给最终用户再补充实现__str__返回好看的展示文本。__format__用得相对少但当你需要支持f{obj:.2f}这类格式说明符时就要自己处理格式串了这个按需实现即可不常写。2.3 比较与哈希__eq__、__hash__、__lt__的连带关系先给一个大多数入门者不知道的结论如果你在类里定义了__eq__却没有同时定义__hash__这个类的实例会变成不可哈希的。因为 Python 有一条默认规则两个对象相等的话哈希值也应该相等。__eq__一旦被重载默认的__hash__会被一并禁用防止你出现“a b 成立但 hash(a) ! hash(b)”这种违反字典和集合不变量的事。所以如果你想让对象同时支持相等比较和放进 dict/set必须成对实现这两个方法。实现时记住一条黄金法则求哈希使用的字段必须和相等比较使用的字段保持一致。比如__eq__比较id和name那__hash__就应该hash((self.id, self.name))。如果你在__eq__里比较了很多字段但__hash__只取了id那id相同但其他字段不同的对象会被塞进同一个哈希桶然后因为__eq__返回 False 而共存。功能上倒不会错但散列效果会很差性能崩得莫名其妙。还有一个更隐蔽的坑可变对象不要参与哈希。如果对象的__hash__依赖的字段在放入 dict 之后被修改了你再根据原 key 去查找时哈希值已经变了元素就找不到。这就是为什么 list、dict、set 自身不可哈希因为它们是可变容器。如果你设计的对象是可变的比如有 setter 方法就不要提供__hash__或者在文档里明确告诉用户“放进 dict 后不要修改关键字段”。关于排序__lt__是优先级比较高的一个方法。Python 3 里已经没有__cmp__了排序时只靠操作符。你写sorted(lst)如果列表里的对象是自定义类内部会用来比较。只实现__lt__而不实现__gt__、__le__、__ge__也能让sorted正常工作因为排序算法主要依赖。但如果你调用a b那还是需要__gt__的。这里可以偷个懒用functools.total_ordering装饰器只需要实现__eq__和其中一个比较方法比如__lt__装饰器会自动补出其他几个比较方法。实测下来这个装饰器很方便但有轻微性能损耗如果排序是热点路径并且对象量极大建议还是手动把几个方法写全。2.4 数值运算系列__add__、__radd__、__iadd__的数据流数值运算可能不是业务代码里最常见的魔法方法但在写一些自定义数值类型、向量类、金额类、矩阵类的时候很有用。这里最关键的其实是理解“左操作数优先、右操作数兜底”的调度规则。a b执行时会先在a的类型里找__add__如果a没有实现或者返回了NotImplemented再去b的类型里找__radd__。很多人第一次看到NotImplemented会以为它是NotImplementedError的省略写法其实是完全不同的两样东西NotImplementedError是异常抛出去表示“方法未实现”NotImplemented是单例值返回它表示“我不会处理这个操作请你试试对方的反向方法”。举个例子一个表示金额的类class Money: def __init__(self, amount): self.amount amount def __add__(self, other): if isinstance(other, Money): return Money(self.amount other.amount) return NotImplemented def __radd__(self, other): if isinstance(other, (int, float)): return Money(self.amount other) return NotImplemented这样写money 100和100 money都能工作。前一个走Money.__add__处理int后一个先尝试int.__add__但int不会处理Money于是退回Money.__radd__。这里有个常见遗漏很多人写了__add__却忘了__radd__结果100 money直接抛TypeError排查半天不知道问题出在哪。__iadd__对应的是运算。要特别注意__iadd__返回的值会被重新赋值给左边的变量。对于可变对象可以在原对象上做修改后return self对于不可变对象可以直接返回一个新对象效果等同于a a b。如果你没有实现__iadd__Python 会退回去做a a b也就是调用__add__。所以这里有一个性能选择如果对象是可变的、并且原地修改更高效就应该实现__iadd__避免无谓的新对象创建。典型例子是list和set的行为它们都是原地修改但tuple没有__iadd__执行t (1, 2)其实是生成一个新 tuple。3. 序列与容器的魔法方法让你的类支持索引和迭代3.1 索引与切片__getitem__、__setitem__、__delitem__如果深入理解 Python 的容器协议你会发现它其实很宽松你只需要实现__getitem__这个对象就可以被索引、切片、迭代甚至用in判断。但接口宽松不等于实现简单这中间有不少细节。写__getitem__时obj[0]和obj[0:3]传入的第二参数类型是不同的前者是 int后者是 slice 对象。如果你想正确处理切片需要自己解析slice.indices(length)来得到真正的起始、结束、步长。一个很容易踩坑的场景是你内部存的是一个大列表想直接透传索引逻辑class MyCollection: def __init__(self, items): self._items items def __getitem__(self, index): return self._items[index]上面的代码看起来没毛病但它把切片行为完全委托给了内部列表。如果内部数据结构换成了字典或者自定义结构index可能是任何类型。更稳妥的做法是显式处理 int 和 slice 两种分支。另外__getitem__在索引越界时应该抛IndexError这既符合惯例也是让for ... in obj停止迭代的必要条件。对你没看错一个只实现了__getitem__的类是可以直接放进for循环里迭代的。迭代器协议会先找__iter__找不到就退回__getitem__协议从 0 开始逐个递增索引调用遇到IndexError就停止。这个兼容行为在 Python 2 时代是迭代器的默认机制3.x 里虽然不推荐依赖它但它仍然有效。__setitem__对应obj[key] value__delitem__对应del obj[key]。实现它们时注意边界处理和类型校验。很多人在__setitem__里不做类型判断让任意类型的数据混入容器后面排序、计算时才发现问题那就要回头改很多地方。3.2 迭代器协议__iter__、__next__、__len__、__contains__的组合用法实现__iter__方法时最常见的方式有两种第一种是返回self并在类里同时实现__next__让对象自身成为自己的迭代器第二种是返回一个生成器对象利用yield语法惰性生成数据。两者各有适用场景。如果你要表示的是“可迭代对象”而不是“迭代器”更推荐用生成器方式。比如class Week: def __iter__(self): for day in [Mon, Tue, Wed, Thu, Fri, Sat, Sun]: yield day这个类可以反复迭代每次for循环都会新建一个生成器状态是独立的。而如果让对象自己当迭代器同一时刻只有一个迭代位置第一轮循环跑完之后再跑第二轮就不会再有数据了。当你要迭代的对象本身没有“当前位置”这个概念时用生成器是更安全的选择。__len__除了配合len(obj)调用之外还会影响bool(obj)的默认判断逻辑。如果一个类没有实现__bool__Python 会尝试调用__len__长度为零返回 False。所以很多容器类只实现__len__就能获得“空对象是假值”的行为。同理如果你希望自己的对象能直接用if obj:判断真假可以先想想这个“真”到底是什么含义——是长度非零还是某个自定义标志位。想要自定义判断逻辑就需要实现__bool__它的返回值会被自动转成布尔值。__contains__对应in运算符。如果你在类里实现了它x in obj就会走你的方法如果没有实现Python 会退化成迭代对象并逐个比较。对于包含大量数据、或者有高效查找方式的容器比如内部维护了一个 set实现__contains__能大幅提升in判断的性能。不要小看这个方法它属于典型的“不实现也能跑但实现了能救性能”的类型。3.3 让实例像函数一样调用__call__的适用场景__call__可能是所有魔法方法里最容易被忽略但最实用的一个。实现它之后类的实例可以用obj(...)这种语法调用。这个特性在几个场景下特别有用。一个非常典型的使用场景是有状态的函数替身。普通函数是无状态的但通过函数属性或者闭包可以携带状态写起来却不太方便。而用带__call__的类状态就是实例属性初始化、重置、查询都一目了然。比如一个累计统计器class Counter: def __init__(self): self.total 0 def __call__(self, value): self.total value return self.total这个类不仅可以用c Counter(); c(5)调用还能随时查看c.total重置时c.total 0比用闭包加nonlocal的方式更容易理解。另一个场景是装饰器工厂很多框架的装饰器本身就是带__call__的类这样可以让装饰器同时携带参数和状态。还有一点值得注意实现了__call__的对象callable(obj)会返回 True。这意味着你可以把它作为回调函数传给别的库比如排序的key、事件绑定、命令注册等。如果你的对象需要保存一些配置信息并在触发时执行相应动作用__call__设计比写一个普通方法要自然得多。4. 上下文管理器与属性管理的魔法方法4.1 上下文管理器协议__enter__、__exit__的完整解析with语句背后的机制是上下文管理器协议进入with块时自动调用__enter__退出时无论是否抛异常都会调用__exit__。这组魔法方法在实际工程里非常重要涉及文件、锁、连接、临时环境变量等场景时它是保证资源正确释放的最可靠方式。实现__enter__时返回值会成为as后面的变量。比如class ManagedResource: def __enter__(self): print(acquire resource) return self def __exit__(self, exc_type, exc_val, exc_tb): print(release resource) return False__exit__接收四个参数异常类型、异常实例、traceback 对象第三个参数在处理某些需要查看调用栈的场景里很有用。如果with块内没有发生异常这三个参数都是 None。__exit__的返回值决定异常是否被“吞掉”返回 True 表示已经处理了异常外部不会再收到异常返回 False 或 None 表示异常会继续向外传播。这是一个很微妙的点一般业务代码建议返回 False不要让异常被静默吞掉。一个非常实用的小技巧是在__exit__里做资源清理和异常记录然后返回 False 让异常继续传播。这样资源释放和错误处理被整齐地分开调用方仍然能看到原始异常同时你也拿到了执行 after 阶段的机会。另外提醒一句contextlib.contextmanager可以用生成器的方式快速创建上下文管理器写起来更简洁。如果你只需要一个函数级别的上下文管理而不是一个完整的可复用类用它会更顺手。但如果你需要维护复杂的内部状态、支持嵌套、或者需要继承复用那自己实现__enter__和__exit__还是更合适。4.2 属性访问控制__getattr__、__setattr__、__getattribute__的区别属性访问相关的魔法方法很容易弄混核心在于理解它们各自的触发时机和查找顺序。__getattr__只在正常属性查找失败时被调用。也就是说访问一个并不存在的属性并且实例字典、类字典、父类链上都没有找到这时才会触发__getattr__。利用这个特性可以做“惰性属性”“动态代理”“伪属性”等功能。比如一个从字典初始化的类class AttrDict: def __init__(self, data): self._data data def __getattr__(self, name): if name in self._data: return self._data[name] raise AttributeError(name)这样一来obj.name就能自动映射到self._data[name]上。注意__getattr__里如果什么属性都返回默认值会导致hasattr(obj, xxx)永远为 True排查 bug 时会非常迷惑。所以不存在的属性应该主动抛出AttributeError保持默认语义。__getattribute__则不同它是所有属性访问的入口每次访问属性都会先经过它。这意味着在这个方法里访问self.xxx会再次触发__getattribute__形成无限递归。正确的写法是使用object.__getattribute__(self, name)来访问真正的属性。这个方法的杀伤力比较大如果不是在写框架或者做代理层我建议尽量别动它。__setattr__在所有属性赋值时被调用同样存在递归风险。在__setattr__里给实例设定属性不要直接写self.xxx value而是用object.__setattr__(self, xxx, value)。通常需要覆盖__setattr__的场景包括属性值校验、设置后自动触发副作用比如设置某个字段后更新缓存、以及阻止某些属性被外部修改。还有__delattr__对应del obj.attr如果要禁止删除某些属性可以在这里做限制。4.3__slots__不只是节约内存严格来说__slots__不算是带双下划线的方法而是一个类属性但它跟属性访问机制息息相关而且在性能优化里很常见所以放在这里一起说。默认情况下Python 的类实例用字典存储属性也就是__dict__。字典灵活但内存占用偏高。在需要创建大量对象的热点场景比如解析大文件生成百万行对象、批量计算实体__slots__可以发挥明显作用。定义一个类class Point: __slots__ (x, y) def __init__(self, x, y): self.x x self.y y这样每个实例不再维护__dict__只保留固定属性的存储空间内存占用可以下降不少。不过天下没有免费的午餐用了__slots__之后实例不再能随意添加新属性。如果你想保留灵活性可以显式地在__slots__中加入__dict__但那等于又退回了字典存储模式内存收益就打折了。还有一点常被忽视继承时子类如果不定义__slots__还是会拥有__dict__。所以父类用__slots__节约下来的空间被子类一把抢了回去。子类想要继续享受这个优化需要在自己的定义里也写上__slots__。我在实际项目里见过不少这种“父类设了 slots子类没设结果内存跟没优化一样”的情况排查时很难想到是这里的问题。5. 更多进阶魔法方法知道它们能让代码更地道5.1__bool__与__copy__、__deepcopy__的边界行为__bool__用于自定义对象的真值判断。默认情况下所有实例都是 True但如果类实现了__len__长度为 0 时会返回 False。所以一个很隐蔽的坑是你的类定义了__len__并且len()的语义是“容器里的元素个数”那么if obj:就会意外地变成“非空才为真”。如果你想让“对象存在”即为真不管容器是否为空就需要显式实现__bool__返回 True。copy.copy和copy.deepcopy默认行为其实挺智能的一般不需要专门实现。但有一种情况对象持有锁、文件句柄、连接池等不可复制资源时默认复制会带来隐患。比如一个持有线程锁的对象被复制后新对象和旧对象可能指向同一个锁对象导致锁的语义被破坏。在这种情况下你需要实现__copy__和__deepcopy__明确控制复制时哪些资源要被重新创建、哪些可以被共享。这组方法属于“平时用不到用到时能救命”的类型。5.2 运算符映射的其他细节反向运算与就地运算的优先级前面讲过__add__、__radd__、__iadd__这一组。实际上整个运算符家族都存在类似的三件套__sub__和__rsub__、__mul__和__rmul__、__truediv__和__rtruediv__等。反向运算的触发规则是一致的左操作数不会处理该操作时右侧类型的反向方法才有机会执行。这里有一个值得注意的优先级细节NotImplemented是值不是异常但很多人的代码里写return NotImplemented后会习惯性地担心“是不是抛异常了”。实际上它只是告诉解释器“这个方法不处理这个类型”解释器继续尝试其他方案。如果所有方案都返回NotImplemented最终才抛出TypeError: unsupported operand type(s)。所以你在实现反向运算时一定要返回NotImplemented而不是抛出它这样 Python 才能尝试下一个路径。有一个例子可以验证对反向运算的理解money * 2和2 * money。前者走Money.__mul__后者会先从int.__mul__尝试int明显不认识Money类型于是 go toMoney.__rmul__。如果你只实现了__mul__而没有__rmul__2 * money一定会报错。很多人在写数值运算类时只做了一半导致只能用“对象在左边”的方式限制很大。5.3__getattribute__和__setattr__之外__dict__与__class__的关系不少初学者分不清obj.__dict__、type(obj).__dict__、obj.__class__这几个东西。obj.__dict__是实例自己的属性字典绝大多数实例属性都存在这里面type(obj).__dict__是类对象自己的属性字典存放类方法和类变量obj.__class__返回对象的类它是建立在类型系统之上的一个元属性。实现属性控制时经常要跟这几位打交道。一个常见误解是访问obj.attr时Python 会先找实例__dict__再找类__dict__最后沿着 MRO 找父类。这个流程在普通未重载__getattribute__的类上是成立的。但如果你重载了__getattribute__这个“先找实例__dict__”的步骤就变成了由你的代码自己控制。比如你可以先检查类上有没有某个特殊标记再决定属性查找怎么走。这种用法适合做“智能属性分发”的场景但性能开销和递归风险都不小建议只在写框架时用。6. 常见问题与排查技巧实录6.1 为什么两个“看起来一样”的对象不相等这是我在排查他人代码时非常常见的问题两个对象字段一样用比较却返回 False。原因很简单因为默认的__eq__就是“比较是否是同一个对象”也就是is的身份比较。要让两个内容相同的对象相等必须显式实现__eq__。很多人以为 Python 会像值类型那样自动比较字段实际上 Python 没有这个默认行为。实现__eq__时还要注意两点一是先判断另一个对象是否为NotImplemented状况灵活处理不同类型的比较二是不要忘了同时处理__hash__。而且实现__eq__后最好把对象设计成“关键字段不可变”避免出现前面讲过的哈希污染问题。6.2__repr__和__str__到底实现哪个我的建议是先实现__repr__再按需实现__str__。因为__repr__是调试时最直接的信息来源并且print(obj)、f-string、日志输出在找不到__str__时都会退回__repr__。很多实际方案里两个方法返回的内容可以相同也可以__str__返回更友好、更短的展示文案。如果你在 f-string 里想强制显示__repr__的结果用f{obj!r}即可。在调试日志、异常信息里我会倾向于让__repr__输出能反映对象核心字段的内容这样一条日志就能定位对象状态。这个习惯在排查线上问题时能节省大量时间。6.3 其他高频问题速查问题原因解决方式TypeError: object is not subscriptable类没有实现__getitem__根据实际语义实现__getitem__或改用.get()等普通方法TypeError: XXX object is not iterable类没有实现__iter__或者__getitem__实现__iter__返回迭代器/生成器TypeError: object does not support item assignment类没有实现__setitem__实现__setitem__或在类内部转成可变容器再赋值XXX object is not callable类没有实现__call__确认是否需要可调用语义需要则实现__call__unhashable type: XXX定义了__eq__但没定义__hash__同时实现__hash__或者用不可变字段做哈希TypeError: unsupported operand type(s) for 缺少__add__/__radd__补实现对应运算方法返回NotImplemented处理不支持的类型定义__slots__后无法添加新属性__slots__限制了实例属性集合恢复__dict__或者把需要添加的属性提前写入__slots__len(obj)结果不对__len__返回值必须是整数且不小于 0检查返回值类型必要时转成 int除了表格里的这些还有一个实操时的独家建议在实现多个魔法方法后可以做一个“协议自检”小实验。比如写一个快速的测试脚本分别测试索引、切片、迭代、比较、布尔值、in判断、with进出、callable把行为打印出来。这样能一次性暴露出大多数魔法方法之间的联动问题。很多隐藏 bug 其实是“实现了单个方法但方法之间互相冲突”导致的单独看每个方法都对组合起来就会出问题。这轮讲下来最深的感受是魔法方法并不是什么高深莫测的黑魔法它就是 Python 对“对象行为协议”的一种约定。搞清楚它们本质上是在理解 Python 解释器怎么看待你的类。平时写业务代码时不需要把所有方法都背下来但至少应该知道这几件事对象怎么被创建和销毁、怎么显示、怎么比较、怎么支持容器操作、怎么管理属性、怎么配合with和运算符。每个方向记住几个关键方法用的时候查一下签名和注意事项就够了。最后说一个小技巧也是我常用的习惯给自定义类写完魔法方法后顺手写一个对应的 dunder 方法清单标注哪些是必须同时成对出现、哪些会影响其他行为。这样过几个月回来看代码不用重新推一遍也能快速想起当时的设计意图。Python 的设计哲学是“让显式优于隐式”魔法方法恰恰是在隐式语法和显式实现之间搭了一座桥。掌握好这座桥写出来的代码会更自然也更接近这门语言本来的样子。
