Python封装基础：用下划线约定和property管理属性访问

一、Python 封装哲学的根本差异：为什么没有 private 关键字？

在 Java、C++ 或 C# 中，定义一个实体类时，传统规范往往要求程序员将所有成员变量声明为 private，并立即为每个变量手写一对 getX() 和 setX() 模板方法。这种做法的初衷是防御性编程：防止未来出现校验需求时，直接修改属性访问语法会破坏调用方的既有代码。

然而在 Python 中，盲目套用这种模板化做法会被视为一种反模式（Anti-Pattern）。Python 在语言设计之初就确立了两条基本准则：

• 尊重程序员的自主性（Consenting Adults）：Python 不在运行时构建不可逾越的物理安全墙来禁止访问类成员，而是依赖明确的社区命名共识来区分“公开契约”与“内部实现细节”。
• 统一访问原则（Uniform Access Principle）：通过内置的描述符机制（Descriptor），Python 允许后续随时把一个普通的公开属性改造为带有校验逻辑的计算属性，而调用方依旧使用纯净的 obj.attr 语法，无需改写为方法调用括号 obj.get_attr()。

理解这一理念后，我们便能看清 Python 管理属性的两大支柱：第一层是下划线命名规范，用于在代码结构上标明访问边界；第二层则是 @property 装饰器，用于在逻辑上无缝截获属性的读取、设置与删除。

二、下划线命名约定：无下划线、单下划线与双下划线

Python 解释器与标准库约定了三种不同层级的属性命名风格。正确理解它们的含义与底层机制，是编写健壮类的第一步。

1. 公开属性（无前导下划线，如 name）

默认情况下，在实例方法中通过 self.name = name 创建的属性都是完全公开的。它们直接存储在实例对象的 __dict__ 字典中。外部代码可以随意进行读取和修改。

class User:
    def __init__(self, name):
        self.name = name  # 公开属性，接口稳定

user = User("Alice")
print(user.name)       # 输出: Alice
user.name = "Bob"      # 自由写入

如果一个属性既不需要额外的赋值校验，也没有衍生计算需求，那么直接定义为公开属性就是最简洁、运行开销最低的做法。

2. 单前导下划线（Protected 约定，如 _name）

在属性名前添加一个下划线 self._name，是 Python 社区通用的保护性约定。它向阅读代码的维护者和调用者发出明确信号：“这是一个内部实现细节或受保护字段，请不要在类外部直接读写它”。

必须注意：单下划线仅属于道德约束与工具提示。Python 解释器在运行时不会阻止调用方直接访问 user._name。然而现代 IDE（如 PyCharm、VS Code）会在外部访问带下划线属性时给出警告，同时模块级别的 from module import * 也会自动忽略单下划线开头的对象。

3. 双前导下划线（名称改写机制 Name Mangling，如 __name）

当属性名以至少两个前导下划线开头且至多以一个下划线结尾（如 self.__balance）时，Python 解释器会介入并触发名称改写（Name Mangling）机制。

解释器会在编译阶段自动将标识符改写为 _类名__属性名（例如 _BankAccount__balance）。如果外部代码依然尝试使用 account.__balance，解释器会直接抛出 AttributeError。

class BankAccount:
    def __init__(self, balance):
        self.__balance = balance  # 触发名称改写

acc = BankAccount(1000)
try:
    print(acc.__balance)
except AttributeError as e:
    print("直接访问失败:", e)  # 输出: 'BankAccount' object has no attribute '__balance'

# 实际上底层通过改写后的名称依然可以访问:
print(acc._BankAccount__balance)  # 输出: 1000

三、用 @property 管理属性访问：平滑演进四步法

在业务迭代过程中，最常见的诉求是：原本设计为直接公开读写的字段，随着业务复杂度增加，必须引入合法性校验（例如价格不能为负数，银行转账必须保证余额充足）。

如果使用传统的 set_price(value) 方法，所有已经部署上线的外部调用方都必须配合修改调用方式，带来沉重的兼容包袱。利用 @property，我们可以在完全保留属性访问外观的同时，在内部自由插入拦截校验。

完整演进示例：商品价格管控

以下是重构前后的对比演示。我们首先定义一个初始版本的 Product 类：

# 重构前：直接公开属性，缺乏防御机制
class Product:
    def __init__(self, name, price):
        self.name = name
        self.price = price

p = Product("机械键盘", 299)
p.price = -50  # 无法防范逻辑脏数据，价格变成了负数！

接下来，我们使用 @property 和对应 setter 进行升级。请注意重构过程的核心要点：

1. 将实例底层的真实存储属性更名为单下划线的内部变量 self._price。
2. 定义与外部属性同名的方法 def price(self)，并加上 @property 装饰器，作为 Getter（取值器）。
3. 定义同名方法 def price(self, value)，并加上 @price.setter 装饰器，在其中编写校验逻辑，最后赋值给 self._price，作为 Setter（设值器）。
4. 在 __init__ 中直接调用 self.price = price，从而使初始化也同样享受校验逻辑的保护。

# 重构后：利用 @property 注入校验逻辑
class Product:
    def __init__(self, name, price):
        self.name = name
        # 赋值操作会触发 @price.setter 校验
        self.price = price

    @property
    def price(self):
        # 取值处理：返回底层保护的实际值
        return self._price

    @price.setter
    def price(self, value):
        # 设值处理：执行严格的类型与数值范围校验
        if not isinstance(value, (int, float)):
            raise TypeError("价格必须为数值类型")
        if value < 0:
            raise ValueError("商品价格不能为负数")
        self._price = round(float(value), 2)

# --- 外部使用效果验证 ---
item = Product("电竞鼠标", 129.5)

# 1. 正常读取与修改：语法与原先的普通属性完全一致
print(item.price)      # 触发 getter -> 129.5
item.price = 159       # 触发 setter -> 成功更新
print(item.price)      # 159.0

# 2. 异常值校验拦截示例
try:
    item.price = -20
except ValueError as err:
    print("非法赋值被成功拦截:", err)  # 输出: 非法赋值被成功拦截: 商品价格不能为负数

try:
    item.price = "免费"
except TypeError as err:
    print("类型错误被成功拦截:", err)  # 输出: 类型错误被成功拦截: 价格必须为数值类型

四、深入底层：@property 的运行机制与关键防坑指南

要真正游刃有余地使用 @property，必须清楚 Python 在幕后是如何调度它的。

1. 描述符协议的工作原理

property 本质上是 Python 内置的一个描述符类（Descriptor Class）。当你在类体中编写 @property 装饰的方法时，Python 在类创建阶段会生成一个描述符对象挂载在类属性中。该对象实现了 __get__、__set__ 和 __delete__ 特殊方法：

• 当执行 item.price 时，解释器优先查找类属性中的描述符，调用 Product.price.__get__(item, Product)。
• 当执行 item.price = 200 时，调用 Product.price.__set__(item, 200)。
• 当执行 del item.price 时，调用 Product.price.__delete__(item)。若未显式定义 @price.deleter，则直接抛出 AttributeError: can't delete attribute。

2. 只读属性（Read-Only Property）与动态计算

如果我们只为某个属性定义 @property Getter，而不定义 @attr.setter，该属性就会天然变成只读属性。任何向其赋值的操作都会被解释器报错拦截。这非常适合用来表示衍生属性或计算结果：

class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height

    @property
    def area(self):
        # 动态衍生属性：根据宽高实时计算面积，不可直接赋值
        return self.width * self.height

rect = Rectangle(4, 5)
print(rect.area)  # 输出: 20

# 尝试给只读属性赋值会抛出异常：
try:
    rect.area = 30
except AttributeError as e:
    print(e)  # 输出: property 'area' of 'Rectangle' object has no setter

3. 最常见的陷阱：在 Setter 中意外造成无限递归

初学者在使用 @property 时最容易犯的错误，是在 Setter 内部给同名属性重新赋值。如下所示：

# 典型错误示例：造成无限死循环
class BadDemo:
    @property
    def value(self):
        return self._value

    @value.setter
    def value(self, val):
        # 危险！这里写成了 self.value = val，导致再次调用当前的 setter！
        self.value = val  # 循环调用自身，最终抛出 RecursionError

五、工程实践与属性设计决策指南

在实际项目架构中，究竟什么时候该用普通属性？什么时候用单下划线？什么时候需要封装为 property？我们可以依据以下决策树来快速选型。

最佳工程实践总结

• 保持极简起点：在创建新类时，大胆使用公共属性。不要为了形式上的“严谨”而提前为每个属性编写无意义的 get_x() / set_x() 方法。
• 按需重构升级：当业务规则要求“某个字段必须大于零”或“修改状态时需要同步清理缓存”时，原地将该字段改为 @property，外部调用代码零改动。
• 避免在 property 中执行高耗时 I/O：调用方使用 obj.attr 语法时，通常预期这是一个纳秒级的常数时间内存读写。如果 @property 内部包含复杂的网络请求、数据库查询或大文件读写，应当显式定义为普通方法（如 obj.fetch_user_details()），以提醒调用者关注其性能开销。