1 / 4概念
AOP
Python 没有 AspectJ 式的编译期织入,但横切逻辑并不缺载体:装饰器包住调用,上下文管理器包住代码块,类装饰器与元类包住类创建,猴子补丁包住第三方对象。这四种包装的介入时机不同,可靠性也不同,混用之前要先分清它们各自能保证什么。
1 概念
1.1 一句话定义
在 Python 里,AOP 就是包装:函数装饰器在定义时把可调用对象替换成包装器,上下文管理器在进入与退出时执行配对逻辑,类装饰器与元类在类创建阶段修改类,猴子补丁在运行期替换属性。
1.2 它解决什么问题
- 横切逻辑集中:日志、计时、重试、缓存、鉴权不必写进每个函数体。
- 资源成对释放:文件、锁、事务、连接用
with保证退出路径唯一。 - 类级约定统一:注册、校验、字段收集在类创建时一次完成。
- 第三方行为可修正:无法改源码的库可以通过补丁适配,但必须限定作用域。
- 调用边界可观测:包装器是天然的埋点位置,能统一加 trace、指标与异常包装。
代价是调用栈变深、签名与文档容易丢失、顺序耦合隐蔽,猴子补丁还会破坏可复现性。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 函数、闭包、作用域与类型注解 | Functions and Syntax |
类、MRO、dataclass、Protocol | OOP |
| 异常传播、异常链与资源清理语义 | Error |
| 协程、任务与异步上下文管理器 | Async |
| 线程锁与并发安全 | Concurrency |
| 对象生命周期与引用计数 | Type |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| decorator | 接收可调用对象并返回包装的可调用对象 | 在定义时执行,不是调用时 |
| 高阶函数 | 参数或返回值是函数的函数 | 装饰器只是它的一种用法 |
| 闭包 | 捕获外层变量的函数 | 循环变量按名字延迟绑定 |
functools.wraps | 把原函数的元数据复制到包装器 | 不改变包装器的实际签名 |
__wrapped__ | 指向被包装函数的引用 | inspect.signature 默认沿它回溯 |
| context manager | 实现 __enter__ / __exit__ 的对象 | 不保证事务语义 |
__exit__ 返回值 | 真值表示吞掉异常 | 返回 None 才是传播 |
| class decorator | 接收类并返回类的可调用对象 | 在类创建完成后执行 |
| metaclass | 创建类的类 | 不是基类,冲突时直接报错 |
| monkey patch | 运行期替换模块或类的属性 | 对已 from 导入的名字无效 |
2 机制
2.1 心智模型
把包装想成洋葱:越靠内层的装饰器越先接触原函数,越靠外层的越先接触调用方。@a 在 @b 之上写作两行,等价于 f = a(b(f)),于是调用时先进入 a,再进入 b,最后才是原函数;返回时顺序相反。
上下文管理器是另一种洋葱:with 按从左到右进入、从右到左退出,__exit__ 能看到块内抛出的异常,返回值决定异常是否继续传播。元类则不在调用路径上,它只在 class 语句执行的那一刻介入一次。
2.2 机制拆解
- 装饰器的时机:
@dec是f = dec(f)的语法糖,在def执行完、名字绑定之前完成替换,因此装饰器代码在导入期运行。带参数的装饰器先求值工厂dec(arg),再用返回的装饰器包装函数;工厂只调用一次。 - 叠加顺序:多个装饰器从下往上应用,运行时从外到内进入。顺序改变语义:
@cache在@retry外层时,一次调用只查一次缓存,重试不会命中缓存;@retry在外、@cache在内时,每次重试都先查缓存,上一次的成功结果可以被复用。 functools.wraps:把__module__、__name__、__qualname__、__annotations__、__doc__复制到包装器,更新__dict__,并设置__wrapped__;3.12 起还把__type_params__纳入。inspect.signature默认沿__wrapped__回溯,所以 FastAPI、pytest 这类依赖签名的框架才能正确识别参数。- 闭包陷阱:包装器捕获的是变量名而不是值,循环里创建的多个包装器会共享最后一个值;用默认参数或
functools.partial在创建时固定。 - 上下文管理器:
with先调用__enter__,把返回值绑定给as目标;块正常结束或抛异常都会调用__exit__(exc_type, exc, tb)。__exit__返回真值会吞掉异常,返回None或False则继续传播。contextlib.contextmanager把生成器变成上下文管理器:yield之前是进入,之后是退出,块内异常会在yield处抛回生成器。 - 类装饰器与元类:类装饰器在类创建后运行,适合注册、替换方法、附加属性;
__init_subclass__在子类创建时由父类感知,比元类简单;元类通过__prepare__、__new__、__init__介入命名空间与类对象构造,多个基类元类不兼容时抛metaclass conflict。 - 猴子补丁:直接给模块或类赋新属性即可生效,但只影响通过该对象查找的调用;
from mod import f已在本地绑定旧对象,补丁无效。正确做法是用unittest.mock.patch限定作用域并在退出时恢复,或包装成新函数而不是替换原函数。 - 异步与描述符:包装协程必须写成
async def并在内部await,否则返回的是协程对象而不是结果;property、classmethod、cached_property本身是描述符,叠加普通装饰器时要考虑返回对象是否仍是描述符。
2.3 完整枚举
| 手段 | 语法 | 介入时机 | 作用域 | 主要代价 |
|---|---|---|---|---|
| 函数装饰器 | @dec | 定义时 | 单个可调用对象 | 每次调用多一层帧 |
| 参数化装饰器 | @dec(arg) | 定义时(工厂先执行) | 单个可调用对象 | 多一层闭包 |
| 类装饰器 | @dec 用于 class | 类创建后 | 整个类 | 可读性下降 |
| 上下文管理器类 | with obj | 进入 / 退出代码块 | 代码块 | 需实现两个方法 |
| 生成器上下文管理器 | @contextmanager | 进入 / 退出代码块 | 代码块 | 生成器帧开销 |
| 异步上下文管理器 | async with | 进入 / 退出协程块 | 协程块 | 需要 __aenter__ |
| 元类 | class C(metaclass=M) | 类创建时 | 类及其子类 | 复杂度高、易冲突 |
__init_subclass__ | 父类方法 | 子类创建时 | 子类 | 只能在父类侧定义 |
| 猴子补丁 | 直接赋值 | 运行期任意时刻 | 进程内全局 | 破坏可复现性 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 装饰器单次调用开销 | 60–150 ns | 相当于多一次 Python 函数调用 |
| 生成器上下文管理器 | 约 1 µs | 比类实现的 with 慢数倍 |
类实现的 with 开销 | 约 0.3 µs | 两次方法调用加异常处理 |
lru_cache 命中 | 约 100 ns | 命中路径在 C 层完成 |
wraps 复制字段 | 5–6 个 | 外加 __dict__ 与 __wrapped__ |
inspect.signature | 约 10 µs | 解析签名,不适合热路径 |
| 装饰器执行次数 | 每个定义一次 | 导入期完成,不影响每次调用 |
| 元类介入次数 | 每个类一次 | 类创建时执行 |
3 实践
3.1 最小示例
import functools
import time
from contextlib import contextmanager
def retry(times=3):
def decorate(fn):
@functools.wraps(fn)
def wrapper(*args, **kwargs):
last = None
for attempt in range(1, times + 1):
try:
return fn(*args, **kwargs)
except RuntimeError as exc:
last = exc
print(f"retry {attempt}/{times} after {exc}")
raise last
return wrapper
return decorate
@contextmanager
def timed(label):
start = time.perf_counter()
try:
yield label
finally:
print(f"{label}: {time.perf_counter() - start:.4f}s")
calls = 0
@retry(3)
@timed("work")
def work(n):
"""docstring 会被 wraps 保留。"""
global calls
calls += 1
if calls < 2:
raise RuntimeError("flaky")
return n * 2
print(work(21), work.__name__, work.__doc__)
@retry(3) 在 @timed 外层,所以每次重试都会重新计时并重新进入上下文;交换两行则计时只进入一次,覆盖整个重试序列。wraps 让 __name__ 仍是 work,没有它这里会打印 wrapper。
3.2 常用操作与参数
| 操作 | 调用 | 说明 |
|---|---|---|
| 保留元数据 | functools.wraps(fn) | 装饰器必备 |
| 查原函数 | wrapper.__wrapped__ | 追到被包装对象 |
| 看签名 | inspect.signature(fn) | 默认沿 __wrapped__ 回溯 |
| 缓存 | functools.lru_cache(maxsize=128) | 参数必须可哈希 |
| 生成器上下文 | contextlib.contextmanager | yield 前后即进入退出 |
| 动态组合上下文 | contextlib.ExitStack | 后进先出,异常安全 |
| 忽略指定异常 | contextlib.suppress(OSError) | 比裸 except 精确 |
| 临时补丁 | unittest.mock.patch | 退出时自动恢复 |
3.3 标准流程
- 先确认横切逻辑的边界:只读观测(日志、指标)可以包在最外层,涉及语义的(重试、缓存、事务)必须明确顺序。
- 选择载体:单次调用用函数装饰器,代码块用上下文管理器,类级约定用
__init_subclass__,元类留到最后。 - 实现时加
functools.wraps,显式列出*args, **kwargs,并在finally或__exit__里做清理。 - 用测试固定顺序与异常语义:断言调用次数、异常类型、资源是否释放,以及签名是否保留。
- 猴子补丁只在测试或适配层使用,并限定作用域;生产代码优先包装或 fork。
3.4 与相邻技术的组合
- Web 框架:FastAPI 的
Depends与中间件分别承担参数级与请求级横切;Django 的中间件顺序敏感,与装饰器叠加时要一起验证。 - 测试:pytest fixture 是上下文管理器的声明式版本;
monkeypatchfixture 自动恢复,比手写补丁安全。 - 可观测性:OpenTelemetry 的 span 用装饰器或上下文管理器注入,注意别把采样逻辑叠加在重试外层,否则一次重试会产生多条 span。
- 重试库:tenacity 用装饰器组合等待、停止与重试条件,语义比手写循环清晰,但仍需保证被重试操作幂等。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 作用范围 | 单次调用 / 代码块 / 整个类 | 决定用装饰器、上下文管理器还是元类 |
| 是否改语义 | 只观测 / 改行为 | 改语义时要显式顺序与测试 |
| 异步支持 | 同步 / 异步 | 异步必须用 async def 包装 |
| 可逆性 | 可逆 / 不可逆 | 不可逆补丁要限制在进程或测试内 |
| 性能敏感度 | 低 / 高 | 热路径避免多层包装与签名解析 |
| 团队熟悉度 | 熟悉 / 不熟悉 | 不熟悉时优先 __init_subclass__ 与显式调用 |
3.6 决策规则
- 只做观测、不改返回值:装饰器包最外层;要改返回值或异常:写清楚顺序并加测试。
- 资源必须成对释放:用
with或ExitStack,不要手写try/finally复制粘贴。 - 类级注册优先
__init_subclass__,其次类装饰器,最后才是元类。 - 异步函数必须用
async def包装;返回协程而不await是常见事故。 - 猴子补丁只用于测试或临时适配,且必须可恢复;不要补丁第三方库的内部函数。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 显式函数调用 | 无魔法、栈清晰 | 重复代码 | 调用点少、语义特殊 |
| 包装类 / 组合 | 可持有状态、易测试 | 需要转发接口 | 有状态的服务对象 |
| 上下文管理器 | 配对释放、异常安全 | 只覆盖代码块 | 资源、事务、临时状态 |
| 装饰器 | 声明式、复用成本低 | 栈变深、签名易丢 | 日志、计时、重试、缓存 |
__init_subclass__ | 简单、无需元类 | 只能由父类发起 | 子类注册与校验 |
| 猴子补丁 | 无需改源码 | 全局副作用、难复现 | 测试、临时适配 |
3.8 何时不该用
- 包装器里做阻塞 I/O 或重计算:每个调用都付代价,应该移出热路径。
- 用装饰器隐藏参数校验与业务分支:调用方看不到真实契约,测试也难以覆盖。
- 重试非幂等操作:重复执行会放大副作用。
- 用元类做业务分派或注册:
__init_subclass__或注册表足够,元类会破坏组合与继承。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 框架读不到参数名 | 未用 functools.wraps | 加 wraps,或显式改写 __signature__ |
| 重试没有生效 | 装饰器顺序反了,异常被外层吞掉 | 让重试位于最外层并验证调用次数 |
with 块里的异常消失 | __exit__ 返回了 True | 返回 None,只吞明确要吞的异常 |
| 异步函数返回协程对象 | 包装器写成同步函数 | 改成 async def 并 await |
| 补丁在别的模块不生效 | from mod import f 已绑定旧对象 | 补丁使用处,或用 patch.object |
类定义时抛 metaclass conflict | 多个基类元类不兼容 | 统一元类,或改用 __init_subclass__ |
| 生成器上下文没清理 | 生成器内缺 try/finally | yield 包在 try 里,finally 释放 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
装饰器不写 wraps | 签名、文档、调试信息丢失 | 统一加 functools.wraps |
| 用装饰器做权限校验并吞异常 | 失败被静默,越权风险 | 显式抛异常并记录 |
| 多层装饰器无注释 | 顺序靠猜,回归难查 | 在定义处标注顺序与理由 |
| 在导入期执行网络请求 | 模块导入变慢、测试难隔离 | 延迟到首次调用 |
| 全局替换第三方函数 | 进程内所有调用方受影响 | 局部包装或 patch |
4.3 可观测信号
包装问题的信号在签名与调用次数上:inspect.signature 是否与原始函数一致、__wrapped__ 是否存在、OpenAPI 文档里的参数是否完整。运行时看 trace 的层数与耗时分布,装饰器叠加会让 p99 出现固定抬升;看重试次数与缓存命中率,确认顺序符合预期;看 RuntimeWarning: coroutine was never awaited,它几乎总是异步包装写错。补丁问题看测试隔离:同一用例单独跑通过、全量跑失败,通常就是补丁泄漏。
4.4 安全 / 性能 / 一致性边界
- 执行时机边界:装饰器在导入期执行,导入即有副作用;元类与
__init_subclass__在类创建时执行一次,不会随调用重复。 - 性能边界:每层包装都增加一次函数调用与栈帧;热路径上的多层装饰器要用基准测试确认,而不是凭感觉。
- 一致性边界:上下文管理器只保证退出路径被调用,不保证事务提交成功;跨资源的原子性要交给数据库或事务管理器。
- 安全边界:猴子补丁可以替换鉴权、序列化与日志函数,等于改写安全边界;生产环境禁止在请求路径上打补丁。
- 可观测边界:包装器会改变栈帧与异常位置,排障时要先剥离包装再看真实调用点;日志里记录
__wrapped__链有助于还原。