Python 装饰器:我以为的语法糖,其实是定义时立刻执行的函数调用
这个坑我是被项目逼着学会的。
有一次产品要求给所有接口加耗时统计,我打开函数,开头写一行 start_time = time.time(),return 前再写一行 print。改到第三个函数时我开始怀疑人生——同样的代码复制粘贴几十遍,以后改格式还得逐个文件翻。于是搜索"Python 不修改函数添加日志",所有答案都指向同一个词:装饰器。
但学装饰器的过程比改代码还痛苦。教程上来就甩一个 @xxx,看不懂为什么 @ 后面跟函数名、为什么有的装饰器带括号有的不带、为什么 wrapper 里要写 *args, **kwargs、为什么还要 import 一个叫 wraps 的东西。我一度把它当成需要背下来的语法咒语。
直到后来才明白:装饰器没有任何魔法,它只是一个普通的函数调用,@ 只是 Python 官方提供的一个缩写。 把这层窗户纸捅破,所有"为什么"就都有了答案。这篇笔记就是从头捅到底。
一、先补两块地基:函数是对象,闭包是记忆
装饰器踩坑的根源,是很多人跳过了两个基础概念直接学语法。快速补齐。
第一块:函数是对象。 Python 里函数和字符串、整数一样,是普通值——可以赋给变量、装进列表、当参数传给另一个函数、当返回值返回:
def hello(name):
return f"Hello, {name}"
greet = hello # 函数赋给变量,注意没有括号——不是调用,是传递
funcs = [hello, greet] # 装进列表
print(funcs[0]("Bob")) # Hello, Bob
def call_it(func, arg): # 函数当参数
return func(arg)
print(call_it(hello, "Carol"))
hello 和 hello() 的区别是理解一切后续内容的钥匙:前者是"函数对象本身",后者是"执行它并取结果"。
第二块:闭包。 函数里定义函数,内层函数能访问外层函数的变量——而且即使外层函数已经 return 了,这个"记忆"依然保留:
def outer(x):
def inner(y):
return x + y # inner 记住了 x
return inner
add5 = outer(5) # outer 执行完毕、已经返回
print(add5(10)) # 15 —— x=5 还活着
可以把闭包理解成:函数对象随身带一个小背包,里面装着它定义时所在作用域的变量引用。这个小背包正是装饰器能"记住"原函数的根本。
两块地基铺好,装饰器只剩一件事要做:把函数传进函数、包装、返回。
二、撕开 @:它就是一行赋值语句
先完全不用语法糖,手写一个"包装":
def add_log(func):
def wrapper():
print("函数执行前")
func()
print("函数执行后")
return wrapper
def say_hello():
print("Hello!")
# 手动包装:传进去,拿回新的,替换原名
say_hello = add_log(say_hello)
say_hello()
# 输出:函数执行前 / Hello! / 函数执行后
看最后那行赋值:say_hello = add_log(say_hello)。这个动作就是装饰器的全部——把原函数传给包装函数,返回增强版,用原名指回它。
而 Python 觉得这行赋值写起来啰嗦,就发明了 @ 缩写:
@add_log
def say_hello():
print("Hello!")
这两段代码在 Python 解释器眼里一模一样。 遇到 @add_log,解释器的翻译动作就是执行 say_hello = add_log(say_hello)。
这是全文最重要的一句话,值得单独放大:
@不是"注解"或"标记",它是一条在函数定义完成的瞬间立刻执行的语句。 带括号就立即执行——这是函数调用的基本规则,@不会豁免它。
这个认知直接解释了新手最容易栽的坑,第五节会回来收割。
三、造一个万能模板:*args、**kwargs 和 @wraps
上一节的 wrapper() 只能包装无参数无返回值的函数——真实代码几乎不存在这种函数。需要两个补丁,补完就是一个可以无脑复用的模板。
补丁一:适配任意签名。 让 wrapper 接收任意位置参数和关键字参数,原封不动转发给原函数:
def wrapper(*args, **kwargs):
result = func(*args, **kwargs) # 转发,并接住返回值
return result
补丁二:治"身份失忆症"。 包装之后 say_hello 这个名字指向的其实是 wrapper——于是 say_hello.__name__ 变成了 'wrapper',文档字符串也丢了。这会破坏调试信息,更严重的是让依赖函数名做路由注册的框架(Flask、FastAPI)直接失效。
解药是标准库的 functools.wraps,它把原函数的元数据(__name__、__doc__ 等)拷贝给 wrapper:
from functools import wraps
def add_log(func):
@wraps(func) # 一行,身份找回
def wrapper(*args, **kwargs):
print(f"调用 {func.__name__}")
result = func(*args, **kwargs)
print(f"{func.__name__} 返回 {result!r}")
return result
return wrapper
两块补丁打完,这就是通用装饰器的标准模板——计时、重试、缓存、权限校验,全都长这个骨架。
四、带参数的装饰器:为什么要套三层
下一个拦路虎是这种写法:
@repeat(num_times=3)
def greet(name):
print(f"Hello, {name}!")
@repeat 后面怎么带括号了?之前的 @add_log 不带啊?
回到那个核心认知:@ 后面跟的是一个"会返回装饰器的调用"。拆解执行过程:
@repeat(num_times=3)
def greet(name): ...
等价于:
greet = repeat(num_times=3)(greet)
从里往外读:先执行 repeat(num_times=3),它返回一个装饰器;这个装饰器再吃掉 greet,返回 wrapper。所以 repeat 的结构必须是三层嵌套:
def repeat(num_times): # 第一层:装饰器工厂,吃配置
def decorator(func): # 第二层:真正的装饰器,吃函数
@wraps(func)
def wrapper(*args, **kwargs): # 第三层:干活的人
for _ in range(num_times):
result = func(*args, **kwargs)
return result
return wrapper
return decorator
为什么必然三层?因为配置和函数是两次分开的投喂:num_times 在 @repeat(num_times=3) 时进来,func 在函数定义完成时才进来。两次投喂,需要两层函数分别接住,加上最里面干活的 wrapper,正好三层。这不是设计炫技,是逻辑推论——想通了这一点,"带参装饰器要套三层"就从需要背的规则变成了显然的事实。
顺带补一条堆叠规则:多个装饰器从下往上应用,等价于从上往下嵌套包裹:
@a
@b
def f(): ...
# 等价于 f = a(b(f))
五、三大踩坑实录
学完结构,该收割第二节埋下的那个认知了。三个坑都源于对"@ 是语句"理解不彻底。
坑一:装饰器在导入时就"偷跑"(杀伤力最大)
我在生产环境栽过的具体场景:为了发监控日志,装饰器里初始化了一个数据库连接池。结果容器启动后 K8s 健康检查超时,直接杀 Pod——明明一个接口都没被调用,启动却卡在 import 某个模块那里两分钟。
还原现场:
import time
def monitor_decorator(func):
print(f"正在初始化监控,绑定 {func.__name__}")
time.sleep(3) # 模拟连接池初始化
print("监控就绪")
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
@monitor_decorator
def get_user_info(user_id):
return f"用户 {user_id}"
只是 import 这个模块、一次都没调用,控制台照样输出那两行、照样等 3 秒。因为 @monitor_decorator 就是 get_user_info = monitor_decorator(get_user_info)——只要模块被加载,这行就执行,装饰器外层的代码就跑完。我当年"以为它在等指令,其实它第一眼看到我就动手了"。
正确姿势:所有重操作(连数据库、读文件、建连接)必须挪进 wrapper 内部,实现懒加载——第一次真正调用时才初始化。装饰器外层只做轻量的准备工作。
坑二:忘了 @wraps,框架炸了
代码本地跑得好好的,接上 Flask/FastAPI 后路由全失效。排查半天,发现 __name__ 全是 'wrapper'——框架靠函数名注册路由,包装后名字丢了。习惯:写 wrapper 之前先敲 @wraps(func),把它当成模板的一部分,而不是可选项。
坑三:三层漏写一层,报错看不懂
带参数装饰器少嵌套一层,@repeat(3) 会把 3 当函数传进去,报错完全对不上号。定位办法就是心里默背那句等价式 f = repeat(3)(f),检查每一层吃的是什么。
六、三个可以直接抄走的实战装饰器
学习笔记的终点是工具箱。三个高频场景的成品代码,均已含 @wraps、均已懒加载。
计时器:
import time
from functools import wraps
def timing(func):
@wraps(func)
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = func(*args, **kwargs)
elapsed = time.perf_counter() - start
print(f"{func.__name__}: {elapsed:.4f}s")
return result
return wrapper
重试器(带参数版):
def retry(max_attempts=3, delay=1):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
for attempt in range(max_attempts):
try:
return func(*args, **kwargs)
except Exception as e:
if attempt == max_attempts - 1:
raise
time.sleep(delay * (2 ** attempt)) # 指数退避
return wrapper
return decorator
@retry(max_attempts=3, delay=0.5)
def fetch_api(url):
...
缓存器——其实标准库已经写好了,functools.cache 就是一个官方装饰器,直接用:
from functools import cache
@cache
def fibonacci(n):
return n if n < 2 else fibonacci(n-1) + fibonacci(n-2)
看到 @cache 时可以顺便检验一下自己的理解:它是无参数装饰器(两层结构),在定义时执行,wrapper 里带着对原函数的闭包引用。
结语
回头看这篇笔记走过的路,其实只有一句话:
@不是魔法,是f = decorator(f)这行赋值的官方缩写——它在函数定义完成的瞬间执行,仅此而已。
这句话往前推,得到"装饰器在导入时就运行",于是坑一的启动卡死可以推演出来;往前推,得到"带参数时@后面是一次调用返回装饰器",于是三层嵌套的必然性可以推演出来;往前推,得到"原名被 wrapper 顶替",于是@wraps的必要性也可以推演出来。学语法的痛苦,九成来自把"可推导的东西"当"需要背诵的东西"。
这也是技术学习笔记这个方向的价值所在:踩坑的意义从来不是记住坑的位置,而是把坑背后的机制挖出来。机制有了,下一个没见过的语法糖——@property、@staticmethod、@dataclass——你都能自己拆开看。

浙公网安备 33010602011771号