怎么利用Python @property实现数据验证和只读属性

在 Python 面向对象编程中，直接暴露类的实例属性虽然写法简便，却无法防止外部传入非法数据；如果沿用传统的 get_val() 和 set_val() 方法进行封装，又会破坏 Pythonic 的直接属性赋值体验。内置的 @property 装饰器正是解决这一矛盾的核心工具。它能够把类中的方法包装成可以通过 obj.attr 形式直接访问的属性，使开发者既能在取值时构建安全的“只读属性”，又能在赋值时透明地执行“数据验证”。本文将详细介绍这两项特性的具体实现步骤、底层拦截机制与常见避坑规则。

一、核心原理：@property 如何拦截属性读写

@property 本质上是 Python 描述符协议（Descriptor Protocol）的高层封装。当一个方法被 @property 装饰后，该方法就成为了类的一个属性描述符对象，负责接管对应属性名的一切读写操作。

通常情况下，Python 实例的属性存储在实例本身的 __dict__ 字典中。而一旦在类级别定义了 @property，解释器在执行 obj.name 读取或 obj.name = val 赋值时，会优先委派给该描述符对象中绑定的 getter 或 setter 函数，而不是直接操作实例字典。这种机制允许我们将真正的底层数据存储在带有单下划线前缀的受保护变量中（如 _name），并在外层函数中嵌入任何所需的校验逻辑。

二、实现只读属性：防止外部篡改与派生数据计算

在面向对象设计中，部分属性一旦在初始化后就不应被外部重新赋值（例如数据库主键、订单创建时间），还有部分属性是根据其他属性动态计算得出的派生值（例如长方形的面积由长和宽决定）。

利用 @property 实现只读属性的做法非常明确：只定义被 @property 装饰的方法（即 getter），而不为其提供对应的 @<name>.setter 方法。这样一来，外部依然能够像读取普通属性一样读取数据，但任何赋值尝试都会直接被 Python 解释器捕获并抛出 AttributeError。

1. 完整代码示例：动态计算与保护 ID

import datetime

class Order:
    def __init__(self, order_id: str, unit_price: float, quantity: int):
        # 将不可变标识保存在受保护变量中
        self._order_id = order_id
        self._created_at = datetime.datetime.now()
        self.unit_price = unit_price
        self.quantity = quantity

    # 1. 声明只读属性：订单唯一标识
    @property
    def order_id(self) -> str:
        return self._order_id

    # 2. 声明只读属性：创建时间
    @property
    def created_at(self) -> datetime.datetime:
        return self._created_at

    # 3. 声明动态只读属性：总价（根据价格和数量实时计算）
    @property
    def total_price(self) -> float:
        return round(self.unit_price * self.quantity, 2)

2. 运行结果验证

执行以下测试代码，观察属性读取与非法赋值时的控制台表现：

order = Order(order_id="ORD-202610-88", unit_price=49.9, quantity=3)

# 正常访问只读属性与动态计算属性
print(f"订单编号: {order.order_id}")       # 输出: ORD-202610-88
print(f"订单总额: {order.total_price}")    # 输出: 149.7

# 尝试篡改只读属性（将触发异常）
try:
    order.order_id = "ORD-NEW-999"
except AttributeError as e:
    print(f"捕获写保护异常: {e}")
    # 输出: 捕获写保护异常: property 'order_id' of 'Order' object has no setter

三、实现数据验证：拦截写入与参数多维校验

在业务逻辑中，很多属性需要支持外部修改，但必须限制在合理范围之内。例如：商品价格不能为负数、用户年龄必须为整数且在合理区间、电子邮箱必须包含特定格式等。

实现数据验证的核心步骤分为三步：

1. 定义 Getter：使用 @property 装饰方法，返回受保护的变量（如 return self._age）。
2. 定义 Setter：使用 @<属性名>.setter 装饰同名方法，接收待赋的值 value。
3. 编写校验逻辑并在不合法时抛出规范异常：类型错误抛出 TypeError，取值越界抛出 ValueError；通过校验后，再将值写入受保护变量 self._age = value。

完整示例代码：学生年龄与考试成绩校验

在下面的示例中，我们为 Student 类的 age（年龄）和 score（成绩）定义了严格的类型及边界验证规则，并在 __init__ 构造方法中直接调用公开属性，确保实例在初始化时也能自动享受相同的校验逻辑：

class Student:
    def __init__(self, name: str, age: int, score: float):
        self.name = name
        # 注意：这里直接赋值给 self.age 和 self.score，从而复用 setter 校验
        self.age = age
        self.score = score

    # --- age 属性的 Getter 与 Setter ---
    @property
    def age(self) -> int:
        return self._age

    @age.setter
    def age(self, value: int):
        if not isinstance(value, int):
            raise TypeError(f"年龄必须为整数类型 (int)，当前传入为: {type(value).__name__}")
        if not (5 <= value <= 100):
            raise ValueError(f"年龄取值必须在 5 到 100 岁之间，当前传入为: {value}")
        self._age = value

    # --- score 属性的 Getter 与 Setter ---
    @property
    def score(self) -> float:
        return self._score

    @score.setter
    def score(self, value: float):
        if not isinstance(value, (int, float)):
            raise TypeError(f"成绩必须为数值类型，当前传入为: {type(value).__name__}")
        if not (0.0 <= value <= 100.0):
            raise ValueError(f"成绩取值范围必须在 0.0 到 100.0 分之间，当前传入为: {value}")
        self._score = float(value)

验证异常触发与正常执行效果：

# 1. 正常创建对象并读取属性
stu = Student(name="张三", age=18, score=92.5)
print(f"学生: {stu.name}, 年龄: {stu.age}, 分数: {stu.score}")
# 输出: 学生: 张三, 年龄: 18, 分数: 92.5

# 2. 修改为合规数据
stu.score = 98.0
print(f"修改后分数: {stu.score}")  # 输出: 修改后分数: 98.0

# 3. 传入非法类型测试
try:
    stu.age = "二十岁"
except TypeError as e:
    print(f"类型异常: {e}")
    # 输出: 类型异常: 年龄必须为整数类型 (int)，当前传入为: str

# 4. 传入越界数值测试
try:
    stu.score = 150.0
except ValueError as e:
    print(f"取值异常: {e}")
    # 输出: 取值异常: 成绩取值范围必须在 0.0 到 100.0 分之间，当前传入为: 150.0

四、综合实践：同时管理只读属性与受控可写属性

在实际工程开发中，一个健壮的业务模型往往兼具只读属性与需要验证的可写属性。以银行账户管理场景为例：

• account_number（账号）和 created_at（开户时间）为只读属性，创建后不可更改；
• holder_name（开户人）和 balance（账户余额）为受控属性，其中余额只允许非负浮点数；
• status（账户等级）为派生只读属性，根据当前余额动态返回 "普通账户" 或 "VIP账户"。

class BankAccount:
    def __init__(self, account_number: str, holder_name: str, initial_balance: float):
        # 只读属性在底层单下划线变量中保存
        self._account_number = account_number
        # 赋值给公开属性，触发验证逻辑
        self.holder_name = holder_name
        self.balance = initial_balance

    # 1. 只读属性：账号
    @property
    def account_number(self) -> str:
        return self._account_number

    # 2. 需校验属性：开户人姓名
    @property
    def holder_name(self) -> str:
        return self._holder_name

    @holder_name.setter
    def holder_name(self, name: str):
        if not isinstance(name, str) or not name.strip():
            raise ValueError("开户人姓名必须是非空字符串")
        self._holder_name = name.strip()

    # 3. 需校验属性：账户余额
    @property
    def balance(self) -> float:
        return self._balance

    @balance.setter
    def balance(self, amount: float):
        if not isinstance(amount, (int, float)):
            raise TypeError("金额必须为数字类型")
        if amount < 0:
            raise ValueError("账户余额不能小于 0")
        self._balance = round(float(amount), 2)

    # 4. 派生只读属性：根据余额计算用户评级
    @property
    def tier(self) -> str:
        return "VIP客户" if self._balance >= 50000.0 else "普通客户"

五、常见陷阱与最佳实践

在使用 @property 时，初学者最容易踩入几个典型误区：

# 错误写法：将引发 RecursionError: maximum recursion depth exceeded
@age.setter
def age(self, value):
    self.age = value      # 错误！这会再次触发 self.age 的 setter 方法，死循环！

# 正确写法：赋值给底层的单下划线变量
@age.setter
def age(self, value):
    self._age = value     # 正确：写入底层存储，跳出拦截

六、总结

通过本文的讲解与完整示例，可以归纳出利用 Python @property 实现数据验证与只读属性的核心结论：

• 实现只读属性：仅需编写带有 @property 装饰器的 Getter 方法，省去 Setter 定义。一旦外部尝试进行赋值，Python 会抛出 AttributeError 予以拦截。适用于主键 ID、创建时间戳或动态汇总计算字段。
• 实现数据验证：成对编写 @property 和 @<name>.setter 方法，在 setter 中进行 isinstance 类型检验与业务区间核验，确保外部在享受简洁自然的 obj.attr = val 赋值语法的同时，非法参数被坚决阻断。
• 设计规范：底层实际存储使用 _attr 命名约定，在 __init__ 中统一触发 setter 赋值，保持业务模型的高内聚与健壮性。