★ FEATURED ARTICLE 1. 从set_name说起为什么突然聊Property我先问个问题你写Python有没有经历过这种场景——早期写了一个类里面直接暴露了self.age后来业务方说年龄不能是负数于是你加上了校验逻辑但调用方已经散落在一百个地方直接赋值user.age -5。你只能去每个调用点补校验或者干脆写一个set_age()全局替换改到怀疑人生。这就是property要解决的核心问题让你在不动外部调用代码的前提下把直接属性访问升级成带逻辑的属性访问。很多人对property的理解停留在把方法当属性用再加个property装饰器就完事了。但实际项目里property真正的作用远不止这一步。它不是语法糖那么简单背后是一整套Python数据描述符机制决定了你在类里怎么设计数据接口、怎么控制修改权限、怎么做惰性求值、怎么在继承体系里安全扩展。这篇内容不打算只罗列API文档式的示例而是按照从需求到实现、从原理到实战、从该用到不该用的路径把property讲透。无论你是刚入门的Python新手还是已经在写业务代码、想重构数据层的开发者这篇都能给你一些能直接落地的思路。为什么值得认真对待property因为它是Python中少有的、能把面向对象设计落到属性访问层面的语言特性。用好了你的类可以像普通数据容器一样自然却暗藏校验、转换、派生计算等逻辑用不好就是各种隐蔽的坑赋值不触发校验、继承时setter写错方法名、property和普通属性重名导致递归爆炸。后面都会讲到。2. property的底层到底是什么描述符协议才是关键2.1 一组神奇的魔术方法要理解property就得先理解描述符descriptor协议。Python里有一组魔术方法决定了访问一个对象的属性时究竟发生了什么__get__、__set__、__delete__。任何类只要实现了这几个方法中的任何一个它的实例就可以作为另一个类的类属性并劫持对那个属性的读写操作。property本质上就是一个实现了上述协议的描述符类。你自己写的类方法之所以能像属性一样被调用是因为Python解释器在解析obj.prop时发现prop是定义在类上的一个property对象于是调用它的__get__把fget方法跑一遍把返回值给你。沿着这个思路往下推你会得到几个重要的推论property对象是存储在类的__dict__里的不是存在实例里的。因为存在类属性里所以实例访问obj.prop时走的是类属性的查找路径而不是实例的属性字典。当你在实例上执行obj.prop 某个值时真正触发的是property的__set__方法也就是你写的setter函数。用生活化的方式理解类属性相当于一栋楼的门禁系统property就是那个门卫。你想进房间读数据obj.name门卫要检查你是不是名单里的人执行fget你想往房间里放东西写数据obj.name xxx门卫要检查你带的东西合不合规执行fset。2.2 再往下挖一层__set_name__与类创建时机这里有个在写复杂property时经常踩的坑property对象是在类定义阶段创建和绑定的。Python 3.6之后描述符多了一个__set_name__(self, owner, name)方法它会在类创建时把这个描述符被赋给了哪个类的哪个名字传给你。property内部就利用了这个机制来获取属性名这也是为什么你在property的函数里能拿到self.属性名对应的那个变量。很多新手会在property的setter里写self._name value这不是巧合是约定。因为property本身占用官方接口名比如name一旦你把内部存储直接命名为self.name就会再次触发property的__set__和setter里的self.name value形成无限递归直接栈溢出。正确做法永远是内部保存用下划线前缀的私有名公开接口用property同名对象。这是Python社区里面约定俗成的规矩不是强制语法但不遵守就是踩坑。2.3 一个让你重新认识赋值的细节再补一个高级但实用的细节实例属性赋值可以覆盖描述符但property不会。这句话是什么意思如果一个类同时定义了__slots__或者带有__dict__你在实例上执行obj.xxx 1时Python会优先检查类上有没有对应的数据描述符。property属于数据描述符——因为它同时实现了__get__和__set__——所以实例上直接赋值会被拦截进入setter逻辑而不是悄悄往obj.__dict__里塞一个新属性。这一点极其重要。它意味着只要某个名字被property接管你从任何角度赋值都会走同一套校验逻辑不会出现我在外部给实例加了个新属性绕过了你的校验这种漏洞。反过来如果你的类用的是property但你没写setter那么任何外部赋值都会直接抛AttributeError。这是实现只读属性的基础后面专门聊。3. 实战第一站用Property做数据卫生检查3.1 数值校验工资不能是负数直接上业务代码。假设你正在做一个薪资系统员工类的月薪在外部被频繁读取和修改但业务规则要求不能为负数不能超过一百万一月防止异常脏数据。class Employee: def __init__(self, name: str, salary: float): self._name name self._salary salary property def salary(self) - float: return self._salary salary.setter def salary(self, value: float) - None: if not isinstance(value, (int, float)): raise TypeError(salary 必须是数值) if value 0: raise ValueError(salary 不能为负数) if value 1_000_000: raise ValueError(salary 超出合理范围) self._salary value这段代码解决的不只是校验更重要的是所有地方统一走同一个入口。哪怕有十个模块在修改emp.salary xxx每次都会经过校验。你不需要额外写任何对外接口。这就是property最基础的价值把对数据的管控收口到类内部把调用方从繁琐的检查代码里解放出来。test_caseemp Employee(张三, 12000)可以直接打印emp.salary拿值如果有人写emp.salary -1立刻抛异常错误在源头被拦截而不是等到月底算总账时才发现数据坏了。3.2 类型转换时间戳和字符串字段的边界处理第二个高频场景从数据库或第三方接口拿到的原始字段类型和业务层需要的类型不一致。过去我写过不少代码在构造函数里self.created_at datetime.fromtimestamp(raw_ts)然后在别的地方又对整个对象整体赋值。有了property这一切可以更优雅。import datetime import time class Article: def __init__(self, title: str, published_ts: float): self._title title self._published_ts published_ts property def title(self) - str: return self._title property def published_at(self) - datetime.datetime: 对外永远返回 datetime而不是裸时间戳 return datetime.datetime.fromtimestamp(self._published_ts) published_at.setter def published_at(self, value): if isinstance(value, datetime.datetime): self._published_ts value.timestamp() elif isinstance(value, (int, float)): self._published_ts float(value) else: raise TypeError(只接受 datetime 或时间戳数值)这个设计的妙处在于外部代码完全不用关心对象内部到底存的是时间戳还是datetime。读的时候统一拿datetime写的时候你传时间戳也行、传datetime也行内部自动转换。以后如果后端存储从时间戳改成ISO字符串你只需要改published_at的property实现所有调用方技术零改动。类似的还有布尔值的字符串转换前端传 true/false 字符串后端需要 bool。在property的setter里做一次归一化所有外部赋值从此不再担心脏格式。3.3 计算属性有些值不该被存起来还有一种场景也很典型一个状态是从多个字段推出来的不需要存储。比如订单类total_amount是由goods_amount和shipping_fee和discount算出来的。如果用传统思路你会在每次修改这三个字段后手动更新total少更新一次就是脏数据。class Order: def __init__(self, goods_amount0.0, shipping_fee0.0, discount0.0): self._goods_amount goods_amount self._shipping_fee shipping_fee self._discount discount property def goods_amount(self): return self._goods_amount goods_amount.setter def goods_amount(self, value): if value 0: raise ValueError(商品金额不能为负) self._goods_amount float(value) property def shipping_fee(self): return self._shipping_fee shipping_fee.setter def shipping_fee(self, value): self._shipping_fee float(value) property def discount(self): return self._discount discount.setter def discount(self, value): if not 0 value self._goods_amount: raise ValueError(折扣必须在 0 和商品金额之间) self._discount float(value) property def total_amount(self) - float: 计算属性无需存储每次实时计算 return round(self._goods_amount self._shipping_fee - self._discount, 2)这里total_amount没有setter——你不需要外部去手动设置总价它是由明细推导出来的。业务逻辑上总价是派生值这个概念通过property自然地表达出来了。对比把total做成普通属性并手动同步的做法这种方案从机制上杜绝了不同步的bug。从设计模式的角度看这种方式也更符合单一事实来源原则真实数据只有三个内部字段总价永远是它们的函数不存在第四个需要维护的副本。4. 进阶操作Property在真实项目中的进阶玩法4.1 三种写法你会用几种property有几种等价的创建方式实际工作中你会见到不同的风格。第一种装饰器写法最常见class Person: def __init__(self, name): self._name name property def name(self): return self._name name.setter def name(self, value): self._name value.strip().title()第二种直接把getter当参数传给property类class Person: def __init__(self, name): self._name name def _get_name(self): return self._name def _set_name(self, value): self._name value.strip().title() name property(_get_name, _set_name, doc人的名字)第三种通过property()构造prop对象后再调用setter方法class Person: def __init__(self, name): self._name name def _get_name(self): return self._name name property(_get_name) name.setter def name(self, value): self._name value.strip().title()三种风格各有用途。装饰器风格最美观适合绝大多数场景。第二种适合一个类的property特别多、你想让getter和setter函数集中排列在类后部的场景这样前面一眼看到的就是有哪些属性实现细节往后放。第三种则是动态扩展已有property的典型姿势尤其在给第三方类打补丁时很实用。另外要提一句property(fgetNone, fsetNone, fdelNone, docNone)这个函数的第三个参数是删除方法用来定义del obj.prop的行为。很多教科书不写它但如果你处理的是资源类对象比如缓存、socket描述符deleter能帮你合理释放资源。4.2 只读属性与假只读的真相只读属性是最容易出意外的。property不带setter外部执行obj.name x确实会抛AttributeError但这种保护只存在于实例访问层面。class Config: def __init__(self, api_key): self._api_key api_key property def api_key(self): return self._api_keycfg Config(sk-xxx)之后cfg.api_key hacked会报错这没问题。但cfg._api_key hacked依然可以——下划线不是安全边界它只是约定。所以如果你真的想要程序外部无法改动仅靠property是不够的。你需要组合使用__slots__和__setattr__或者用不可变的数据结构。但通常property的只读就够用了因为我们防的是误操作和不规范编码不是防黑客。一个更隐蔽的坑property实现只读属性后如果你在类内部的__init__里不小心写了self.api_key ...而不是self._api_key ...一样会触发setter不存在而报错。新手经常在这个地方卡半天最后发现原来是初始化时走了property。修正方案很简单内部赋值一律写私有名。4.3 惰性缓存属性把一次计算存起来有些计算耗时的property你希望第一次访问时算出来之后直接缓存结果。class DataReport: def __init__(self, raw_data): self._raw_data raw_data self._cache {} property def processed(self): if processed not in self._cache: # 模拟一个耗时计算 self._cache[processed] [x * 2 for x in self._raw_data] return self._cache[processed]或者用标准库functools.cached_property它能让你少写不少样板代码。from functools import cached_property class DataReport: def __init__(self, raw_data): self._raw_data raw_data cached_property def processed(self): # 只算一次之后读缓存 return [x * 2 for x in self._raw_data]这是property在生产环境最有价值的用法之一。注意cached_property在类定义了__slots__且不含__dict__或对象被copy时会有特殊行为需要在文档里写清楚。很多时候读取慢和写代码慢是两回事如果有人反复读取同一个昂贵的计算属性每次重新计算就是巨大的浪费。缓存住以后后续访问就是O(1)量级。4.4 继承时property的扩展getter复用setter增强继承场景是property的重灾区。很多人写完父类的property子类想加逻辑时不知道该怎么覆写。class BaseUser: def __init__(self, username, password): self._username username self._password password property def username(self): return self._username property def password(self): return ******你想在子类里给username加个前缀给password的返回规则加个脱敏处理怎么重写最直接的做法是整个property一起覆写但其实可以只覆写getter、沿用setter。property对象本身拥有getter、setter、deleter三个方法可以在继承链上逐步增加行为class AdminUser(BaseUser): property def username(self): return f[admin] {self._username} username.setter def username(self, value): self._username value这样虽然你重写了整个属性但setter逻辑如果父类有复杂的校验可以在子类setter里显式调用父类的私有setter方法没有直接暴露的话也可以调用super的逻辑。反过来如果只想复用父类的getter、重写setter直接这样class ModeratorUser(BaseUser): BaseUser.username.setter def username(self, value): value value.strip() self._username value这种写法要求父类的property已经存在并且你以属性的方式访问它然后在它上面挂setter。很多老手都不一定会这样用但你看了这段就不会在继承里无从下手了。4.5 防止外部直接改私有字段名字改写了解一下property的外部接口再完美总有人好奇地去摸obj._name。Python没有真正的私有变量但可以通过双下划线前缀触发名字改写name mangling让外部直接访问obj.__name不会成功class Protected: def __init__(self, secret): self.__secret secret property def secret(self): return self.__secret secret.setter def secret(self, value): self.__secret value当你在类内部写self.__secret时Python自动把它改名为self._Protected__secret。外部访问p.__secret会AttributeError访问p._Protected__secret依然能拿到——所以这层保护是防君子不防小人。但它的确能有效阻止意外误写而且不会和子类里同名属性撞车。讲个真实体验在大型项目中每个人写代码风格不同有的人就是控制不住手总想帮别人查_字段。名字改写能把意外访问变成明确报错反而更容易暴露问题。作为类设计者多加一层保护不是坏事。5. 什么时候不该用Property边界与陷阱5.1 业务参数变动的黑历史cache翻车property最大的坑就是把不稳定、易变的业务运算伪装成稳定的属性读取。如果你把一个每次计算逻辑都可能变的金额换算写成property下次财务要求加税点你得改setter而外部调用点根本不知道这个变化。这种频繁变动的业务逻辑更适合用显式方法比如order.calc_total()让这里有计算的意图明确暴露给调用者。我见过一次事故一个stock.quantity被做成了property背后是查询库存表的最新数量。然后某产品经理要求缓存三分钟开发就在property的getter里加了缓存。后来清库存后前端还显示旧数量排查了两小时才发现是property的缓存没失效。这种需要有时序性的操作就不该藏在property里用显式refresh_quantity()方法更利于控制。建议纯数据取值、格式转换、基于同一对象明文字段的推导适合property跨系统查询、外部IO、需要手动刷新、逻辑经常变化的计算考虑显式方法。5.2 别把方法伪装成属性尤其是有副作用的property的getter在用户看来就是一个普通属性他们不会想到读一下可能会触发网络请求、写日志、甚至修改内部状态。class User: property def is_active(self): # 反向误区这里居然触发了写操作 self._last_login datetime.now() return self._status active读一个属性结果内部状态被改了这在多线程环境里直接就是灾难。getter的职责应当是尽可能无副作用地返回数据如果需要副作用请写成显式方法。类似的不要把耗时超过几百毫秒的操作放property里。普通人读属性不会想到可以用try...except包裹更不会想到p.name居然能阻塞几秒。虽然技术上可以这么写但接口设计上这是误导。5.3 和字典、命名元组比较什么时候不该用类有时候你压根不需要写一个类更不需要property。如果你只是临时组合几个字段直接用一个dict或dataclass就够别为一个小需求包装一堆property。Python 3.7的dataclass提供了field()和__post_init__能解决90%的创建时校验和转换问题代码量更少from dataclasses import dataclass dataclass class Product: name: str price: float def __post_init__(self): if self.price 0: raise ValueError(价格不能为负)如果你的需求只是创建时确保正确dataclass足够。property更适合对象生命周期内任何时刻的赋值都要受控的场景。我看到的很多过度设计案例是把简单的dataclass硬改成了7个property一堆setter的巨型类。维护成本上去了收益却不明显。所以动手前先想清楚你到底需要的是不可破坏的约束还是一种好看的字段缩写方式5.4 property和getattr/setattr的联动风险如果你在类里还重写了__getattr__或__setattr__property和它们之间的优先级需要搞清楚。__getattr__只在正常查找失败时才调用所以property存在时它不会参与。但__setattr__就不同它在所有赋值操作前都会被调用如果你写了self._name value其实也会经过__setattr__。如果你在__setattr__里改动名字映射就可能干扰property的内部存储。常见坑class A: def __init__(self): self._x 1 def __setattr__(self, name, value): # 一个不小心就破坏了property super().__setattr__(name.lower(), value)name.lower() 把_x变成别的然后property的setter再赋值时就直接跑偏了。在项目里如果确实要重写__setattr__务必对property内部使用的私有属性名加白名单放行。6. 一组关于项目实践的高频问题6.1 在FastAPI/Django模型里怎么配合property使用如今写Python后端绕不开框架。在Django模型里property是常见的辅助字段展示手段比如# Django Model class Order(models.Model): goods_amount models.DecimalField(max_digits10, decimal_places2) shipping_fee models.DecimalField(max_digits6, decimal_places2) property def total_amount(self): return self.goods_amount self.shipping_fee注意这个property不会被Django迁移识别为数据库字段也不会被ModelForm自动处理。很多人误以为property会影响数据库结构其实完全不会它纯粹是Python层的计算。如果你要让它出现在序列化输出里DRF得在Serializer里显式ReadOnlyField。在FastAPI的Pydantic模型里如果你用了自定义的property做字段官方推荐在Config里配置orm_modeTrue或者用property配合computed_field否则被序列化时可能不生效。这块通常是新手最容易迷茫的point写完property接口返回里就是没有。6.2 生命周期管理property 上下文管理器有时一个property背后需要管理资源连接、锁、句柄这时候综合运用deleter和析构逻辑是个好方案。class ManagedConnection: def __init__(self, endpoint): self._endpoint endpoint self._conn None property def connection(self): if self._conn is None: self._conn self._open() return self._conn connection.deleter def connection(self): if self._conn: self._conn.close() self._conn None然后外部代码conn obj.connection用完del obj.connection逻辑清晰。这种模式适合连接池里每个对象打包少量资源管理的场景。当然如果只是要用完记得释放直接用with obj.connection as conn:会更符合直觉——但那个时候你其实需要的是一个实现了__enter__/__exit__的上下文管理器property只是返回这样一个对象而已。6.3 property和slots配合省内存但别乱配如果类定义使用__slots__意味着实例不能有__dict__。这会带来两个影响property的__set__在赋值时会直接调用settersetter内部self._attr value如果_attr没在__slots__里列出来就会报错。functools.cached_property依赖写入实例__dict__所以和__slots__配合时不生效会报AttributeError: X object has no attribute __dict__。实战中__slots__ property是一对好搭档省内存且能控制访问但你要在slots里把内部私有属性名列全。忘记列全代码一运行就崩排查起来还很懵——因为报错信息不会直接告诉你slots没写全。一个我认为值得推荐的组合方案除了公开属性property同名之外把私有存储属性全部列进__slots__公开属性本身不要加进__slots__因为它只是类属性不属于实例存储。如果搞混了调试时会很痛苦。7. 三种典型的坏味道自查清单写了不少正向示例再从反面给三个自查标准你看看自己项目里有没有类似问题。第一为什么不把所有字段都做成property如果所有字段都被一股脑地加了getter/setter但是setter里只写self._x value没有任何校验和转换——这是典型过度设计直接去掉property用普通属性或者dataclass更清爽。property的意义是介入没有逻辑的介入就是纯装饰。第二property的getter里有没有磨人的隐藏逻辑如果访问一个属性会打开数据库连接、调用外部HTTP、sleep几毫秒这个设计就在误导调用方。你会发现排查性能问题时一行print(user.name)竟然花了200ms全是因为property内部跑了查询。可读性很差。请把IO和网络调用放到显式方法里。第三继承体系里是否保留了父类property的约束子类如果只重写了getter忘了setter或者重写整个property时丢了校验那原本所有赋值都必须通过校验的承诺就破了。我在review代码时经常看到子类里一个无脑setter绕过父类校验的情况。解决方案是尽量只在父类写核心校验逻辑子类通过super().xxx复用而不是推倒重来。这三个坏味道如果都避开了你的property使用基本就合格了。它不再是一个花哨语法而是数据建模时的一个趁手工具。8. 最后分享一个我实际项目里的重构案例这段经历可能对你更有参考价值。之前维护过一个旧的库存服务Inventory类有quantity、reserved、available三个公开字段。业务方要求任何修改quantity或reserved的地方都必须同步保证available quantity - reserved不小于0。原代码在每个调用点手动计算改到后面漏了一处导致线上出现负库存。我的重构方案就是property化三个字段class Inventory: def __init__(self, quantity0, reserved0): self._quantity quantity self._reserved reserved property def quantity(self): return self._quantity quantity.setter def quantity(self, value): if value 0: raise ValueError(库存数量不能为负) if value self._reserved: raise ValueError(不能把可用库存调整到已预定量以下) self._quantity value property def reserved(self): return self._reserved reserved.setter def reserved(self, value): if value 0: raise ValueError(预定量不能为负) if value self._quantity: raise ValueError(预定量不能超过库存总量) self._reserved value property def available(self): return self._quantity - self._reserved重构后所有调用点代码一行没改原本inv.quantity 50照常工作但非法状态在源头就被拦截了。线上再也没出现过负库存的脏数据。这个case里property的核心价值不是少写几个方法而是把数据一致性规则内聚到数据模型本身不让它在各处散落。如果你在维护一个老项目这种把裸字段逐步收口为property的渐进式重构比一次性大改安全得多。你不需要让调用方感知变化却能逐渐把校验补上、把派生计算收拢这才是property在工程里最厉害的地方。
阅读完成 · 觉得有帮助？
