Python 装饰器：@property

在 Python 的对象模型中，属性访问与方法调用共享统一的命名空间，但表达的语义却不同：属性描述对象的状态，方法表达对象的行为。随着类设计的演进，原本以属性公布的值可能需要延迟计算、加入校验逻辑、动态生成或与其他属性保持同步。

如果直接将属性改写为方法，不仅破坏既有的 API，还会使调用方式从：

obj.area

变为：

obj.area()

这种变化违背“接口稳定性”原则，不利于代码维护。

@property 应运而生，它可以将无参方法以属性形式呈现，使访问简单直观，但背后仍由方法控制逻辑，同时兼顾封装性、可扩展性和接口稳定性。

一、什么是 @property

@property 是 Python 内置的装饰器，用于将实例方法转换为描述符对象，使其在访问时触发自定义逻辑。其核心目标包括：

（1）提供优雅的属性访问语法

将方法逻辑以属性形式暴露，例如 obj.area 而不是 obj.area()。

（2）支持基于方法的动态计算或延迟求值

允许在属性访问时执行逻辑，而无需改变 API 约定。

（3）提升封装性

通过 getter、setter、deleter 控制属性的读取、赋值和删除行为。

（4）保持 API 的向后兼容

当原本的公开属性需要扩展逻辑时，可用 property 保持调用方式不变。

从 Pythonic 风格看，@property 是“显式优于隐晦”的体现：它让用户以简单的语法访问有逻辑支持的属性。

二、@property 工作原理

@property 的底层基于。

在 Python 中，任何实现以下方法之一的对象都被视为描述符：

__get__(self, instance, owner)

__set__(self, instance, value)

__delete__(self, instance)

描述符对象可以控制某个属性在 读取、写入、删除 时的行为。

property 本质是内置类：

    def __delete__(self, instance): ...

当我们定义：

        return ...

解释器会将 x 替换为一个 property 实例，其内部维护三个方法：

• fget：取值逻辑（getter）

• fset：赋值逻辑（setter）

• fdel：删除逻辑（deleter）

当执行：

obj.x

实际等价于：

A.x.__get__(obj, A)

即调用 fget(obj)。

类似地：

• 赋值 obj.x = value 等价于 A.x.__set__(obj, value)

• 删除 del obj.x 等价于 A.x.__delete__(obj)

因此，property 与简单属性不同，它是具有行为的托管属性。

三、核心方法：getter/setter/deleter

property 的三个核心组件共同构成完整的托管属性机制。

（1）getter：属性读取逻辑

最基本的 @property 用法是定义只读属性。

        return 3.14159 * self.r ** 2

使用：

print(c.area)     # 访问 area 属性时会自动调用其 getter（触发 fget 方法）

（2）setter：属性赋值逻辑

setter必须使用与 getter 同名的装饰器：

p.age = 20      # 访问 age 属性时会自动调用其 setter（触发 fset 方法）

说明：@age.setter 并不是随意命名，而是绑定到同一个 property 对象上，因此名称必须与 getter 相同。

（3）deleter：属性删除行为

用于资源释放或状态清理。

del res.conn   # 访问 conn 属性时会自动调用其 deleter（触发 fdel 方法）

说明：@conn.deleter 绑定的是同名 property 对象的删除逻辑方法，确保删除行为受控。

getter、setter 和 deleter 都必须保持与原 property 对象同名，确保访问行为受控。

四、典型应用场景

（1）将计算逻辑转换为自然的属性语法

当某个值由其他属性推导而来时，使用 property 会让 API 更自然。

        return self.w * self.h

用户角度：

rect.area   # 比 rect.area() 更直观

这是最常见的用法：用户访问属性时实际触发方法逻辑。

（2）为属性添加校验逻辑

避免直接暴露内部成员。

        self._c = value

（3）保持 API 向后兼容

当属性从简单值变成计算值时，不破坏调用方式。

初始版本中：

obj.speed = 12  # 简单属性

后来想加入单位转换或校验：

        self._speed = value

外部代码无需调整。

（4）隐藏内部实现，保护成员命名自由

有了 property 之后，可以随意修改内部成员名（如从 value → _value → _internal_value），让类具有更好的可维护性与扩展性。

五、常见误区

误区 1：在 getter 内访问自身属性导致无限递归

错误示例：

    return self.x   # 再次访问 property → 无限递归

正确写法：

    return self._x

误区 2：误认为 property 会自动缓存

每次访问都会重新计算。

如果需要缓存，应使用：

from functools import cached_property

误区 3：getter、setter 名称不一致

在使用 property 时，setter 方法必须绑定到同一个 property 对象上，因此名称必须与 getter 相同，否则不会生效：

    ...

误区 4：将 property 当作带参数的方法使用

property 只能表现为无参属性：

obj.value(3) # 错误

小结

@property 基于描述符协议实现，是 Python 中用于创建托管属性的核心机制。它让开发者以属性语法访问方法逻辑，在保持接口简洁的同时获得计算、校验与封装能力。通过 getter、setter 与 deleter，可以设计稳定且易维护的类接口。使用 property 时应避免递归访问、滥用复杂逻辑或错误绑定 setter，以保持类结构清晰、设计合理。

“点赞有美意，赞赏是鼓励”