1. 为什么我在1.24这天重新梳理装饰器

1.24这天，我没有急着学新东西，而是把琢磨了大半年的装饰器重新拉出来复盘了一遍。起因是前两天给同事review代码，看到一段@cache的用法，我随口说了一句“这装饰器就是函数外面套函数”，结果自己回家细想了一下，发现这句话其实经不起推敲——装饰器的执行时机、参数传递、元信息保留，哪一层没搞明白都会出问题。于是这天我把笔记本翻出来，从闭包开始一路整理到类装饰器，边写边把脑子里那些模糊的认知全部校正了一遍。

这篇文章就是当天笔记的整理版，照例是个人总结，有错欢迎指正。如果你也是Python开发者，对装饰器的理解停留在“会用但说不清原理”的阶段，或者写装饰器时经常被签名丢失、调用时机错乱这种问题绊住，那这篇笔记应该能帮上忙。内容不追求大而全，只讲我在1.24这天实际梳理过的概念、写过的代码、踩过的坑，尽量还原当时的思考过程。

需要提前说明的是，装饰器这个东西，本质上是“函数的函数”，它依赖Python函数式编程的两个基石：函数是一等公民、闭包能捕获外部变量。如果你对这两个概念还没啥体感，建议先跑一遍文中的示例代码再往下看。笔记里凡是标了[特殊字符]的位置，都是我当天标记的易错点，算是给自己画的注意符号。

2. 闭包与函数一等公民，是理解装饰器的地基

2.1 函数是一等公民，意味着什么

所谓一等公民，就是函数和整数、字符串、列表一样，可以赋值给变量、放进数据结构、作为参数传给另一个函数，也能作为返回值从函数里蹦出来。如果用生活化一点的类比，你可以把函数想象成一把经过标准化改装的扳手——它既可以拿在手里直接拧螺丝，也可以装进工具箱带走，还能交给另一个人让他来拧。

def greet(name): return f"Hello, {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作用域里的x=5，所以在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.wraps：

import 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(times=3) def say_hi(): print("hi") say_hi()

怎么理解这三次嵌套？我给自己的记忆口诀是：

• 最外层repeat(times=3)返回的是真正的装饰器decorator
• decorator接收到的是被装饰的函数func
• wrapper才是最终替代原函数的新函数

所以带参装饰器的调用链可以等价为：say_hi = repeat(times=3)(say_hi)。如果你以前一直记不住三层结构，建议把这句话抄下来贴在显示器旁边。我在1.24当天还专门做了一下等价展开的练习：

temp_decorator = repeat(times=3) # 返回 decorator say_hi = temp_decorator(say_hi) # 返回 wrapper

这个展开练习对我帮助很大。事实上，很多看起来高深的三层嵌套装饰器，拆开看无非就是“分步传参”这一件事。

3.4 类装饰器：用__call__替代闭包

函数装饰器写多了，你会发现有些状态用闭包持有其实略别扭——比如计数器、缓存表这种带内部状态的东西，用类的实例变量更自然。Python允许类对象被直接调用，只要定义了__call__方法，所以在类装饰器里，__init__接收原函数，__call__充当wrapper：

import 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行，毫不犹豫重构为类或独立工具函数。

最后再分享一个小技巧：如果你要排查一个复杂的多层装饰器问题，与其一层层读代码，不如写一个只打印函数名和参数的“探针装饰器”，临时挂在最外层和最内层，跑一次业务用例，立刻就能看出调用链的先后次序和参数流转情况。实测下来，排查速度比凭直觉猜要快得多。