@property装饰器核心是将方法伪装为属性以控制访问逻辑，而非 merely 实现getter/setter；它支持校验、缓存等副作用，保持obj.x语法透明，避免破坏封装性与工具兼容性。
property 装饰器不是为了“实现 getter/setter”而存在，而是为了把方法伪装成属性——关键在控制访问逻辑，而非语法糖。
为什么直接用 @property 比写 get_x/set_x 更合理
当你需要对属性读写做校验、缓存、日志或触发副作用时，@property 让调用方无感地保持 obj.x 语法，避免暴露实现细节。硬写 get_x() 和 set_x(value) 会破坏封装性，且无法被数据类（@dataclass）或序列化工具（如 pydantic）自动识别。
- 只加
@property：只读属性（无setter时赋值会抛AttributeError） - 必须配对使用
@xxx.setter：否则obj.xxx = v会失败 - 不能只写
@xxx.setter不写@property：Python 会报AttributeError: can't set attribute
@property 和 @xxx.setter 必须同名，且 setter 方法名必须与 property 名一致
常见错误是 setter 方法名拼错或加了下划线前缀，比如：
class Person:
def __init__(self, name):
self._name = name
<pre class='brush:python;toolbar:false;'>@property
def name(self):
return self._name
@name.setter # ✅ 正确：必须是 @name.setter
def name(self, value): # ✅ 方法名也必须叫 name
if not isinstance(value, str):
raise TypeError("name must be str")
self._name = value❌ 错误示例：
@name.setter → 写成 @full_name.setter 或 @_name.setter 都会失效
def full_name(self, value): → 方法名不匹配，赋值时静默失败或报错
带验证的 setter 容易忽略的边界：None、空字符串、类型隐式转换
很多业务场景要求非空字符串、正整数等，但用户可能传 None 或空串，而 Python 默认不会拦截：
立即学习“Python免费学习笔记（深入）”；
-
obj.age = None在没检查时会直接赋给私有变量，后续可能引发TypeError在别处爆发 -
obj.price = "19.99"如果期望float，需主动转换或拒绝字符串 - 建议在 setter 中显式判断：
if value is None:、if not value.strip():、if not isinstance(value, (int, float)): - 避免在 setter 里做耗时操作（如网络请求、文件读取），会影响属性赋值性能
property 不适合替代真正的私有字段或复杂状态管理
当逻辑涉及多个字段联动、异步更新、或需要缓存失效控制时，@property 很快会变得难维护：
- 比如
@property返回一个计算结果，但依赖 5 个其他属性 —— 每次访问都重新算，没缓存就慢 - 想支持
del obj.cached_result？得额外写@xxx.deleter，但实际极少用 - 更重的状态逻辑建议抽成独立方法（如
obj.refresh_cache()），而不是塞进 property - 如果字段需要序列化（JSON / ORM 映射），property 默认不被包含，需手动处理
真正麻烦的从来不是怎么写 @property，而是什么时候不该用它——比如该用 __setattr__ 拦截所有属性、该用描述符复用逻辑、或者该交给 pydantic 的 Field(validator=...) 处理。
