Python @property底层原理：描述符协议与访问机制解析

一、什么是描述符协议？从普通属性到行为托管

在 Python 中，绝大多数对象的实例属性都保存在名为 __dict__ 的字典中。当我们执行 obj.price = 100 时，默认操作只是简单地向 obj.__dict__['price'] 写入一个键值对。这种朴素的机制无法在赋值时自动执行边界检查、类型验证或惰性计算。

为了在属性读取、设置或删除时插入自定义逻辑，Python 提出了描述符协议（Descriptor Protocol）。协议规定：只要一个类定义了以下三个特殊方法中的任意一个，这个类的实例就是一个“描述符”：

• __get__(self, instance, owner=None)：在读取属性时被触发。instance 为调用该属性的具体对象实例，owner 为所属的类。
• __set__(self, instance, value)：在对属性进行赋值操作时被触发。
• __delete__(self, instance)：在使用 del obj.attr 语法删除属性时被触发。

数据描述符与非数据描述符的分水岭

Python 根据描述符实现的方法，将其严格划分为两类，这也是理解属性访问顺序的关键分水岭：

1. 数据描述符（Data Descriptor）：只要类中实现了 __set__() 或 __delete__() 方法（无论是否实现了 __get__()），它就是数据描述符。
2. 非数据描述符（Non-Data Descriptor）：类中仅实现了 __get__() 方法，没有定义 __set__() 和 __delete__()。Python 中的普通函数、@classmethod 和 @staticmethod 本质上都是非数据描述符。

许多初学者常犯的一个直觉性误解是：“如果我只写了 @property 而没有写 @attr.setter，它是不是就变成了非数据描述符？”答案是否定的。Python 内置的 property 类自始至终都是数据描述符。即使你没有声明 setter，property 的内部也定义了 __set__()，只是其默认行为是直接抛出 AttributeError: can't set attribute。

二、属性访问机制解析：为什么 @property 能压制实例字典？

当我们在 Python 代码中编写 val = obj.attr 时，解释器究竟经历了哪些检索步骤？理解这个推导过程，才能真正明白为什么 @property 可以接管一切。

点号操作符的默认行为由基类 object 的 __getattribute__ 方法实现。对于一个常规实例 obj（类型为 Cls = type(obj)），读取属性 attr 的查找优先级如下：

推导步骤与执行细节

1. 第一步（类 MRO 检查数据描述符）：解释器首先在 Cls.__mro__（类的继承链字典）中搜索是否存在名为 attr 的属性。如果找到了，并且该对象是数据描述符（定义了 __set__ 或 __delete__），解释器直接调用该描述符的 __get__(obj, Cls) 并将其返回值交付给调用方。整个查找链路在此短路结束，完全不看实例自己的字典。
2. 第二步（实例局部字典查找）：如果类层级中没有同名属性，或者该属性不是数据描述符，解释器转而检查实例自身的字典 obj.__dict__。如果 'attr' in obj.__dict__，则直接返回 obj.__dict__['attr']。
3. 第三步（类层级非数据描述符与常规类属性）：如果实例字典中不存在该键，解释器再次回到类的 MRO 字典中：
   • 如果该属性是非数据描述符（如普通方法），则调用其 __get__(obj, Cls) 进行方法绑定（生成 bound method）；
   • 如果只是普通的类变量（例如字符串或数字），则直接返回该类变量值。
4. 第四步（回退保底机制）：如果上述步骤均未命中，且类定义了 __getattr__(self, name)，则调用该兜底方法；若未定义，则抛出经典的 AttributeError。

三、拆解 @property：纯 Python 实现与闭包机制

为了剥离 CPython 底层 C 源码的语法干扰，我们可以使用纯 Python 代码完整实现一个功能一致的 MyProperty 类。通过代码的结构，我们可以清晰地看到 getter、setter 以及 deleter 是如何挂载与替换的。

class MyProperty:
    """纯 Python 模拟内置 property 描述符"""
    def __init__(self, fget=None, fset=None, fdel=None, doc=None):
        self.fget = fget
        self.fset = fset
        self.fdel = fdel
        self.__doc__ = doc or (fget.__doc__ if fget else None)

    def __get__(self, instance, owner=None):
        # 若由类直接访问 (例如 Cls.attr)，返回描述符本身
        if instance is None:
            return self
        if self.fget is None:
            raise AttributeError("unreadable attribute")
        return self.fget(instance)

    def __set__(self, instance, value):
        if self.fset is None:
            raise AttributeError("can't set attribute")
        self.fset(instance, value)

    def __delete__(self, instance):
        if self.fdel is None:
            raise AttributeError("can't delete attribute")
        self.fdel(instance)

    def getter(self, fget):
        return type(self)(fget, self.fset, self.fdel, self.__doc__)

    def setter(self, fset):
        return type(self)(self.fget, fset, self.fdel, self.__doc__)

    def deleter(self, fdel):
        return type(self)(self.fget, self.fset, fdel, self.__doc__)

链式装饰的过程发生了什么？

很多开发者容易混淆 @prop.setter 的返回值。仔细观察上述代码中的 setter 方法：它并不是直接在原描述符对象上进行就地修改（In-place mutation），而是创建并返回了一个全新的描述符实例，将既有的 fget、新的 fset 以及 fdel 组合封装。

当执行以下标准语法时：

class BankAccount:
    def __init__(self, balance):
        self._balance = balance

    @property
    def balance(self):
        return self._balance

    @balance.setter
    def balance(self, value):
        if value < 0:
            raise ValueError("余额不可为负数")
        self._balance = value

解释器的执行步骤是：

1. 解析第一个 def balance(self)，经过 @property 修饰后，生成只读描述符实例 A，类字典中 BankAccount.__dict__['balance'] = 描述符A。
2. 解析随后的 @balance.setter，调用 描述符A.setter(新的函数)，生成包含 getter 与 setter 的全新描述符实例 B。
3. 由于函数名同为 balance，类字典完成重写：BankAccount.__dict__['balance'] = 描述符B。描述符 A 随后成为无引用的临时对象被垃圾回收。

四、容易踩坑的关键细节与边界条件

1. 属性同名递归错误（RecursionError）

这是刚接触 @property 时最容易出现的错误：

# 错误示例
class User:
    def __init__(self, name):
        self.name = name  # 触发 setter

    @property
    def name(self):
        return self.name  # 递归调用 getter！导致 RecursionError

    @name.setter
    def name(self, value):
        self.name = value  # 递归调用 setter！导致 RecursionError

原因剖析：在 setter 内部执行 self.name = value 时，由于 name 是类层级的数据描述符，它会再次被优先级机制拦截，从而再次调用 setter，形成死循环。

正确规范：底层存储必须使用不同名称的私有变量或保护变量（如 self._name），以避开描述符的同名拦截。

2. 为什么描述符必须定义在类层级，不能定义在实例层级？

如果尝试在 __init__ 中给 self.prop = property(...)，你会发现它完全失去拦截作用，只会被当成一个普通对象存入 self.__dict__。

这是因为根据查找规则（参见图 2 步骤 1），Python 是从对象的类型（type(obj).__mro__）开始检索描述符的。Python 根本不会检查 self.__dict__ 中的值是否实现了描述符协议，避免了在普通字典查找中引入巨大的函数调用开销。

五、机制总结与横向对比

为了在架构设计中准确选用适合的工具，我们对普通字段、非数据描述符与 @property 数据描述符的运行机制进行全景对比：