1. 为什么我在1.24这天重新梳理装饰器1.24这天我没有急着学新东西而是把琢磨了大半年的装饰器重新拉出来复盘了一遍。起因是前两天给同事review代码看到一段cache的用法我随口说了一句“这装饰器就是函数外面套函数”结果自己回家细想了一下发现这句话其实经不起推敲——装饰器的执行时机、参数传递、元信息保留哪一层没搞明白都会出问题。于是这天我把笔记本翻出来从闭包开始一路整理到类装饰器边写边把脑子里那些模糊的认知全部校正了一遍。这篇文章就是当天笔记的整理版照例是个人总结有错欢迎指正。如果你也是Python开发者对装饰器的理解停留在“会用但说不清原理”的阶段或者写装饰器时经常被签名丢失、调用时机错乱这种问题绊住那这篇笔记应该能帮上忙。内容不追求大而全只讲我在1.24这天实际梳理过的概念、写过的代码、踩过的坑尽量还原当时的思考过程。需要提前说明的是装饰器这个东西本质上是“函数的函数”它依赖Python函数式编程的两个基石函数是一等公民、闭包能捕获外部变量。如果你对这两个概念还没啥体感建议先跑一遍文中的示例代码再往下看。笔记里凡是标了[特殊字符]的位置都是我当天标记的易错点算是给自己画的注意符号。2. 闭包与函数一等公民是理解装饰器的地基2.1 函数是一等公民意味着什么所谓一等公民就是函数和整数、字符串、列表一样可以赋值给变量、放进数据结构、作为参数传给另一个函数也能作为返回值从函数里蹦出来。如果用生活化一点的类比你可以把函数想象成一把经过标准化改装的扳手——它既可以拿在手里直接拧螺丝也可以装进工具箱带走还能交给另一个人让他来拧。def greet(name): return fHello, {name} # 把函数赋值给变量 my_func greet print(my_func(alice)) # Hello, alice这看起来平平无奇但它是装饰器能成立的第一个前提。正因为函数可以当作普通对象传递我们才能把原函数“塞进”另一个函数里面由外层函数统一管理调用前后的逻辑。我在1.24之前理解的“函数外面套函数”指的就是这层关系但光知道这个还不够因为套完之后还要处理参数、返回值、元信息一堆破事。2.2 闭包让内层函数记住外部环境的变量闭包通俗点讲就是内层函数“记住”了外层函数作用域里的变量即使外层函数已经执行完这些变量依然对内存函数可见。这个特性决定了装饰器的包装函数能访问到被装饰函数本身也能访问到装饰器配置时传入的参数。def outer(x): def inner(y): return x y return inner add5 outer(5) print(add5(10)) # 15这里inner捕获了outer作用域里的x5所以在outer(5)已经返回之后add5依然是“持有5这个值”的函数。我用一个比较接地气的比喻来记住它闭包像是一个随身携带的“记忆胶囊”函数走到哪里胶囊里的数据就跟到哪里。装饰器恰恰利用了这一点——外层装饰器函数把被装饰的函数保存下来再返回一个闭包闭包内部既知道原始函数是什么也知道装饰器配置时传入的参数值。2.3 从手动包装到语法糖先别急着上符号。装饰器本质上没有任何“魔法”你完全可以用普通函数调用的方式手动包装。我当天做的第一个练习就是不用写一遍def my_decorator(func): def wrapper(*args, **kwargs): print(before) result func(*args, **kwargs) print(after) return result return wrapper def say_hello(): print(hello) say_hello my_decorator(say_hello) say_hello()看到没say_hello my_decorator(say_hello)这一行就是装饰器的真相。my_decorator只是把这个赋值操作提前到函数定义的时候由解释器自动执行。我在笔记里给自己写了一句批注装饰器不是“函数的修饰品”它就是一个高阶函数输入函数、输出函数只是让人写起来省一行的语法糖。有了这层认知后面看所有装饰器代码都不会蒙圈。注意装饰器在函数定义时就会执行即调用my_decorator(say_hello)而不是在调用被装饰函数时才执行。这个区别极容易被忽略我用[特殊字符]标在了笔记本第一页。3. 从零手写一个装饰器循序渐进3.1 第一版最简单的无参装饰器当天我的第一个目标是写一个支持任意参数、任意返回值的通用装饰器不能只适配某个固定签名的函数。很多人第一次写装饰器只处理了一个参数后面遇到需要传两个、传关键字参数时就翻车了。正确的写法是统一用*args和**kwargs接住所有参数原样转交给原函数。def logger(func): def wrapper(*args, **kwargs): print(f调用前: {func.__name__}) result func(*args, **kwargs) print(f调用后, 结果是: {result}) return result return wrapper logger def multiply(a, b): return a * b print(multiply(3, 4))运行后你会看到调用前: multiply 调用后, 结果是: 12 12这个版本已经能覆盖大多数“打日志”场景了。但当天我顺手戳了个痛点打印func.__name__是在外层wrapper中做的而func是原始函数所以名字没丢可如果你去打印multiply.__name__看到的是wrapper而不是multiply。这就是后面要解决的元信息丢失问题。3.2 进阶保留原函数元信息functools.wraps的真相丢掉__name__有什么影响最直观的是框架和调试工具会认错函数。比如你写了一个带装饰器的视图函数路由框架靠__name__来注册URL如果名字被换成wrapper路由匹配就会出问题。我1.24当天在代码里就撞见过一次排查了半天最后发现是装饰器没套wraps导致函数元信息全丢了。解决办法很简单用标准库functools.wrapsimport functools def logger(func): functools.wraps(func) def wrapper(*args, **kwargs): print(func.__name__) return func(*args, **kwargs) return wrapper这里的关键点是functools.wraps(func)本身也是一个装饰器它会把func的名字、文档字符串、注解、模块等信息拷贝到wrapper身上。本质上它是替你做了类似这样的操作wrapper.__name__ func.__name__ wrapper.__doc__ func.__doc__我在笔记里标记[特殊字符]提醒自己永远在编写装饰器时套一层functools.wraps(func)除非你刻意需要隐藏原始函数的身份那属于特殊情况。不要因为“功能没问题”就跳过这一步问题不在跑通业务逻辑这一层出在第三方工具链的兼容性上。3.3 带参数的装饰器三层嵌套怎么理解无参装饰器已经很简单了但实际项目中经常需要类似“重试3次”“缓存5秒”这种带配置的装饰器。这时候写法要从两层嵌套变成三层嵌套——外层多出来的那一层专门用来接收装饰器的配置参数。import functools def repeat(times): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): for _ in range(times): result func(*args, **kwargs) return result return wrapper return decorator repeat(times3) def say_hi(): print(hi) say_hi()怎么理解这三次嵌套我给自己的记忆口诀是最外层repeat(times3)返回的是真正的装饰器decoratordecorator接收到的是被装饰的函数funcwrapper才是最终替代原函数的新函数所以带参装饰器的调用链可以等价为say_hi repeat(times3)(say_hi)。如果你以前一直记不住三层结构建议把这句话抄下来贴在显示器旁边。我在1.24当天还专门做了一下等价展开的练习temp_decorator repeat(times3) # 返回 decorator say_hi temp_decorator(say_hi) # 返回 wrapper这个展开练习对我帮助很大。事实上很多看起来高深的三层嵌套装饰器拆开看无非就是“分步传参”这一件事。3.4 类装饰器用__call__替代闭包函数装饰器写多了你会发现有些状态用闭包持有其实略别扭——比如计数器、缓存表这种带内部状态的东西用类的实例变量更自然。Python允许类对象被直接调用只要定义了__call__方法所以在类装饰器里__init__接收原函数__call__充当wrapperimport functools class Counter: def __init__(self, func): functools.update_wrapper(self, func) self.func func self.count 0 def __call__(self, *args, **kwargs): self.count 1 print(f已调用 {self.count} 次) return self.func(*args, **kwargs) Counter def hello(): print(hello) hello() hello()输出结果会显示“已调用 1 次”“已调用 2 次”。有一点值得注意类装饰器里functools.update_wrapper(self, func)而不是functools.wraps(func)套在普通函数上两者的效果类似但作用对象不同——这里要更新的对象是类实例。我在笔记里给自己标了一个易错点[特殊字符]类装饰器实例化发生的时间点是函数定义时而不是函数调用时。也就是说Counter执行时Counter.__init__就跑了之后每次调用hello()跑的是__call__。两者的职责不能搞混。4. 装饰器叠加顺序、异步装饰器等关键细节4.1 多个装饰器叠加的执行顺序一个函数上可以挂多个装饰器这是我在项目中经常看到但总有人搞错的点。先看一段代码def decorator_a(func): print(执行 A) def wrapper(*args, **kwargs): print(调用 A wrapper) return func(*args, **kwargs) return wrapper def decorator_b(func): print(执行 B) def wrapper(*args, **kwargs): print(调用 B wrapper) return func(*args, **kwargs) return wrapper decorator_a decorator_b def demo(): print(demo)这段代码“执行”阶段的输出是执行 B 执行 A而“调用”阶段的输出是调用 A wrapper 调用 B wrapper demo为什么表现完全不同关键在于装饰器执行顺序和包装层次是两个方向装饰器从下往上执行靠近函数的先执行但调用时从上往下层层包住。用洋葱模型来记最贴切demo decorator_a(decorator_b(demo))所以调用demo()的时候先进入A的wrapper再进入B的wrapper最后才触达原始函数本体。我当天在笔记里画了一行伪代码帮助自己记忆定义时自下而上调用时自上而下。这个顺序直接影响日志输出的先后、权限校验的位置。比如你想先做登录校验再做权限判断装饰器的先后顺序就得想清楚写反了就会出现“未登录先判断权限”的尴尬情况。4.2 异步函数装饰器怎么写项目里用了async/await之后装饰器也跟着变复杂了。如果你用普通装饰器去包一个async函数返回的wrapper会是一个普通函数调用它返回的是一个coroutine对象而不是真正执行异步函数。这会导致装饰器内部的“调用前/调用后”逻辑根本不在同一个事件循环上下文中行为变得非常诡异。正确的写法是让wrapper也变成async def并在内部使用await等待原函数执行import functools import asyncio def async_logger(func): functools.wraps(func) async def wrapper(*args, **kwargs): print(async 前) result await func(*args, **kwargs) print(async 后) return result return wrapper async_logger async def fetch_data(): await asyncio.sleep(1) return data asyncio.run(fetch_data())我在1.24这天把一个紧急bug排查到凌晨最后发现就是同事在异步函数上套了同步装饰器导致前端一直等到超时。所以如果你写的项目里async场景很多务必要意识到装饰器并不是“函数通用包装器”它写出来是什么类型最终调用的就是什么类型。同步装饰器包异步函数等于把coroutine函数变成了普通函数事件循环的控制权直接错乱。4.3 内置装饰器property、staticmethod的逻辑本质很多初学者分不清property和装饰器的关系其实它就是Python内置的一个装饰器。property接收一个方法返回一个描述符对象从而让方法可以像属性一样访问。理解了这个再看staticmethod、classmethod你会发现它们的内核都是把“原函数”重新包装成了另一个可调用对象只不过包装后的行为不同。我自己在当天做的总结是内置装饰器没有什么神秘力量它们只是标准库帮我们实现好的高阶函数。如果你自己能手写一个最简单的装饰器再去读property的源码会发现底层逻辑其实高度相似——封装、拦截访问、返回新对象。读源码不一定马上能看懂但方向上不会错。5. 1.24复盘纠正几个长期存在的错误认知5.1 错误一装饰器只在函数调用时才执行这是我犯过的偏差里最隐蔽的一个。我原先以为decorator就是给函数打个标记等到调用函数时才去做包装。实际上decorator在函数定义完成的那一刻就立即执行了。特别是不带参数的装饰器它在模块导入阶段就会跑一遍外层函数体。所以如果你的装饰器外层有print或者耗时的初始化逻辑import模块时就会有输出、有开销。真实项目里要注意有些装饰器会在函数定义时注册到某个路由表、插件系统或事件系统里。也就是说只要模块被import装饰器副作用就生效了。这在Django的URL注册、Flask路由、pytest的hook里都有体现。我那天在笔记里用粗体写了一个结论装饰器的定义期执行是一把双刃剑——注册类任务靠它意外副作用也靠它。5.2 错误二以为functools.wraps只改一个__name__我之前对functools.wraps(func)的认知是“把原函数的__name__复制过来而已”。实际上它做的是__name__、__doc__、__module__、__qualname__、__annotations__并且更新__dict__。也就是说它把你手工写的那些“复制名字、复制注释”的活儿全包了连函数被装饰后仍能维持原签名显示配合inspect.signature也是它的功劳。一个很常见的场景是写了一个带文档字符串的函数装饰后查看帮助时就看不到原来的文档了这对库的作者来说尤其致命。我当天实际验证了一下def func(): 原始函数的说明 pass print(func.__doc__) # 有wraps时输出原始函数的说明没wraps时输出None以后再写通用装饰器我习惯直接一行functools.wraps(func)不纠结细节。5.3 错误三类装饰器的__init__和__call__时机混淆之前我写过一次类装饰器调试了半天才意识到问题实例化过程已经在函数定义时发生过一次之后每次调用走的是__call__。也就是说如果你把初始化逻辑写进__init__它只跑一次把每次调用前的逻辑写进__call__它跑N次。这个区分对了类装饰器的状态管理才会符合直觉。比如计数器、缓存、限流这些场景状态放在实例变量上是对的。但如果你误以为每次调用都会重新执行__init__就会写出缓存永远不生效的bug。我在当天的笔记里给这个坑专门画了一行__init__是给类开锁的房间__call__才是房间里的每一把椅子。6. 常见问题速查与调试技巧实录6.1 装饰器导致函数签名变化问题现象使用inspect.signature(函数)查看签名时看到的不是原始参数而是*args, **kwargs。很多依赖签名进行参数校验、自动生成文档的框架会受到波及。原因与处置wrapper的签名和原函数不一致虽然运行上通常没问题但会给静态分析工具带来困扰。解决办法一是使用functools.wraps它内部会更新__wrapped__属性很多库读取__wrapped__来获取真实签名二是在极端场景下保留原始函数引用不要完全透明地替换。我在当天测试中发现import inspect logger def add(a, b: int 1) - int: return a b print(inspect.signature(add)) # 是否显示(a, b: int 1) - int取决于wraps处理建议在需要序列化函数元数据的框架中配合functools.wraps一起使用或者直接使用标准库中的functools.partial等替代方案。6.2 原函数引用的丢失问题现象装饰器内部包装后原函数被变量覆盖如果你把原函数挂到某个注册表里后来想要恢复原函数做单元测试却发现找不到入口。常用方案是保留__wrapped__引用或者在使用装饰器时显式保存原函数original_func func # 在wrapper闭包里事先保存如果是第三方框架中的装饰器可以用inspect.unwrap逐层解包装拿到被包裹的原始函数对象。我通常用这个技巧追踪复杂的多层装饰器找到真正执行业务逻辑的那个函数然后定点打日志。6.3 调试建议能用现成的库就别手写如果你只是想在函数执行前后加逻辑自己手写没什么问题可一旦要处理异常重试、超时控制、属性透传手写很容易漏细节。我后来在项目里更推荐用wrapt这类库它帮你处理了签名保留、属性拷贝、甚至描述符协议的问题而且在debug时能看到更清晰的调用链。1.24当天的笔记里我给自己的行动建议是先会用标准库手写再在项目里用成熟方案——手写是为了理解原理用库是为了少踩坑。wrapt的基本用法也很简单装饰器函数接收wrapper函数实例通过wrapper.__wrapped__访问原始函数既保留了原有属性也避免了很多隐性问题。6.4 中间层状态污染的排查技巧类装饰器如果持有一个共享的可变对象作为状态比如全局列表、字典缓存一旦并发场景出现缓存数据可能会互相串扰。我踩过类似的坑装饰器里用了dict做缓存没考虑key的区分度导致两个不同用户请求拿到了对方的缓存结果。排查方法很简单——在缓存key里加入函数名、参数值、调用来源标记保证唯一性。另外如果装饰器内部定义了多层wrapper建议在每一层加一个带编号的print或日志标记跑一端小用例就能看出执行顺序是否符合预期。这种“日志标尺法”虽然朴素但比看代码猜执行顺序高效得多。我在1.24这一天最大的收获不是记住了多少装饰器的写法而是理解了它的边界装饰器擅长横切逻辑复用但滥用它会让调试变得痛苦。我现在写装饰器的习惯是先写清楚原函数再包一层薄薄的装饰器越短越好一旦逻辑超过20行毫不犹豫重构为类或独立工具函数。最后再分享一个小技巧如果你要排查一个复杂的多层装饰器问题与其一层层读代码不如写一个只打印函数名和参数的“探针装饰器”临时挂在最外层和最内层跑一次业务用例立刻就能看出调用链的先后次序和参数流转情况。实测下来排查速度比凭直觉猜要快得多。
1. 为什么我在1.24这天重新梳理装饰器1.24这天我没有急着学新东西而是把琢磨了大半年的装饰器重新拉出来复盘了一遍。起因是前两天给同事review代码看到一段cache的用法我随口说了一句“这装饰器就是函数外面套函数”结果自己回家细想了一下发现这句话其实经不起推敲——装饰器的执行时机、参数传递、元信息保留哪一层没搞明白都会出问题。于是这天我把笔记本翻出来从闭包开始一路整理到类装饰器边写边把脑子里那些模糊的认知全部校正了一遍。这篇文章就是当天笔记的整理版照例是个人总结有错欢迎指正。如果你也是Python开发者对装饰器的理解停留在“会用但说不清原理”的阶段或者写装饰器时经常被签名丢失、调用时机错乱这种问题绊住那这篇笔记应该能帮上忙。内容不追求大而全只讲我在1.24这天实际梳理过的概念、写过的代码、踩过的坑尽量还原当时的思考过程。需要提前说明的是装饰器这个东西本质上是“函数的函数”它依赖Python函数式编程的两个基石函数是一等公民、闭包能捕获外部变量。如果你对这两个概念还没啥体感建议先跑一遍文中的示例代码再往下看。笔记里凡是标了[特殊字符]的位置都是我当天标记的易错点算是给自己画的注意符号。2. 闭包与函数一等公民是理解装饰器的地基2.1 函数是一等公民意味着什么所谓一等公民就是函数和整数、字符串、列表一样可以赋值给变量、放进数据结构、作为参数传给另一个函数也能作为返回值从函数里蹦出来。如果用生活化一点的类比你可以把函数想象成一把经过标准化改装的扳手——它既可以拿在手里直接拧螺丝也可以装进工具箱带走还能交给另一个人让他来拧。def greet(name): return fHello, {name} # 把函数赋值给变量 my_func greet print(my_func(alice)) # Hello, alice这看起来平平无奇但它是装饰器能成立的第一个前提。正因为函数可以当作普通对象传递我们才能把原函数“塞进”另一个函数里面由外层函数统一管理调用前后的逻辑。我在1.24之前理解的“函数外面套函数”指的就是这层关系但光知道这个还不够因为套完之后还要处理参数、返回值、元信息一堆破事。2.2 闭包让内层函数记住外部环境的变量闭包通俗点讲就是内层函数“记住”了外层函数作用域里的变量即使外层函数已经执行完这些变量依然对内存函数可见。这个特性决定了装饰器的包装函数能访问到被装饰函数本身也能访问到装饰器配置时传入的参数。def outer(x): def inner(y): return x y return inner add5 outer(5) print(add5(10)) # 15这里inner捕获了outer作用域里的x5所以在outer(5)已经返回之后add5依然是“持有5这个值”的函数。我用一个比较接地气的比喻来记住它闭包像是一个随身携带的“记忆胶囊”函数走到哪里胶囊里的数据就跟到哪里。装饰器恰恰利用了这一点——外层装饰器函数把被装饰的函数保存下来再返回一个闭包闭包内部既知道原始函数是什么也知道装饰器配置时传入的参数值。2.3 从手动包装到语法糖先别急着上符号。装饰器本质上没有任何“魔法”你完全可以用普通函数调用的方式手动包装。我当天做的第一个练习就是不用写一遍def my_decorator(func): def wrapper(*args, **kwargs): print(before) result func(*args, **kwargs) print(after) return result return wrapper def say_hello(): print(hello) say_hello my_decorator(say_hello) say_hello()看到没say_hello my_decorator(say_hello)这一行就是装饰器的真相。my_decorator只是把这个赋值操作提前到函数定义的时候由解释器自动执行。我在笔记里给自己写了一句批注装饰器不是“函数的修饰品”它就是一个高阶函数输入函数、输出函数只是让人写起来省一行的语法糖。有了这层认知后面看所有装饰器代码都不会蒙圈。注意装饰器在函数定义时就会执行即调用my_decorator(say_hello)而不是在调用被装饰函数时才执行。这个区别极容易被忽略我用[特殊字符]标在了笔记本第一页。3. 从零手写一个装饰器循序渐进3.1 第一版最简单的无参装饰器当天我的第一个目标是写一个支持任意参数、任意返回值的通用装饰器不能只适配某个固定签名的函数。很多人第一次写装饰器只处理了一个参数后面遇到需要传两个、传关键字参数时就翻车了。正确的写法是统一用*args和**kwargs接住所有参数原样转交给原函数。def logger(func): def wrapper(*args, **kwargs): print(f调用前: {func.__name__}) result func(*args, **kwargs) print(f调用后, 结果是: {result}) return result return wrapper logger def multiply(a, b): return a * b print(multiply(3, 4))运行后你会看到调用前: multiply 调用后, 结果是: 12 12这个版本已经能覆盖大多数“打日志”场景了。但当天我顺手戳了个痛点打印func.__name__是在外层wrapper中做的而func是原始函数所以名字没丢可如果你去打印multiply.__name__看到的是wrapper而不是multiply。这就是后面要解决的元信息丢失问题。3.2 进阶保留原函数元信息functools.wraps的真相丢掉__name__有什么影响最直观的是框架和调试工具会认错函数。比如你写了一个带装饰器的视图函数路由框架靠__name__来注册URL如果名字被换成wrapper路由匹配就会出问题。我1.24当天在代码里就撞见过一次排查了半天最后发现是装饰器没套wraps导致函数元信息全丢了。解决办法很简单用标准库functools.wrapsimport functools def logger(func): functools.wraps(func) def wrapper(*args, **kwargs): print(func.__name__) return func(*args, **kwargs) return wrapper这里的关键点是functools.wraps(func)本身也是一个装饰器它会把func的名字、文档字符串、注解、模块等信息拷贝到wrapper身上。本质上它是替你做了类似这样的操作wrapper.__name__ func.__name__ wrapper.__doc__ func.__doc__我在笔记里标记[特殊字符]提醒自己永远在编写装饰器时套一层functools.wraps(func)除非你刻意需要隐藏原始函数的身份那属于特殊情况。不要因为“功能没问题”就跳过这一步问题不在跑通业务逻辑这一层出在第三方工具链的兼容性上。3.3 带参数的装饰器三层嵌套怎么理解无参装饰器已经很简单了但实际项目中经常需要类似“重试3次”“缓存5秒”这种带配置的装饰器。这时候写法要从两层嵌套变成三层嵌套——外层多出来的那一层专门用来接收装饰器的配置参数。import functools def repeat(times): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): for _ in range(times): result func(*args, **kwargs) return result return wrapper return decorator repeat(times3) def say_hi(): print(hi) say_hi()怎么理解这三次嵌套我给自己的记忆口诀是最外层repeat(times3)返回的是真正的装饰器decoratordecorator接收到的是被装饰的函数funcwrapper才是最终替代原函数的新函数所以带参装饰器的调用链可以等价为say_hi repeat(times3)(say_hi)。如果你以前一直记不住三层结构建议把这句话抄下来贴在显示器旁边。我在1.24当天还专门做了一下等价展开的练习temp_decorator repeat(times3) # 返回 decorator say_hi temp_decorator(say_hi) # 返回 wrapper这个展开练习对我帮助很大。事实上很多看起来高深的三层嵌套装饰器拆开看无非就是“分步传参”这一件事。3.4 类装饰器用__call__替代闭包函数装饰器写多了你会发现有些状态用闭包持有其实略别扭——比如计数器、缓存表这种带内部状态的东西用类的实例变量更自然。Python允许类对象被直接调用只要定义了__call__方法所以在类装饰器里__init__接收原函数__call__充当wrapperimport functools class Counter: def __init__(self, func): functools.update_wrapper(self, func) self.func func self.count 0 def __call__(self, *args, **kwargs): self.count 1 print(f已调用 {self.count} 次) return self.func(*args, **kwargs) Counter def hello(): print(hello) hello() hello()输出结果会显示“已调用 1 次”“已调用 2 次”。有一点值得注意类装饰器里functools.update_wrapper(self, func)而不是functools.wraps(func)套在普通函数上两者的效果类似但作用对象不同——这里要更新的对象是类实例。我在笔记里给自己标了一个易错点[特殊字符]类装饰器实例化发生的时间点是函数定义时而不是函数调用时。也就是说Counter执行时Counter.__init__就跑了之后每次调用hello()跑的是__call__。两者的职责不能搞混。4. 装饰器叠加顺序、异步装饰器等关键细节4.1 多个装饰器叠加的执行顺序一个函数上可以挂多个装饰器这是我在项目中经常看到但总有人搞错的点。先看一段代码def decorator_a(func): print(执行 A) def wrapper(*args, **kwargs): print(调用 A wrapper) return func(*args, **kwargs) return wrapper def decorator_b(func): print(执行 B) def wrapper(*args, **kwargs): print(调用 B wrapper) return func(*args, **kwargs) return wrapper decorator_a decorator_b def demo(): print(demo)这段代码“执行”阶段的输出是执行 B 执行 A而“调用”阶段的输出是调用 A wrapper 调用 B wrapper demo为什么表现完全不同关键在于装饰器执行顺序和包装层次是两个方向装饰器从下往上执行靠近函数的先执行但调用时从上往下层层包住。用洋葱模型来记最贴切demo decorator_a(decorator_b(demo))所以调用demo()的时候先进入A的wrapper再进入B的wrapper最后才触达原始函数本体。我当天在笔记里画了一行伪代码帮助自己记忆定义时自下而上调用时自上而下。这个顺序直接影响日志输出的先后、权限校验的位置。比如你想先做登录校验再做权限判断装饰器的先后顺序就得想清楚写反了就会出现“未登录先判断权限”的尴尬情况。4.2 异步函数装饰器怎么写项目里用了async/await之后装饰器也跟着变复杂了。如果你用普通装饰器去包一个async函数返回的wrapper会是一个普通函数调用它返回的是一个coroutine对象而不是真正执行异步函数。这会导致装饰器内部的“调用前/调用后”逻辑根本不在同一个事件循环上下文中行为变得非常诡异。正确的写法是让wrapper也变成async def并在内部使用await等待原函数执行import functools import asyncio def async_logger(func): functools.wraps(func) async def wrapper(*args, **kwargs): print(async 前) result await func(*args, **kwargs) print(async 后) return result return wrapper async_logger async def fetch_data(): await asyncio.sleep(1) return data asyncio.run(fetch_data())我在1.24这天把一个紧急bug排查到凌晨最后发现就是同事在异步函数上套了同步装饰器导致前端一直等到超时。所以如果你写的项目里async场景很多务必要意识到装饰器并不是“函数通用包装器”它写出来是什么类型最终调用的就是什么类型。同步装饰器包异步函数等于把coroutine函数变成了普通函数事件循环的控制权直接错乱。4.3 内置装饰器property、staticmethod的逻辑本质很多初学者分不清property和装饰器的关系其实它就是Python内置的一个装饰器。property接收一个方法返回一个描述符对象从而让方法可以像属性一样访问。理解了这个再看staticmethod、classmethod你会发现它们的内核都是把“原函数”重新包装成了另一个可调用对象只不过包装后的行为不同。我自己在当天做的总结是内置装饰器没有什么神秘力量它们只是标准库帮我们实现好的高阶函数。如果你自己能手写一个最简单的装饰器再去读property的源码会发现底层逻辑其实高度相似——封装、拦截访问、返回新对象。读源码不一定马上能看懂但方向上不会错。5. 1.24复盘纠正几个长期存在的错误认知5.1 错误一装饰器只在函数调用时才执行这是我犯过的偏差里最隐蔽的一个。我原先以为decorator就是给函数打个标记等到调用函数时才去做包装。实际上decorator在函数定义完成的那一刻就立即执行了。特别是不带参数的装饰器它在模块导入阶段就会跑一遍外层函数体。所以如果你的装饰器外层有print或者耗时的初始化逻辑import模块时就会有输出、有开销。真实项目里要注意有些装饰器会在函数定义时注册到某个路由表、插件系统或事件系统里。也就是说只要模块被import装饰器副作用就生效了。这在Django的URL注册、Flask路由、pytest的hook里都有体现。我那天在笔记里用粗体写了一个结论装饰器的定义期执行是一把双刃剑——注册类任务靠它意外副作用也靠它。5.2 错误二以为functools.wraps只改一个__name__我之前对functools.wraps(func)的认知是“把原函数的__name__复制过来而已”。实际上它做的是__name__、__doc__、__module__、__qualname__、__annotations__并且更新__dict__。也就是说它把你手工写的那些“复制名字、复制注释”的活儿全包了连函数被装饰后仍能维持原签名显示配合inspect.signature也是它的功劳。一个很常见的场景是写了一个带文档字符串的函数装饰后查看帮助时就看不到原来的文档了这对库的作者来说尤其致命。我当天实际验证了一下def func(): 原始函数的说明 pass print(func.__doc__) # 有wraps时输出原始函数的说明没wraps时输出None以后再写通用装饰器我习惯直接一行functools.wraps(func)不纠结细节。5.3 错误三类装饰器的__init__和__call__时机混淆之前我写过一次类装饰器调试了半天才意识到问题实例化过程已经在函数定义时发生过一次之后每次调用走的是__call__。也就是说如果你把初始化逻辑写进__init__它只跑一次把每次调用前的逻辑写进__call__它跑N次。这个区分对了类装饰器的状态管理才会符合直觉。比如计数器、缓存、限流这些场景状态放在实例变量上是对的。但如果你误以为每次调用都会重新执行__init__就会写出缓存永远不生效的bug。我在当天的笔记里给这个坑专门画了一行__init__是给类开锁的房间__call__才是房间里的每一把椅子。6. 常见问题速查与调试技巧实录6.1 装饰器导致函数签名变化问题现象使用inspect.signature(函数)查看签名时看到的不是原始参数而是*args, **kwargs。很多依赖签名进行参数校验、自动生成文档的框架会受到波及。原因与处置wrapper的签名和原函数不一致虽然运行上通常没问题但会给静态分析工具带来困扰。解决办法一是使用functools.wraps它内部会更新__wrapped__属性很多库读取__wrapped__来获取真实签名二是在极端场景下保留原始函数引用不要完全透明地替换。我在当天测试中发现import inspect logger def add(a, b: int 1) - int: return a b print(inspect.signature(add)) # 是否显示(a, b: int 1) - int取决于wraps处理建议在需要序列化函数元数据的框架中配合functools.wraps一起使用或者直接使用标准库中的functools.partial等替代方案。6.2 原函数引用的丢失问题现象装饰器内部包装后原函数被变量覆盖如果你把原函数挂到某个注册表里后来想要恢复原函数做单元测试却发现找不到入口。常用方案是保留__wrapped__引用或者在使用装饰器时显式保存原函数original_func func # 在wrapper闭包里事先保存如果是第三方框架中的装饰器可以用inspect.unwrap逐层解包装拿到被包裹的原始函数对象。我通常用这个技巧追踪复杂的多层装饰器找到真正执行业务逻辑的那个函数然后定点打日志。6.3 调试建议能用现成的库就别手写如果你只是想在函数执行前后加逻辑自己手写没什么问题可一旦要处理异常重试、超时控制、属性透传手写很容易漏细节。我后来在项目里更推荐用wrapt这类库它帮你处理了签名保留、属性拷贝、甚至描述符协议的问题而且在debug时能看到更清晰的调用链。1.24当天的笔记里我给自己的行动建议是先会用标准库手写再在项目里用成熟方案——手写是为了理解原理用库是为了少踩坑。wrapt的基本用法也很简单装饰器函数接收wrapper函数实例通过wrapper.__wrapped__访问原始函数既保留了原有属性也避免了很多隐性问题。6.4 中间层状态污染的排查技巧类装饰器如果持有一个共享的可变对象作为状态比如全局列表、字典缓存一旦并发场景出现缓存数据可能会互相串扰。我踩过类似的坑装饰器里用了dict做缓存没考虑key的区分度导致两个不同用户请求拿到了对方的缓存结果。排查方法很简单——在缓存key里加入函数名、参数值、调用来源标记保证唯一性。另外如果装饰器内部定义了多层wrapper建议在每一层加一个带编号的print或日志标记跑一端小用例就能看出执行顺序是否符合预期。这种“日志标尺法”虽然朴素但比看代码猜执行顺序高效得多。我在1.24这一天最大的收获不是记住了多少装饰器的写法而是理解了它的边界装饰器擅长横切逻辑复用但滥用它会让调试变得痛苦。我现在写装饰器的习惯是先写清楚原函数再包一层薄薄的装饰器越短越好一旦逻辑超过20行毫不犹豫重构为类或独立工具函数。最后再分享一个小技巧如果你要排查一个复杂的多层装饰器问题与其一层层读代码不如写一个只打印函数名和参数的“探针装饰器”临时挂在最外层和最内层跑一次业务用例立刻就能看出调用链的先后次序和参数流转情况。实测下来排查速度比凭直觉猜要快得多。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
