外观
12 - 加了装饰器后行为为什么变了:函数包装、调用顺序与缓存边界
摘要
给查询函数加上缓存后,租户 B 竟然得到租户 A 的结果。本文从这个教学误用解释装饰器如何替换函数、包装顺序怎样影响行为,以及缓存和重试必须满足的条件,帮助你识别看不见的调用边界。
版本范围:Python 3.14,使用标准库
functools与inspect。示例不读取真实租户数据,不包含外部网络或性能测量。独立示例已在 Windows 上使用 CPython 3.14.0 与 3.13.7 执行通过。
1. 场景:函数没有改,结果却跨了租户
日志查询程序根据当前租户与报表编号返回结果。为了减少重复查询,作者给 lookup(report_id) 加上 lru_cache。切到另一租户后,同一报表编号命中旧缓存,返回前一个租户的结果。原查询函数在没有缓存时工作正常,但缓存根据调用参数建立键,读不到隐藏在全局上下文里的差异。
教学例子不构造真实数据泄漏,而是返回 "alpha:7" 这类标记,足以证明错误复用的机制。它提醒我们:装饰器不是给函数贴上无害标签,而是在原调用路径周围增加行为,甚至替换调用对象。正确性不能只审查原函数体,还要审查包装者的输入、状态和执行顺序。
将调用画成嵌套入口:定义阶段决定名称绑定哪条包装链,调用阶段由外层决定是否进入下一层。 日志名变成 wrapper、每次监控都有记录但原函数有时没执行,都要沿这条链找到返回发生在哪一层。装饰器维护的状态与原函数隐藏状态也要分别检查。
先保持同一个查询函数和同一个键,仅交换 trace 与 cache 的嵌套。第一次调用两种顺序都计算;第二次命中时,外层 trace 仍记录,外层 cache 则直接返回。差异来自停止进入的位置,不是哪个装饰器更高级。租户例子再要求同一键是否真的代表同一业务结果。
2. 函数是对象,装饰器是接收并返回对象的调用
函数定义创建一个 function object(函数对象),把函数名绑定到它。函数对象可以传给其他函数、保存在容器里,也可以作为返回值。decorator(装饰器)利用这个能力,在定义阶段接受被装饰对象,返回接下来绑定到原名称的对象。
@trace 放在 def lookup(...): ... 前面,其关键语义相当于先创建原函数,再执行 lookup = trace(lookup)。装饰器的返回值不一定是普通函数,只要业务约定需要它可调用,就可以是支持 __call__ 的对象。若返回错误类型,定义仍可能完成,但后续调用会失败。
定义阶段与调用阶段必须分清。装饰器函数本身在函数定义执行时运行;它返回的包装函数则通常在业务调用时运行。若模块在导入时执行函数定义,装饰器配置也会在导入期间发生。这解释了为什么一个看似只加了注解式语法的改动,可以让导入过程连接外部服务或因配置缺失失败。
带参数形式 @trace(prefix="query") 多了一层:先调用工厂函数取得装饰器,再让这个装饰器接收原函数。闭包(closure,保留外部作用域引用的函数)使包装函数可以保留原函数与配置。这里的保留也是对象引用;配置中若有可变对象,后续修改可能影响包装行为,不能假设定义时自动深复制。
官方 复合语句中的函数定义规定装饰器应用顺序。本文关注可观察调用关系,不把装饰器误称为编译器生成的固定代理类型。
3. 多个装饰器的顺序如何推导
对 @outer、@inner、def target,名称最终绑定到 outer(inner(target))。应用时,内层先接收原函数;调用时,外层先接到请求,再决定是否调用内层。把这两种顺序混为一谈,就会记出互相矛盾的答案。
图表将在阅读到此处时加载…
示例把追踪放在缓存外面,所以每次调用都会进入追踪,即使命中缓存。若缓存放外面,缓存命中会跳过追踪包装,监控记录的含义就变成真实查询执行次数,而非总调用次数。两种顺序都能成立,必须与指标定义一致。
权限检查与缓存叠加时影响更大。若外层缓存可以在没有重新执行权限检查的情况下返回受保护结果,就需要证明缓存键包含完整的权限上下文,并且权限变化会正确失效。单凭“这是相同用户和参数”不够,用户角色、授权范围、数据版本都可能改变。设计时通常让鉴权在有可能直接返回数据的路径之前执行,并保持明确的数据隔离。
计时与重试也类似。计时放外层测整个操作含等待与多次尝试,放重试内部则测单次尝试。若最终日志没有说明指标语义,两个实现会产生表面矛盾的结果。先定义要观测的行为,再安排包装顺序。
4. wraps 保存元信息,不会自动保证行为等价
普通包装函数名为 wrapper,签名通常写成 *args, **kwargs。不处理元信息时,日志、文档生成和依赖注入工具看到的可能是包装者,而不是原函数。functools.wraps 根据约定复制名称、文档、注解等信息,并设置 __wrapped__ 指向被包装对象。
inspect.signature 默认会沿包装链观察原签名,因此示例里最终显示 (tenant, report_id)。但包装函数在运行时仍然执行自己的调用与参数转发,wraps 不会生成一套与原函数完全相同的参数绑定实现,也不校验包装逻辑是否遵守原返回语义。
如果包装者吞掉返回值,或把所有异常改为 None,即使元信息完整,调用契约仍然改变。正确包装通常需要透传返回值,按设计保留异常上下文,并在 finally 里完成必须执行的观测或清理。要主动转换返回类型时,应该将它视为新接口设计,而非透明增强。
官方 functools.wraps 与 update_wrapper说明了元信息处理方式。Python 版本之间复制字段可以变化,不应为了手写复制而固化一份旧版本字段列表;优先使用标准工具。
5. 最小实验:遗漏上下文与显式缓存键
运行前沿两次调用推导:bad_lookup(7) 第一次以键7保存 alpha:7,改全局租户并没有改键,第二次会在缓存层直接返回旧值。正例把 tenant 加入参数后键不同,得到 alpha:7 与 beta:7。同键两次的顺序实验再记录原函数次数一,以及追踪次数二或一;wraps 只解释元信息,不会替缓存决定正确键。
保存为 examples/12_decorators.py,运行:
powershell
python docs/python/examples/12_decorators.pypython
"""独立示例:缓存上下文遗漏与 wraps。"""
from functools import lru_cache, wraps
import inspect
current_tenant = "alpha"
@lru_cache(maxsize=16)
def bad_lookup(report_id):
return f"{current_tenant}:{report_id}"
def trace(function):
@wraps(function)
def wrapper(*args, **kwargs):
print("call:", function.__name__)
return function(*args, **kwargs)
return wrapper
@trace
@lru_cache(maxsize=16)
def lookup(tenant, report_id):
return f"{tenant}:{report_id}"
if __name__ == "__main__":
assert bad_lookup(7) == "alpha:7"
current_tenant = "beta"
print("bad:", bad_lookup(7)) # 同一个键,错误地复用 alpha 的结果。
assert bad_lookup(7) == "alpha:7"
print("good:", lookup("alpha", 7), lookup("beta", 7))
print("name:", lookup.__name__)
print("signature:", inspect.signature(lookup))
def exercise(cache_outside):
observations = {"trace": 0, "origin": 0}
def origin(key):
observations["origin"] += 1
return key * 2
def counted_trace(function):
@wraps(function)
def wrapper(*args, **kwargs):
observations["trace"] += 1
return function(*args, **kwargs)
return wrapper
if cache_outside:
wrapped = lru_cache(maxsize=4)(counted_trace(origin))
cached_function = wrapped
else:
cached_function = lru_cache(maxsize=4)(origin)
wrapped = counted_trace(cached_function)
assert wrapped(7) == wrapped(7) == 14
info = cached_function.cache_info()
assert (info.hits, info.misses, observations["origin"]) == (1, 1, 1)
return observations, info
outer_trace, trace_cache = exercise(False)
outer_cache, cache_trace = exercise(True)
assert outer_trace["trace"] == 2 and outer_cache["trace"] == 1
print("order trace/cache:", outer_trace, trace_cache)
print("order cache/trace:", outer_cache, cache_trace)
receipts = []
attempts = 0
def committed_but_response_lost():
global attempts
attempts += 1
receipts.append("receipt") # 模拟成功副作用;不是实际支付或网络调用。
if attempts == 1:
raise ConnectionError("response lost after commit")
return "ok"
for attempt in range(2):
try:
committed_but_response_lost()
break
except ConnectionError:
if attempt == 1:
raise
assert len(receipts) == 2
print("unsafe retry receipts:", len(receipts))预期反例返回 alpha:7,正例分别得到 alpha:7 与 beta:7;追踪输出两次 call: lookup,名称保持 lookup,签名包含租户和报表编号。证明的是完整参数参与缓存后两次请求不再共享同一键。若结果还取决于配置、权限版本或其他外部状态,仍需进一步建模,不能以这个正例声称已经完成真实多租户设计。
全局 current_tenant 仅用于教学复现,真实并发服务不能依靠单一全局变量保存每个请求的租户。请求局部上下文有不同的生命周期和传播方式;无论用哪种机制,缓存键都应显式覆盖影响结果的条件。隐藏状态越多,推导缓存正确性越困难。
6. 缓存的正确性与空间成本
cache(缓存)复用已计算结果,正确性前提是相同键代表在可接受时间范围内相同的结果。lru_cache 要求参数可哈希,按最近使用策略保留有限条目;maxsize=None 则不限制条目数。默认容量不能等同于内存预算:每个结果可能很大,条目计数固定仍可能占用大量内存。
缓存会保留参数和结果引用,直到条目移除或清空。装饰实例方法时,self 通常也进入键,从而可能保持实例存活。若每个短生命周期对象都调用一次被类级缓存包装的方法,就要检查这些实例何时从缓存释放。将缓存上限设得很大并不自动合理,数据价值、更新频率和对象生命周期要一起评估。
返回可变对象也是坑。某个调用方修改缓存返回的列表,后面的调用就读到修改结果。可以缓存不可变表示,或返回副本;复制的成本和嵌套对象共享又要按照第 3 篇分析。lru_cache 不会自动深拷贝参数或结果。
缓存结构的线程安全不等于同一键只计算一次。官方 lru_cache 文档说明,并发调用可能在第一项尚未填入缓存时重复执行底层函数。这对纯计算可能只是重复工作,对产生副作用的函数则可能是正确性风险。需要单次执行语义时,还要设计每键协调或业务幂等,不能用缓存装饰器代替。
时间相关数据需要明确失效策略。标准 lru_cache 主要提供容量淘汰,不提供业务 TTL(Time To Live,有效期)机制。数据库更新后缓存不一定立即变化;配置切换也不会自动清空。缓存正确性应包括版本键、更新通知、显式清除或有效期,而不仅是第一次命中实验。
7. 重试装饰器必须围绕操作语义设计
retry(重试)在失败后再次尝试同一操作,适合部分暂时性失败,但失败类型和操作状态必须可判断。读取接口的暂时连接错误与输入参数错误不是一类问题;数据库提交后响应丢失与事务完全回滚也不是一类问题。
idempotency(幂等性)指相同逻辑操作重复执行时,不额外产生不期望的效果。调用支付、创建订单或发送通知时,“没有收到成功响应”不证明“没有成功执行”。包装函数若无条件捕获所有异常并重新调用,可能制造重复数据。要通过业务操作标识、唯一约束或服务端去重建立幂等边界,再确定可重试错误。
退避、抖动、最大次数与总截止时间也属于调用契约。若每层都重试三次,层层叠加可能放大成更多底层请求;若每次等待都忽略剩余截止时间,外层超时后任务还在持续耗费资源。装饰器抽象让逻辑更方便复用,也让代价更容易隐藏,因此默认参数必须接受实际负载验证。
示例不实现通用重试工具,避免把几行循环冒充生产策略。真正落地时,应写出一次逻辑操作对应多少底层尝试、哪些失败允许再次执行、取消如何停止以及异常如何保留。这些约定比装饰器语法复杂,也更决定线上稳定性。
8. 异步与方法包装的进一步边界
用同步包装函数装饰 async def 时,直接调用原函数得到的是协程对象,不是业务结果。计时若只包住协程对象创建,就没有测量实际执行。异步包装应使用 async def 并 await 原调用,按事件循环和取消语义完成清理。不能用同步 time.sleep 实现异步重试等待。
异步函数也不应简单套标准 lru_cache 来缓存协程对象。协程对象带有执行状态,复用已执行对象不是复用业务结果。需要异步缓存时,必须明确缓存的是结果、共享任务还是失败状态,以及取消一个等待者会不会影响其他等待者。第 21 篇再展开任务与取消模型。
方法包装同样涉及描述符。普通函数包装器通常继续参与类属性绑定,因此方法调用可以正常传 self;返回自定义可调用对象时,若它没有恰当读协议,行为可能改变。把 staticmethod、classmethod 与自定义装饰器叠加前,应验证实际类型和绑定对象,而不是认为装饰器对任何位置都透明。
8.1 评审包装器时先画退出路径
一个包装函数往往有正常返回、原函数抛错、缓存直接返回与取消四条路径。日志是否每条路径都记录,资源是否每条路径都释放,异常是否仍然指向原始原因,都应逐项检查。只在返回前写清理代码,遇到异常就会跳过;只在 except Exception 中处理,则还要意识到某些控制性异常不属于这个范围。
计时包装若只在成功后写指标,会让失败请求从延迟统计中消失,得到偏乐观的结果。应该明确成功与失败是否分开记录,并将必须结束的计时放到合适的 finally 路径。记录日志自身也可能失败或耗时,需要避免辅助逻辑覆盖业务异常;这不等于应无条件吞掉所有观测错误,而是要规定可接受的降级策略。
测试包装器时,关注这些外部契约,不必断言每个内部辅助函数的调用次数。可以使用一个返回标记的函数、一个抛出预期异常的函数,以及两次相同键调用,分别观察返回透传、异常传播和缓存路径。若涉及权限与重试,再加入权限变化与已提交但响应丢失的受控替身,验证实际需要的保证。
最后检查可观察接口是否仍一致。被包装函数可能被框架用于读取签名、文档或注解,也可能被调用方保存为回调。元信息、返回类型与绑定方式改变后,错误不一定立刻在函数体出现,可能在注册或依赖解析阶段暴露。评审因此需要同时执行直接调用和实际入口调用,不能只手动调用包装器一次。
9. 进阶与面试
装饰器什么时候执行? 装饰应用在定义执行时完成;包装函数的业务逻辑通常在调用时执行。模块导入会执行定义,因此装饰器也可能影响导入阶段。
多个装饰器怎样排序? 名称绑定到外层包住内层的结果;调用先进入外层,是否继续由各层逻辑决定。通过监控与缓存例子说明“先应用”与“先调用”的区别。
wraps 能否保证参数和结果完全一致? 不能。它维护元信息和解包链,参数转发、返回透传、异常与副作用仍由包装逻辑负责。
继续研究时,可以用 __wrapped__ 检查包装链,并查看缓存的 cache_info() 判断命中与容量。不要在生产中随意绕过包装层直调原函数,那可能绕过鉴权、事务或限流;解包适合在明确边界的调试与工具环境中使用。
用命中次数与副作用检验包装顺序
从缓存短路迁移到重试重复执行
缓存命中是在某层停止进入,重试是在某层再次进入。两者都改变原函数的执行次数,却有相反方向。receipt 已追加再丢失响应时,重试重新进入会追加第二条;调用层没有收到结果,不代表副作用没发生。沿这条链迁移到事务与Deadline,必须补上实际提交与总预算状态,而不是只复制装饰器骨架。
包装顺序实验对同一个键连续调用两次,检查 cache_info() 的 hits=1、misses=1,并单独记录原函数次数为一。trace(cache(origin)) 的追踪层在缓存外,每次调用都经过它,次数二;cache(trace(origin)) 的追踪层在缓存内,命中直接返回,次数一。顺序决定记录的是请求次数还是实际计算次数,不能把两类指标混为一谈。首次出现的 cache_info 是缓存统计接口,不是证明所有键都正确的功能测试。
重试反例先追加 receipt,再模拟响应连接失败,第二次重试导致两条 receipt。它演示的是受控内存副作用,不是假称真实线上提交故障。包装层只能改变调用策略,无法自动恢复已发生的效果。生产事务必须把操作标识与业务修改放进同一一致性边界,参见事务与连接生命周期以及Deadline、幂等与并发重试。
独立能力任务:增加相同键与不同键两组调用,分别断言原函数、追踪层、命中统计;交换装饰顺序后解释指标含义如何变化。验收还要写出重试允许条件,不能把所有异常都放进无限循环。 可进一步阅读Spring切面顺序与组合语义:装饰嵌套顺序不等同容器切面排序。
10. 结尾
装饰器改变调用对象和执行路径,只有输入、顺序、状态与副作用的契约完整,复用增强逻辑才可靠。
- 区分定义时的装饰应用与调用时的包装执行,顺序由嵌套关系决定。
wraps保留元信息,缓存键必须覆盖影响结果的上下文与失效条件。- 重试、异步和方法包装需要各自的行为约定,语法简短不代表代价简单。