Python property函数用法：参数详解与代码示例

一、为什么需要 property 函数

在许多面向对象语言（如 Java）中，为了保护对象内部状态，开发者通常将字段设为私有，并显式编写 get_attr() 与 set_attr() 方法。如果在 Python 中直接采用这种方式，代码调用会变得繁琐，且破坏了属性直接点号访问的简洁性；反之，若直接开放公有属性 self.attr，外部调用方就可以随意赋入非法值（例如给半径或年龄赋负数），无法保证数据的有效性。

property() 函数正是解决这一矛盾的核心机制。它在保持外部点号访问形式不变的前提下，由 Python 解释器在底层自动将属性读写操作委托给对应的方法执行，实现了接口一致性与数据安全性的统一。

二、property 函数的参数详解

Python 官方内置的 property() 函数完整签名如下：

property(fget=None, fset=None, fdel=None, doc=None) -> property attribute

该函数接收四个可选参数，每个参数对应属性生命周期中的一种操作或元数据：

三、property 的函数式调用与代码示例

第一种使用方式是直接调用 property() 内置函数。这种方式直观体现了函数参数的传递过程，适合在类的末尾统一组装属性接口。

1. 经典函数式封装示例

以下代码定义了一个 Temperature 类，将摄氏温度存储在私有变量 _celsius 中，并通过 property() 绑定取值、赋值和删除行为，同时在赋值阶段进行绝对零度（-273.15℃）有效性校验：

class Temperature:
    def __init__(self, celsius=0.0):
        # 初始赋值时直接走 setter 逻辑，确保合法性
        self._celsius = 0.0
        self.celsius = celsius

    def get_celsius(self):
        """读取摄氏温度"""
        return self._celsius

    def set_celsius(self, value):
        """设置摄氏温度并校验下限"""
        if not isinstance(value, (int, float)):
            raise TypeError("温度必须是数字类型")
        if value < -273.15:
            raise ValueError("温度不能低于绝对零度 (-273.15°C)")
        self._celsius = float(value)

    def del_celsius(self):
        """禁止直接删除温度属性"""
        raise AttributeError("不允许删除 celsius 属性")

    # 通过 property 函数集中组装
    celsius = property(
        fget=get_celsius,
        fset=set_celsius,
        fdel=del_celsius,
        doc="摄氏温度属性，支持范围校验与删除保护。"
    )

# 示例执行与输出验证
t = Temperature(25)
print(f"当前温度: {t.celsius}")  # 示例输出: 当前温度: 25.0

t.celsius = 36.5
print(f"更新温度: {t.celsius}")  # 示例输出: 更新温度: 36.5

try:
    t.celsius = -300
except ValueError as e:
    print(f"校验拦截: {e}")  # 示例输出: 校验拦截: 温度不能低于绝对零度 (-273.15°C)

四、装饰器语法糖：现代 Python 惯用写法

在日常开发中，直接使用 @property 装饰器比直接调用函数更为普遍。两者在语义和底层执行机制上完全等价，但装饰器写法结构更内聚、函数名更简洁统一。

1. 装饰器的工作等价原理

当使用 @property 装饰一个方法时，Python 会生成一个只包含 fget 的 property 对象。随后，该对象提供了 .setter 和 .deleter 辅助装饰器方法，用于绑定赋值和删除处理函数，并返回一个配置完备的新 property 对象：

• @property：将方法注册为 fget，相当于 attr = property(fget=attr)；
• @attr.setter：将新方法注册为 fset，相当于 attr = attr.setter(new_func)；
• @attr.deleter：将新方法注册为 fdel，相当于 attr = attr.deleter(new_func)。

2. 装饰器写法完整示例

class Circle:
    def __init__(self, radius):
        self._radius = 0.0
        # 统一使用 setter 执行初始化与边界校验
        self.radius = radius

    @property
    def radius(self):
        """圆的半径（必须为正数）"""
        return self._radius

    @radius.setter
    def radius(self, value):
        if not isinstance(value, (int, float)):
            raise TypeError("半径必须为数值类型")
        if value <= 0:
            raise ValueError("半径必须大于 0")
        self._radius = float(value)

    @property
    def area(self):
        """只读属性：根据当前半径动态计算面积"""
        import math
        return math.pi * (self._radius ** 2)

# 测试代码
c = Circle(5)
print(f"半径: {c.radius}")       # 示例输出: 半径: 5.0
print(f"面积: {c.area:.2f}")     # 示例输出: 面积: 78.54

c.radius = 10
print(f"新面积: {c.area:.2f}")   # 示例输出: 新面积: 314.16

try:
    c.area = 500  # 尝试修改只读属性
except AttributeError as e:
    print(f"只读拦截: {e}")      # 示例输出: 只读拦截: property 'area' of 'Circle' object has no setter

五、开发中的常见陷阱与注意事项

1. 属性名与底层私有变量名重名（递归死循环）

这是初学者使用 property 最容易遇到的严重错误：在 getter 或 setter 方法内部，如果直接访问托管属性本身而非底层私有变量（通常以前导单下划线命名，如 self._x），会导致无限递归，抛出 RecursionError: maximum recursion depth exceeded。

# 错误示例：引发递归死循环
class BadCase:
    def __init__(self, val):
        self.val = val

    @property
    def val(self):
        # 错误：再次访问 self.val 会重复调用当前 getter 方法！
        return self.val

    @val.setter
    def val(self, value):
        # 错误：self.val = value 再次触发当前 setter 方法！
        self.val = value

# 正确做法：使用带下划线的不同名称存储实际数据，如 self._val

2. 只读属性与动态计算

若希望属性为只读属性，只需在类中仅定义 fget（或仅使用 @property 装饰），不提供 fset 或 @attr.setter。任何尝试通过 obj.attr = new_val 进行赋值的操作都会被 Python 解释器直接抛出 AttributeError: can't set attribute（在 Python 3.11+ 中为 has no setter）。

这常用于只依赖其他属性动态生成的计算属性（如上面示例中的 Circle.area 或人员的 full_name），避免由于数据冗余缓存造成的状态不同步。

3. 文档字符串的继承与提示

当使用函数式写法 property(fget, fset, fdel, doc) 时，若未提供 doc，它会自动使用 fget 的 __doc__。而使用 @property 装饰器时，写在 getter 方法第一行的文档注释将被自动提取为整个 property 属性的文档，无论是调用 help() 还是在 VSCode / PyCharm 中悬停查看类型提示，都能完整呈现。

六、总结速查表