Python @property装饰器与property()函数写法有什么区别

一、两种写法的基本形式与代码结构对比

为了直观感受代码组织形态的不同，我们以一个电商领域中常见的商品模型 Product 为例，该模型需要对单价 price 属性进行非负数校验。

1. 函数式写法：property() 显式传递参数

在 Python 早期版本（以及如今的动态构建逻辑中），定义一个受控属性的标准方式是先编写常规的辅助方法，然后在类体末尾调用内置 property() 函数完成实例化与属性绑定：

class ProductByFunc:
    def __init__(self, price: float):
        self._price = price

    # 1. 定义独立的 getter 辅助方法
    def _get_price(self) -> float:
        return self._price

    # 2. 定义独立的 setter 辅助方法
    def _set_price(self, value: float) -> None:
        if value < 0:
            raise ValueError("价格不能为负数")
        self._price = value

    # 3. 定义独立的 deleter 辅助方法
    def _del_price(self) -> None:
        del self._price

    # 4. 在类命名空间中集中组装并暴露公开属性
    price = property(
        fget=_get_price,
        fset=_set_price,
        fdel=_del_price,
        doc="商品的单价（元），自动校验非负"
    )

这种写法的特点是逻辑相对分散：_get_price、_set_price 等函数名称存在于类的作用域内。即使开发者约定俗成地加上单下划线前缀，它们依然作为独立的实例方法暴露在对象字典中。

2. 装饰器写法：@property 原位标注

现代 Python 代码中普遍推荐采用装饰器语法。此时所有存取方法的名称与公开属性完全同名，通过不同的修饰符区分职能：

class ProductByDec:
    def __init__(self, price: float):
        self._price = price

    @property
    def price(self) -> float:
        """商品的单价（元），自动校验非负"""
        return self._price

    @price.setter
    def price(self, value: float) -> None:
        if value < 0:
            raise ValueError("价格不能为负数")
        self._price = value

    @price.deleter
    def price(self) -> None:
        del self._price

在外部调用时，两种写法的表现完全一致：无论是 p.price 触发读取，p.price = 99.5 触发写入校验，还是 del p.price 触发删除，外部使用者均感受不到底层实现的区别。

二、底层机制：@property 是如何等价展开的？

许多初学者会产生一个疑问：在装饰器写法中，为什么 getter、setter 和 deleter 必须使用一模一样的函数名？为什么定义了 @price.setter 之后，前面的函数不会被简单粗暴地覆盖丢弃？

理解这个问题的关键，在于了解 property 对象的不可变设计以及 Python 解释器对装饰器的去糖（Desugaring）过程。

1. 逐步推导展开过程

当 Python 解释器解析 ProductByDec 类定义体时，发生了如下连续计算：

1. 创建只读属性：执行 @property def price(self): ... 时，解释器先创建普通函数 price，随后执行 price = property(price)。此时，变量 price 已经不再是一个函数，而是一个 property 类型的描述符实例，它的 fget 槽位保存了该函数的引用，同时自动提取其文档字符串。
2. 挂载写入逻辑：接着遇到 @price.setter def price(self, value): ...。这里的 price 正是第一步产生的描述符对象。该对象拥有内置方法 .setter(fset)。
3. 返回新描述符并重新赋值：在 CPython 源码中，property 对象是不可变的（Immutable）。调用 price.setter(...) 绝不会就地修改原对象，而是重新分配一个全新的 property 实例，该实例拷贝了原先的 fget、fdel 和 __doc__，并将新的 fset 填入对应槽位。最后，由于函数名依然是 price，新生成的描述符再次赋值给类变量 price，完成了无缝替换。

三、运行期执行：描述符协议与调用拦截

当我们在业务逻辑中通过实例访问属性时，Python 解释器究竟是如何介入并分发调用的？这就涉及到 Python 面向对象的核心骨架——描述符协议（Descriptor Protocol）。

1. 属性查找优先级与拦截原理

任何实现了 __get__、__set__ 或 __delete__ 特殊方法的对象都被称为描述符。当一个描述符同时实现了 __get__ 和 __set__ 时，它被称为数据描述符（Data Descriptor）。

在 Python 的对象模型中，数据描述符的查找优先级严格高于实例自身的字典（__dict__）。这意味着：

• 当执行 obj.price 时，解释器检测到类属性 price 是一个带有 __get__ 的描述符，因此直接调用 Product.price.__get__(obj, Product)，进而触发绑定的 fget(obj)。
• 当执行 obj.price = 100 时，解释器直接调用 Product.price.__set__(obj, 100)。若该描述符没有配置 fset（例如仅使用了 @property 的只读属性），描述符内部会直接抛出 AttributeError: can't set attribute。
• 即使恶意代码试图通过 obj.__dict__['price'] = -50 绕过校验注入实例字典，下一次直接访问 obj.price 时，解释器依然会优先走 __get__ 逻辑，从而确保内部状态的严密防护。

四、继承与子类重写：常见的失效陷阱与解决方案

在类的继承体系中，针对属性的重写是两种写法产生认知分化、也是开发者最容易踩坑的场景之一。

1. 常见陷阱：直接用 @property 重写导致 setter 丢失

假设我们有一个基础商品类，子类 DiscountProduct 想要在读取价格时计算折扣，但希望沿用父类的价格写入校验逻辑。许多人会习惯性地写出如下代码：

class DiscountProductBad(ProductByDec):
    @property
    def price(self) -> float:
        # 尝试仅重写 getter，打八折
        return super().price * 0.8

# 运行测试
p = DiscountProductBad(100.0)
print(p.price)      # 输出: 80.0（正常读取）
p.price = 200.0     # 报错！AttributeError: can't set attribute

原因剖析：子类中的 @property def price(self) 重新执行了 price = property(fget)，完全新建了一个不包含 fset 的全新描述符，把父类继承而来的完整描述符彻底覆盖了！

2. 正确解决方案：借由父类描述符追加或重写

如果希望在子类中单独重写或保留某一个维度的行为，必须明确引用父类的描述符：

class DiscountProductGood(ProductByDec):
    # 方案 A：在子类中重写 getter，同时复用父类的 setter
    @ProductByDec.price.getter
    def price(self) -> float:
        return self._price * 0.8

    # 方案 B：如果子类只重写 setter，则借由父类描述符挂载
    # @ProductByDec.price.setter
    # def price(self, value: float) -> None:
    #     super(DiscountProductGood, type(self)).price.fset(self, value)

而如果使用 property() 函数写法，由于各环节均是显式的普通方法，重写通常体现为重写 _get_price() 方法，然后在子类中重新定义 price = property(_get_price, Parent._set_price)。相比之下，装饰器写法的 @BaseClass.prop.getter 在语义上更为直白精确。

五、动态元编程：property() 函数不可替代的独特优势

既然 @property 装饰器语义优美、内聚度高，那么原始的 property() 函数写法是否已经沦为过时的历史包袱？

答案是否定的。在动态生成属性、属性工厂模式以及批量元编程场景下，property() 函数是不可或缺的核心利器。因为装饰器语法依赖于 def 静态语法节点，无法直接放置在循环或动态构建流程中。

典型实战：通用属性工厂（Property Factory）

假设我们正在开发一个配置对象或 ORM 框架，需要为数十个字段提供统一的“非空字符串校验”与“私有存储代理”。如果使用 @property 装饰器，必须机械地复制粘贴数十次几乎相同的代码模板；而使用 property() 函数式工厂，只需几十行代码即可优雅实现：

def string_field(storage_name: str, doc: str = ""):
    """动态生成属性描述符的闭包工厂函数"""
    def fget(self):
        return getattr(self, storage_name, "")

    def fset(self, value):
        if not isinstance(value, str) or not value.strip():
            raise ValueError(f"属性必须为非空字符串")
        setattr(self, storage_name, value.strip())

    # 直接返回动态构建的 property 实例
    return property(fget, fset, doc=doc)


class UserProfile:
    # 使用工厂动态声明，无需编写任何冗余的 getter/setter 函数体
    username = string_field("_username", doc="用户昵称")
    email = string_field("_email", doc="联系邮箱")
    company = string_field("_company", doc="所属组织")

    def __init__(self, username: str, email: str, company: str):
        self.username = username
        self.email = email
        self.company = company

在上述案例中，property() 作为一等公民函数直接在闭包中装配并返回。这种动态配置在元类（Metaclass）、类装饰器以及批量绑定字段时发挥着巨大威力，这恰恰是静态的 @property 语法糖难以实现的。

六、全方位特性对比与开发规范总结

为了帮助大家在日常架构设计与代码评审中迅速决策，我们将两种写法的关键差异总结如下：