一、基础知识

要理解装饰器,先记住一句话:装饰器就是一个"接收函数、返回新函数"的可调用对象。它之所以可行,靠的是 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 换成真正的网络请求函数,就能得到一个简单的重试机制。

三、关键细节

  1. 执行时机不同:装饰发生在函数"定义时"(模块加载时),而不是"调用时"。把打印语句写在装饰器外层函数体里,启动时就会输出一次,别误以为是调用触发的。
  2. *args, **kwargs 是通用转发的关键:只写固定形参会让被装饰函数失去原有签名,调用稍微变化就报错。
  3. 返回 func(*args, **kwargs) 的结果:如果 wrapper 忘了 return,原函数的返回值会被吞掉,调用方只能拿到 None。
  4. 多个装饰器叠加时顺序自下而上:@a 在上、@b 在下时,等价于 a(b(func)),即先套 b 再套 a。
  5. 闭包变量是引用而非快照:外层变量在返回后若被修改,内层看到的是修改后的值,循环里创建多个装饰器时尤其要注意。

四、常见错误

现象 原因 修正
调用时报 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 的代码才会在每次调用时执行

五、排查方法

按下面顺序逐步缩小问题范围:

  1. 先看装饰是否发生:在装饰器外层临时加 print("decorating", func.__name__),运行模块确认输出。
  2. 检查签名:运行 python -c "import demo_decorator; print(demo_decorator.add.__name__)",若为 wrapper 说明缺 wraps。
  3. 检查层数:数一数 def 嵌套了几层。无参装饰器两层,带参装饰器三层,少一层就会类型错位。
  4. 检查转发:在 wrapper 里打印 args, kwargs,确认原函数参数确实传了进来。
  5. 检查返回值:临时把 wrapper 改成 return func(*args, **kwargs) 看结果是否恢复。
  6. 叠加顺序问题:把多个装饰器逐个注释掉,定位是哪一个引入的异常。

六、注意事项

  • 装饰器会改变函数的身份(除非用 wraps),依赖 __name__ 或类型注解的框架(如部分 Web 路由、依赖注入库)可能因元信息丢失而出错,wraps 应尽量养成习惯。
  • 类也可以作为装饰器:只要类实现了 __call__,写法与函数装饰器一致,但要注意实例状态和线程安全。
  • 不同 Python 版本对 @ 语法本身一致,但 functools 中辅助工具(如 cached_property)是逐步加入的,使用前请查官方文档确认你的版本是否支持。
  • 装饰器里的重试、超时等逻辑会掩盖真实异常,生产环境应控制重试次数并记录日志,避免把"快速失败"变成"长时间挂起"。
  • 不要在装饰器里捕获过宽的异常后静默吞掉,否则上层完全看不到错误,排查会非常困难。

免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。