一、基础知识
要理解装饰器,先记住一句话:装饰器就是一个"接收函数、返回新函数"的可调用对象。它之所以可行,靠的是 Python 里三个基础事实。
第一,函数是"一等对象"。函数可以像普通变量一样赋值给别的名字,也可以作为实参传给另一个函数,还能被当作返回值。下面这段代码把函数当成参数传来传去,完全合法:
def greet(name):
return f"你好,{name}"
say = greet # 函数赋值给变量
print(say("小明")) # 你好,小明
def call(fn, value):
return fn(value) # 函数作为参数
print(call(greet, "小红"))
第二,闭包。当一个内层函数引用了外层函数作用域里的变量,即使外层函数已经执行结束,这个变量依然"活着",内层函数还能访问它。装饰器就是利用闭包,把原函数"包"起来,在调用前后插入自己的逻辑。
第三,@ 只是语法糖。写 @timer 放在函数定义上方,等价于在函数定义完成后执行 func = timer(func)。也就是说,下面两段代码完全等价:
def timer(func): # 这里用一个原样返回的简版做演示
return func
@timer
def work():
...
def timer(func):
return func
def work():
...
work = timer(work)
理解了这三点,装饰器就不再是魔法:它把原函数换成了包装后的新函数,而新函数内部依旧持有对原函数的引用。
一个最简单的计时装饰器如下:
import time
def timer(func):
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = func(*args, **kwargs)
cost = time.perf_counter() - start
print(f"{func.__name__} 耗时 {cost:.4f} 秒")
return result
return wrapper
它接收 func,返回一个 wrapper;wrapper 用 *args 和 **kwargs 转发任意参数,保证被装饰函数原本怎么调用,现在还能怎么调用。
二、实操步骤
下面按四步,把一个计时器改造成可用的"带重试次数参数"的装饰器。建议把代码保存为 demo_decorator.py,边看边运行。
第 1 步:写最简装饰器并应用
import time
def timer(func):
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = func(*args, **kwargs)
print(f"{func.__name__} 耗时 {time.perf_counter() - start:.4f}s")
return result
return wrapper
@timer
def add(a, b):
time.sleep(0.1)
return a + b
print(add(1, 2))
运行后你会先看到耗时输出,再看到结果 3,说明计时逻辑确实插在了原函数前后。
第 2 步:用 functools.wraps 保留元信息
直接返回的 wrapper 有个副作用:add.__name__ 会变成 wrapper,文档字符串也丢失。这会让调试和文档生成工具困惑。用标准库的 wraps 修正:
from functools import wraps
def timer(func):
@wraps(func)
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = func(*args, **kwargs)
print(f"{func.__name__} 耗时 {time.perf_counter() - start:.4f}s")
return result
return wrapper
加上 @wraps(func) 后,add.__name__ 仍然是 add,help(add) 也能看到原来的说明。
第 3 步:理解"带参数"为什么要多一层
@timer 直接跟函数,而 @retry(times=3) 先调用一次拿到真正的装饰器。因此带参数装饰器是三层结构:最外层接收参数,中间层接收函数,最内层才是包装函数。
第 4 步:写出带参数的重试装饰器
from functools import wraps
import time
def retry(times=3, delay=0.5):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
last_exc = None
for i in range(times):
try:
return func(*args, **kwargs)
except Exception as exc:
last_exc = exc
if i < times - 1:
time.sleep(delay)
raise last_exc
return wrapper
return decorator
@retry(times=3, delay=0.2)
def flaky():
print("执行一次")
raise ValueError("模拟失败")
flaky()
运行会打印三次"执行一次"后抛出最后一次异常。把 flaky 换成真正的网络请求函数,就能得到一个简单的重试机制。
三、关键细节
- 执行时机不同:装饰发生在函数"定义时"(模块加载时),而不是"调用时"。把打印语句写在装饰器外层函数体里,启动时就会输出一次,别误以为是调用触发的。
*args, **kwargs是通用转发的关键:只写固定形参会让被装饰函数失去原有签名,调用稍微变化就报错。- 返回
func(*args, **kwargs)的结果:如果wrapper忘了return,原函数的返回值会被吞掉,调用方只能拿到None。 - 多个装饰器叠加时顺序自下而上:
@a在上、@b在下时,等价于a(b(func)),即先套b再套a。 - 闭包变量是引用而非快照:外层变量在返回后若被修改,内层看到的是修改后的值,循环里创建多个装饰器时尤其要注意。
四、常见错误
| 现象 | 原因 | 修正 |
|---|---|---|
调用时报 missing 1 required positional argument: 'func' |
把带参数装饰器写成了两层,@retry(times=3) 把 times 当函数传了进去 |
补齐三层结构:外层收参数、中层收函数、内层做包装 |
add.__name__ 变成 wrapper,文档字符串丢失 |
没有用 functools.wraps |
在 wrapper 上加 @wraps(func) |
原函数有返回值,装饰后却得到 None |
wrapper 里调用 func 后没有 return |
写成 return func(*args, **kwargs) |
| 带参数时被装饰函数收不到自己的参数 | 内层 wrapper 没写 *args, **kwargs 转发 |
用 def wrapper(*args, **kwargs) 并原样转发 |
| 装饰器里的打印在程序一启动就出现 | 把逻辑写在了外层函数体而非 wrapper 内 |
只有放进 wrapper 的代码才会在每次调用时执行 |
五、排查方法
按下面顺序逐步缩小问题范围:
- 先看装饰是否发生:在装饰器外层临时加
print("decorating", func.__name__),运行模块确认输出。 - 检查签名:运行
python -c "import demo_decorator; print(demo_decorator.add.__name__)",若为wrapper说明缺wraps。 - 检查层数:数一数
def嵌套了几层。无参装饰器两层,带参装饰器三层,少一层就会类型错位。 - 检查转发:在
wrapper里打印args, kwargs,确认原函数参数确实传了进来。 - 检查返回值:临时把
wrapper改成return func(*args, **kwargs)看结果是否恢复。 - 叠加顺序问题:把多个装饰器逐个注释掉,定位是哪一个引入的异常。
六、注意事项
- 装饰器会改变函数的身份(除非用
wraps),依赖__name__或类型注解的框架(如部分 Web 路由、依赖注入库)可能因元信息丢失而出错,wraps应尽量养成习惯。 - 类也可以作为装饰器:只要类实现了
__call__,写法与函数装饰器一致,但要注意实例状态和线程安全。 - 不同 Python 版本对
@语法本身一致,但functools中辅助工具(如cached_property)是逐步加入的,使用前请查官方文档确认你的版本是否支持。 - 装饰器里的重试、超时等逻辑会掩盖真实异常,生产环境应控制重试次数并记录日志,避免把"快速失败"变成"长时间挂起"。
- 不要在装饰器里捕获过宽的异常后静默吞掉,否则上层完全看不到错误,排查会非常困难。
免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。

评论
还没有评论,来说两句吧。