Python魔术方法命名规范：__init__等双下划线前后缀方法详解

在 Python 面向对象编程中，以双下划线开头并以双下划线结尾的方法（如 __init__、__str__、__len__）被称为特殊方法（Special Methods），在社区日常交流中常被称为魔术方法或简称为 Dunder Methods（源自“Double UNDERscore”）。这类命名的核心规则非常清晰：双下划线前后缀是 Python 官方解释器保留的内部命名空间，用于将用户自定义类的实例行为无缝接入 Python 原生语法（例如运算符号、类型转换、迭代协议等）。用户在编写业务代码时，应当只实现官方既有规范定义的魔术方法，切勿私自生造相同命名格式的新方法。

一、Python 下划线命名体系全景对比

下划线在 Python 语法中承载了多种维度的语义约束。从单下划线前缀到双下划线修饰，每种形式的作用范围和运行时机制各有不同。理解双下划线前后缀的特殊地位，首先需要建立清晰的下划线命名全貌。

从规范定义可知，__foo__ 这类前后双下划线方法并不是魔法，而是 Python 提供给类的“协议接口”。当自定义类实现了某个特定方法名，Python 运行时就会允许该类的实例参与到该方法所对应的核心语法体系中。

二、对象生命周期魔术方法：从 __new__ 到 __init__

在所有魔术方法中，__init__ 是开发者最先接触且使用频率最高的方法。许多初学者常将其误认为是对象的“构造函数（Constructor）”。在底层实现中，Python 将对象的“创建”与“初始化”清晰地解耦为了两个先后执行的阶段：__new__ 负责构造实例并分配空间，__init__ 负责接收该实例并初始化属性。

代码演示：__new__ 与 __init__ 的协同工作

以下代码演示了通过重写 __new__ 控制对象创建（例如单例缓存），以及 __init__ 负责属性初始化的协作过程：

class DatabaseConnection:
    _instance = None

    def __new__(cls, *args, **kwargs):
        # 仅在第一次调用时通过父类构造实例
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance._initialized = False
        return cls._instance

    def __init__(self, host: str, port: int):
        # 避免单例多次重复初始化
        if not self._initialized:
            self.host = host
            self.port = port
            self._initialized = True
            # 严格禁止: return self 或 return "ok"

# 实例化测试
conn1 = DatabaseConnection("localhost", 3306)
conn2 = DatabaseConnection("127.0.0.1", 3306)

print(f"是否为同一实例: {conn1 is conn2}")
print(f"当前主机地址: {conn1.host}")

输出结果（示例）：

是否为同一实例: True
当前主机地址: localhost

三、核心魔术方法分类与语法协议映射

Python 之所以被认为“语法优雅且一致”，正是因为其遵循数据模型（Data Model）规范。当外部使用 len(x)、x[key]、a + b 或 with x: 时，Python 解释器在内部统一派发给对应的魔术方法。只要开发者实现了特定的魔术方法，自定义对象就可以无缝融入内置语法。

1. 字符串表现：__repr__ 与 __str__ 的区别

很多开发者在重写对象展示时混淆 __str__ 和 __repr__。它们的分工非常清晰：

• __repr__（Representation）：目标受众是开发者。输出应尽量精确、无歧义，理想情况下其输出字符串能够直接放入 eval() 中重建该对象（例如 User(name='Alice', age=20)）。
• __str__（String）：目标受众是普通用户。输出应具备良好的人类可读性（例如 Alice (20岁)）。
• 回退机制：如果一个类只定义了 __repr__，当调用 str(obj) 或 print(obj) 时，Python 会自动回退调用 __repr__；但反过来，只定义 __str__ 时，容器打印（如 [obj]）和交互式解释器仍会显示默认的内存地址信息。因此，推荐优先实现 __repr__。

class Product:
    def __init__(self, sku: str, price: float):
        self.sku = sku
        self.price = price

    def __repr__(self) -> str:
        return f"Product(sku={self.sku!r}, price={self.price})"

    def __str__(self) -> str:
        return f"商品[{self.sku}] 售价: ¥{self.price:.2f}"

item = Product("A-1024", 99.5)
print(str(item))   # 触发 __str__ -> 商品[A-1024] 售价: ¥99.50
print(repr(item))  # 触发 __repr__ -> Product(sku='A-1024', price=99.5)
print([item])      # 列表容器默认调用内部元素的 __repr__

2. 序列协议与切片支持：自定义安全数据列表

如果希望某个类表现得像列表一样可以被索引、求长度，只需实现 __len__ 与 __getitem__：

class DataBatch:
    def __init__(self, items):
        self._data = list(items)

    def __len__(self) -> int:
        return len(self._data)

    def __getitem__(self, index):
        # 支持单个整数下标与 slice 切片对象
        if isinstance(index, slice):
            return DataBatch(self._data[index])
        return self._data[index]

batch = DataBatch([10, 20, 30, 40, 50])
print(len(batch))         # 输出: 5
print(batch[1])           # 输出: 20
print(batch[1:4]._data)   # 切片输出: [20, 30, 40]

3. 上下文协议：__enter__ 与 __exit__

当对象配合 with 语句使用时，进入代码块触发 __enter__，退出代码块触发 __exit__。无论中间是否发生异常，__exit__ 都会被可靠调用，非常适合资源加锁、事务管理与文件句柄释放。

class ExecutionTimer:
    def __enter__(self):
        import time
        self.start = time.perf_counter()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        import time
        self.duration = time.perf_counter() - self.start
        print(f"代码块执行完毕，耗时: {self.duration:.4f} 秒")
        # 返回 False（或默认None）表示不静默异常，异常将继续向外抛出
        return False

四、魔术方法的规范实现与防错指南

魔术方法虽然赋予了类强大的扩展能力，但违背其命名规范和设计契约会引入严重的运行时隐患。在编写和维护魔术方法时，开发者应严格遵守以下四项核心准则。

比较运算符重载的规范写法示例

重写 __eq__ 与比较方法时，务必处理传入参数类型不匹配的情况。返回 NotImplemented 可以让 Python 解释器有机会尝试对方的反向比较逻辑：

class Money:
    def __init__(self, amount: float, currency: str):
        self.amount = round(amount, 2)
        self.currency = currency.upper()

    def __eq__(self, other) -> bool:
        if not isinstance(other, Money):
            # 关键：不要直接 raise TypeError，返回 NotImplemented 允许解释器协调
            return NotImplemented
        return self.amount == other.amount and self.currency == other.currency

    def __repr__(self) -> str:
        return f"Money({self.amount}, '{self.currency}')"

m1 = Money(100.0, "CNY")
m2 = Money(100.0, "CNY")
m3 = "100.0 CNY"

print(m1 == m2)  # True
print(m1 == m3)  # False（正确回退，未崩溃）

五、常用魔术方法速查表

为了便于日常编码时对标标准协议，下表总结了最常用的魔术方法及其触发场景与契约要求：