Python魔法方法完全指南：从__init__到__getitem__的对象行为协议

我第一次被魔法方法搞蒙，是在一个老项目的调度器代码里。for task in tasks 能正常遍历，可这个 Task 类既没有继承 list，也没有实现明显的 iter 或 next 方法。我翻到类底部才看见几行 __getitem__、__len__、__eq__、__repr__……这些双下划线方法几乎在每个类里都会出现，但很多 Python 初学者只认识一个 __init__，其他的能避开就避开。

后来我把这套机制彻底想通了：魔法方法不是“魔法”，而是 Python 给对象预设的一套“行为协议”。类通过实现某个双下划线方法，声明自己支持某种语言能力；解释器在遇到 len(obj)、obj[key]、obj + other、with obj 这些语法时，会隐式去调用对应的协议方法。这篇文章我想把这些 Magic Methods 按使用场景拆开讲清楚，包括对象生命周期、容器协议、运算比较、属性访问、上下文管理和迭代器，以及我在实际项目里踩过的一些坑。适合刚学完 Python 基础语法、想读框架源码，或者正想把业务类写得自然一些的读者。

1. 魔法方法不是玄学，是 Python 对“对象行为”作出的协议约定

1.1 把魔法方法理解为“语言级别的接口”

先明确一个关键概念：在 Python 里，很多内置函数、运算符和语法结构，本质上都是“协议”。类实现了对应的方法，就等于接入了这套协议，然后语言就会用统一的方式对待它。

比如你写 len(obj)，Python 并不会像查表一样去猜测你这个对象有多少个元素，而是去调用 type(obj).__len__(obj)。你写 obj[0]，解释器会转成调用 type(obj).__getitem__(obj, 0)。你写 a == b，Python 会先去尝试 type(a).__eq__(a, b)，如果返回 NotImplemented 再尝试反向操作。

一个最简单的例子：

python复制class Bookshelf:
    def __init__(self, books):
        self.books = books

    def __len__(self):
        return len(self.books)

shelf = Bookshelf(["《流畅的Python》", "《Python Cookbook》"])
print(len(shelf))      # 2

这里其实没有任何“魔法”。Bookshelf 定义了 __len__，于是它就拥有了“可被 len() 计算长度”的能力。如果你不定义这个方法，len(shelf) 会直接抛 TypeError: object of type 'Bookshelf' has no len()。

用生活里的例子类比：魔法方法有点像电器插头。Python 语言定义好了“插座标准”，你的类实现对应的方法就是在安装某种规格的插头。只要插头一致，for 循环、with 语句、加减乘除这些“通用电器”就能直接使用你的对象，不需要知道它内部具体怎么实现。

这对代码设计的影响是巨大的。你不需要让你的类继承某个固定的“容器基类”才能支持遍历；只要实现了 __iter__ 或 __getitem__，它就会被上下文环境自动识别为可迭代对象。同样的道理，一个类只要实现 __enter__ 和 __exit__，即使它跟文件、数据库连接没有任何继承关系，也能被 with 语句管理。

1.2 常见的内置语法与魔法方法映射

为了方便查阅，我把日常开发中最常见的一组语法/内置函数与对应魔法方法先整理成一张表。后面几章再逐个展开细说。

初看这张表会觉得方法很多，但实际使用时你完全不需要一次记住所有。更重要的是理解一种思考方式：当你在纠结“我要给这个对象增加什么能力”时，先问一句：“这个能力是否对应 Python 已有的某个语法/内置函数？”如果对应，那大概率就应该考虑实现对应的魔法方法，而不是发明一个独门的方法名。

2. 生命周期与展示：为什么我在 __init__ 里做初始化，还要知道 __new__

2.1 __new__ 和 __init__ 的分工

绝大多数 Python 初学者最早接触的魔法方法就是 __init__。大家习惯叫它“构造函数”，甚至在很多教程里也叫它构造函数。严格来说，这个叫法不准确。真正的实例创建发生在 __new__ 里，__init__ 只是实例创建完成后的初始化方法。

可以这样理解：__new__ 负责“把一块地批下来”，然后返回一个实例；__init__ 负责“在批下来的这块地上装修房子”。实例化一个类时，Python 先调用 __new__(cls, *args, **kwargs) 拿到实例，再调用 __init__(self, *args, **kwargs) 完成初始化。

你大部分时候不需要自己写 __new__，因为 object.__new__ 已经够用。但有几个特殊场景必须理解它。最典型的是单例模式：

python复制class Singleton:
    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self):
        print("__init__ 仍然会被调用")

在这个实现里，无论你创建多少次 Singleton()，拿到的都是同一个实例，因为 __new__ 永远只创建一次对象，后续直接返回已有实例。但要注意：每次调用 Singleton() 时，Python 依然会继续调用 __init__ 重新初始化。这对单例来说往往不是想要的行为，所以真正的单例实现通常还会在 __init__ 里加“只初始化一次”的判断，或者通过元类控制。这个例子倒不是说单例一定这么写，而是提醒你看到 __new__ 时要能反应过来它承担的是“创建”职责。

另一个常见场景是不可变类型。如果一个对象创建之后就不能修改，那么所有属性都应该在 __new__ 阶段确定，而 __init__ 对它的约束就很弱。例如 tuple 的子类自定义逻辑时，就需要在 __new__ 里提前处理。

但这并不是说 __init__ 不重要。作为日常使用的 99% 场景，我们仍在 __init__ 里保存状态：给 self 绑定业务所需的属性。如果你在 __init__ 里发现某些校验逻辑必须在实例创建前完成，比如参数非法时甚至不希望创建对象，也可以在 __new__ 里抢先抛异常。

2.2 给对象做调试展示：优先实现 __repr__

调试代码时最影响效率的一件事是什么？打印一个对象，结果看到 <__main__.Point object at 0x7f9d0a1b3d30>。这个信息除了内存地址什么都说明不了。

如果你希望日志里直接看到对象的关键业务信息，就需要实现 __repr__。它面向开发者，目标是输出“无歧义、可重建”的字符串。比如：

python复制class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __repr__(self):
        return f"Point(x={self.x!r}, y={self.y!r})"

p = Point(3, 5)
print(repr(p))          # Point(x=3, y=5)
print(p)                # 如果没有定义 __str__，很多场景会退化使用 __repr__ 的结果

注意，repr(p) 的输出必须优先保证开发时能看懂，而不是给终端用户读。比如说一个 Order 对象，__repr__ 最好显示订单号和状态；而 __str__ 可以输出更适合展示的一句话，比如“订单 #1024 已支付”。

常见的表现差异还有容器。列表里的元素输出时，Python 会调用元素的 __repr__，而不是 __str__。这意味着如果你只实现 __str__，打印列表时依然看到一堆 <Point object at ...>；如果你只实现 __repr__，则 print(obj) 在很多情况下会自动使用 __repr__ 的结果。所以我个人经验是：如果时间只够写一个，优先实现 __repr__。它兼顾了控制台调试、列表打印、异常信息展示等多个场景。

2.3 别把清理逻辑压在 __del__ 上

__del__ 经常被类比成 C++ 的析构函数，但这门语言里它非常不可靠。对象引用计数归零时它会被调用，但如果存在循环引用且垃圾回收没有及时触发，或者解释器正在退出，__del__ 的调用时机可能远晚于你的预期，甚至不一定会被调用。

更麻烦的是，如果 __del__ 里访问了某个已经被回收的全局资源，还可能抛出异常。这不是你在关键业务里能依赖的机制。文件句柄、数据库连接、锁这类资源，正确的释放方式是上下文管理器：

python复制class ManagedConnection:
    def __enter__(self):
        self.conn = self._open()
        return self.conn

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.conn.close()
        return False

因为 with 语句的执行路径是确定的：块结束、异常抛出、提前 return，最终都会由解释器保证调用 __exit__。相比之下，__del__ 更像是“最后兜底”的机制，日常不应该把核心清理流程寄托在它身上。

3. 让自定义对象“像容器一样”：__getitem__、__iter__、__len__ 的配合

3.1 最简迭代协议：只有 __getitem__，也能被 for 遍历

Python 对可迭代对象的判定有一层向后兼容的“旧式协议”：一个类只要实现了 __getitem__，并且索引从 0 开始连续取值，直到抛出 IndexError，它也能被 for 循环遍历。

当初我看到这个行为时很惊讶。这意味着你不需要实现 __iter__，只要实现下标访问，就能让对象变成一个可迭代序列。看下面这个例子：

python复制class Countdown:
    def __getitem__(self, index):
        if index >= 5:
            raise IndexError("越界")
        return 5 - index

for num in Countdown():
    print(num)  # 5 4 3 2 1

for 循环做的事情相当于：从 index=0 开始调 Countdown()[0]，拿到 5；再调 Countdown()[1]，拿到 4……直到某次调用抛出 IndexError，循环终止。

这个机制非常有 Python 味道。它大大降低了实现一个“可遍历对象”的门槛。不过在日常业务中，如果你希望迭代语义更明确，还是应该实现 __iter__。两套协议并存时，__iter__ 拥有更高优先级。而且 __iter__ 能表达的迭代逻辑更丰富，比如遍历过程中需要传状态、需要边算边丢等。

3.2 支持索引、切片与包含判断的完整容器

只实现最简版 __getitem__ 只能让对象被“顺序访问”，但如果你想让它更像一个真正的序列，就需要处理整数下标、切片、边界条件等。

以一个播放列表为例：

python复制class Playlist:
    def __init__(self, songs):
        self._songs = list(songs)

    def __len__(self):
        return len(self._songs)

    def __getitem__(self, key):
        if isinstance(key, slice):
            return [self._songs[i] for i in range(*key.indices(len(self._songs)))]
        return self._songs[key]

    def __contains__(self, song):
        return song in self._songs

    def __iter__(self):
        return iter(self._songs)

playlist = Playlist(["Song A", "Song B", "Song C"])
print(len(playlist))                    # 3
print(playlist[0])                      # Song A
print(playlist[1:])                     # ['Song B', 'Song C']
print("Song B" in playlist)             # True

这里有几个细节值得展开：

第一，playlist[1:] 触发的 key 是一个 slice 对象，不是整数。所以 __getitem__ 里要做 isinstance(key, slice) 判断。调用 key.indices(len(self._songs)) 可以拿到一个适合传入 range() 的 (start, stop, step) 三元组，这比手工处理边界条件可靠得多。

第二，__contains__ 不是必须实现的。即使没有它，"Song B" in playlist 也能工作，只是 Python 会退化为“遍历整个对象逐个比较”，时间复杂度是 O(n)。当判断逻辑本身有更快的捷径时，实现 __contains__ 能带来明显的收益。比如一个用户列表，如果你只想判断邮箱是否已注册，直接对内部字典或索引集合做查找，比遍历每个用户对象再比对邮箱快得多。

第三，__iter__ 返回 iter(self._songs)，这是最简便的做法。它明确告诉解释器：我的对象可以迭代。更复杂的场景可以返回生成器对象，比如“只返回未播放的歌曲”。

3.3 为什么实现 __len__ 会影响 bool(obj) 的结果

看到这里你可能已经注意到，容器协议里 __len__ 还会产生一个“副作用”：当一个对象定义了 __len__ 但没有定义 __bool__ 时，bool(obj) 会通过 len(obj) == 0 来判断真值。

这意味着一个空列表是 False，非空是 True。你的自定义容器也会自动获得这套行为。比如：

python复制class TaskQueue:
    def __init__(self):
        self._tasks = []

    def __len__(self):
        return len(self._tasks)

queue = TaskQueue()
if not queue:
    print("队列为空")

对很多业务类来说，这是完全合理的行为：队列没有任务时，当作 False 处理。但要注意，如果你的类同时有“列表长度”和“业务状态开关”两种语义，混在一起就可能产生困惑。比如一个订单对象，__len__ 表示订单包含的商品数量，但你希望空订单对象本身未必是 False。这时就应该额外实现 __bool__，明确业务上的真值判断逻辑。

容器协议的设计理念是：让类在行为上贴近内置容器，从而使调用方写出更自然的代码。调用方不关心你的类内部是用 list 还是 dict 还是别的结构存储，它只关心“这个对象能不能被 len、下标、in、for 使用”。

4. 计算与比较：把业务对象变成可加减、可比较的“一等公民”

4.1 算数协议为什么需要“正向”和“反向”两个方法

当你想让一个自定义对象支持 +、-、* 时，Python 不是直接在语法层面做运算，而是查找对象实现的操作方法。以加法为例，a + b 会先调用 a.__add__(b)。如果 a 的类型实现了这个方法，就正常计算结果；如果没有实现，或者方法返回了 NotImplemented，Python 再尝试调用 b.__radd__(a)。

这个“反向方法”经常被忽略。举一个金额场景：

python复制class Price:
    def __init__(self, cents):
        self.cents = cents

    def __repr__(self):
        return f"Price({self.cents} cents)"

    def __add__(self, other):
        if isinstance(other, Price):
            return Price(self.cents + other.cents)
        if isinstance(other, int):
            return Price(self.cents + other)
        return NotImplemented

    def __radd__(self, other):
        return self.__add__(other)

price = Price(100)
print(price + 50)      # Price(150 cents)
print(50 + price)      # Price(150 cents)，走的是 __radd__

注意 50 + price 这一步很重要。整数类型 int 根本不知道如何跟 Price 相加，它尝试后返回 NotImplemented，Python 才会去调用右侧 Price.__radd__。如果我们的类没有实现 __radd__，这个操作会直接抛出类型错误。

类似的，sum([price1, price2, price3]) 在实现 __radd__ 之前也可能出问题，因为 sum 会从 0 开始累加，第一轮就会执行 0 + price1，触发反向加法。所以当你需要自定义对象参与内置聚合函数时，双向协议尤其重要。

反向方法里还有一个容易被忽略的点：当类型不能处理时，应该返回 NotImplemented，而不是直接抛异常。这样做可以让 Python 有机会尝试另一个操作数的方法，也符合“我不支持，让右边的对象自己试试”的语义。直接抛 TypeError 会打断 Python 的双向尝试机制。

4.2 用 @total_ordering 减少比较方法样板

比较运算有六个：==、!=、<、<=、>、>=。如果每个都手动实现，代码会很冗长，而且很容易写错方向。functools.total_ordering 这个装饰器就是用来解决这个问题的：只要在类中实现 __eq__ 和另外一个偏序方法（例如 __lt__），装饰器会自动帮你补全其余比较方法。

考虑一个按面积比较图形的场景：

python复制from functools import total_ordering

@total_ordering
class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height

    def area(self):
        return self.width * self.height

    def __eq__(self, other):
        if not isinstance(other, Rectangle):
            return NotImplemented
        return self.area() == other.area()

    def __lt__(self, other):
        if not isinstance(other, Rectangle):
            return NotImplemented
        return self.area() < other.area()

r1 = Rectangle(3, 4)
r2 = Rectangle(2, 6)
print(r1 >= r2)   # True，由 total_ordering 补全

这个机制的便利性很强，只要补齐 __eq__ 和 __lt__，sort()、max()、min() 都能对自定义对象直接使用。不过我也提一句代价：total_ordering 自动生成的方法是经过“尝试多个方法”的逻辑包装的，比手写精确方法慢一点。对绝大多数业务场景这个开销可以忽略，但在大列表排序、高频比较时，性能敏感的话可以手写完整方法。

4.3 重写 __eq__ 后必须处理的 __hash__ 问题

这一节是我认为最容易踩、最值得单独讲的坑。Python 有一个默认约定：如果类定义了 __eq__，却没有同时定义 __hash__，那么这个类的实例会变得不可哈希，也就是不能放进 set，也不能作为 dict 的键。

原因在于 Python 的 set 和 dict 依赖哈希值来定位对象，同时依赖 __eq__ 判断是否相等。如果两个逻辑上相等的对象哈希值不同，字典就会出现找不到键、重复存储等错误。所以语言干脆在 __eq__ 被定义后，把 __hash__ 设为 None，强制你去思考哈希问题。

实际写代码时，你几乎必然遇到这个报错：

python复制class User:
    def __init__(self, name):
        self.name = name

    def __eq__(self, other):
        if not isinstance(other, User):
            return NotImplemented
        return self.name == other.name

users = {User("alice"), User("bob")}  # TypeError: unhashable type: 'User'

解决方案是根据不可变字段实现 __hash__：

python复制class User:
    def __init__(self, name):
        self.name = name

    def __eq__(self, other):
        if not isinstance(other, User):
            return NotImplemented
        return self.name == other.name

    def __hash__(self):
        return hash(self.name)

这时两个名字相同的 User 对象既会被判定为相等，也会拥有相同的哈希值，放入 set 后可以正常去重。

这里有两条经验要记住：第一，哈希值最好基于不可变字段，比如用户 ID 或字符串名称；如果基于一个会被修改的字段，对象放进 dict 后字段一变，哈希值也跟着变，就会出现“键存进去却再也取不出来”的诡异问题。第二，实现 __eq__ 时，如果类型不匹配应该返回 NotImplemented，给它尝试反向比较的机会；如果直接返回 False，就会把不同类型对象的比较结果也固化下来，可能带来微妙错误。

5. 属性访问协议：从 __getattr__ 到描述符的底层链路

5.1 __getattr__ 与 __getattribute__：一个是“兜底”，一个是“必经之路”

类属性访问有两个容易混淆的方法：__getattr__ 和 __getattribute__。

__getattribute__ 是每次访问属性都会调用的入口。几乎所有属性获取都会经过它，然后再根据名字去查找类属性、实例属性、描述符等。因为它的介入时机非常早，你几乎不应该在普通业务代码里重写它，否则稍不小心就会陷入无限递归。

__getattr__ 则不同。它只在属性查找失败的最后一刻才被调用。也就是说，Python 先是正常查找属性，找不到才回头调用 __getattr__。这让它非常适合实现“动态字段”和“配置兜底”。

举个例子，一个配置对象希望允许用 config.timeout 这种点访问方式获取配置项，但配置项实际存储在字典里：

python复制class Config:
    def __init__(self, values):
        self._values = values

    def __getattr__(self, name):
        if name in self._values:
            return self._values[name]
        raise AttributeError(f"Config has no attribute {name!r}")

config = Config({"timeout": 30, "retry": 3})
print(config.timeout)   # 30，name 不在普通属性中，进入 __getattr__
print(config.retry)     # 3

这个模式的好处是调用方可以像访问普通属性一样读取配置，不用到处写字典的方括号，代码整洁不少。但要小心：config._values 这个属性本身存在于实例字典里，所以直接访问 _values 不会进入 __getattr__。如果属性名真的不存在，我们手动抛出 AttributeError 也很重要，否则外部代码用 getattr(config, "nonexist") 或 hasattr(config, "nonexist") 时行为会变得不可预测。

5.2 属性写入拦截：给字段加上边界检查

跟读取相对的，是写入控制。__setattr__ 在每次给实例属性赋值时被调用。利用它可以做统一的字段校验、类型检查、甚至告警。

python复制class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __setattr__(self, name, value):
        if name == "age" and value < 0:
            raise ValueError("age cannot be negative")
        object.__setattr__(self, name, value)

p = Person("Alice", 30)
p.age = -1   # ValueError: age cannot be negative

这个实现里最关键的一行是 object.__setattr__(self, name, value)。你绝不能写成 self.name = value，那会再次触发 __setattr__，形成无限递归，直到 Python 抛出递归深度错误。

在我见过的一些项目里，用 __setattr__ 做“属性名保护”也是常见需求。比如你不希望外部代码随意覆盖内部字段，或者希望某些字段只读，都可以在这里拦截。但要注意粒度：不要在 __setattr__ 里写一大堆业务分支，它不只是对象构造时被调用，后续每一次赋值都会经过。负担太重、分支太多，很容易拖慢性能，也让类难以维护。

5.3 描述符协议：所有 ORM 字段与校验器的地基

讲完属性访问，就绕不开“描述符”。描述符是 Python 属性协议里非常核心的机制，@property、类方法、静态方法都是描述符协议的封装。理解描述符，等于看懂了 Django ORM 的 Field 为什么能自动接管数据库字段校验，也更容易理解 SQLAlchemy、Pydantic 这类库的底层思路。

描述符