装饰器是 Python 里最常用的语法糖之一。Flask 的 @app.route、 Django 的 @login_required、标准库的 @functools.lru_cache, 背后都是同一个机制。理解它之后,你会发现很多“魔法”其实很朴素。

前提:函数也是对象

在 Python 中,函数是一等对象:可以赋值给变量、作为参数传递、作为返回值返回。 这是装饰器能成立的根本原因。

def greet(name):
    return f"Hello, {name}"


say = greet                 # 赋值给变量
print(say("World"))         # Hello, World

def call_it(func, arg):     # 作为参数
    return func(arg)

call_it(greet, "Python")    # Hello, Python

闭包:记住外层变量

内层函数引用外层函数的局部变量,并在外层返回后仍然能访问,这就是闭包:

def make_multiplier(n):
    def multiply(x):
        return x * n       # n 来自外层作用域
    return multiply


double = make_multiplier(2)
triple = make_multiplier(3)

print(double(5))   # 10
print(triple(5))   # 15

每个 make_multiplier 调用都会创建独立的作用域, 所以 double 和 triple 各自记住了自己的 n。

第一个装饰器

装饰器本质上是一个“接收函数、返回新函数”的高阶函数。 @deco 只是 func = deco(func) 的简写:

def log_calls(func):
    def wrapper(*args, **kwargs):
        print(f"调用 {func.__name__},参数:{args} {kwargs}")
        return func(*args, **kwargs)
    return wrapper


@log_calls
def add(a, b):
    return a + b


print(add(1, 2))

输出:

调用 add,参数:(1, 2) {}
3

*args, **kwargs 让包装函数可以适配任意签名的原函数, 这是写通用装饰器的标准做法。

别忘了 functools.wraps

上面的写法有一个副作用:add.__name__ 变成了 wrapper,文档字符串、类型注解等元信息也丢了。 这会影响调试、日志和依赖函数名的框架。

functools.wraps 会把原函数的元信息复制到包装函数上:

import functools


def log_calls(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"调用 {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

写装饰器时加上这一行,几乎是零成本的好习惯。

带参数的装饰器

需求变成“可以指定日志前缀”时,装饰器需要再套一层: 最外层接收参数,返回真正的装饰器。

def log_with(prefix):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            print(f"[{prefix}] 调用 {func.__name__}")
            return func(*args, **kwargs)
        return wrapper
    return decorator


@log_with("DEBUG")
def add(a, b):
    return a + b

这里有三层函数,看起来绕,但按调用顺序拆开就清楚了:

log_with("DEBUG")          # 返回 decorator
decorator(add)             # 返回 wrapper
wrapper(1, 2)              # 真正执行

用类实现装饰器

需要保存状态时,类会更直观。只要实现 __call__, 实例就可以像函数一样被调用:

class CountCalls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.calls = 0

    def __call__(self, *args, **kwargs):
        self.calls += 1
        print(f"{self.func.__name__} 第 {self.calls} 次调用")
        return self.func(*args, **kwargs)


@CountCalls
def say_hi():
    print("hi")


say_hi()
say_hi()
print(say_hi.calls)   # 2

类装饰器适合需要跨调用累计数据、或者需要提供额外方法(如 reset())的场景。普通场景下,闭包版本更轻量。

实战一:计时器

排查性能时,经常需要知道某个函数跑了多久。用 finally 保证异常时也能输出耗时:

import functools
import time


def timer(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        try:
            return func(*args, **kwargs)
        finally:
            cost = time.perf_counter() - start
            print(f"{func.__name__} 耗时 {cost * 1000:.2f} ms")
    return wrapper


@timer
def slow_task():
    time.sleep(0.2)


slow_task()   # slow_task 耗时 200.xx ms

time.perf_counter() 比 time.time() 精度更高,也不受系统时钟调整影响,适合测量耗时。

实战二:失败重试

调用外部接口时,偶发的网络抖动很常见。写一个可配置次数和异常类型的重试装饰器:

import functools
import time


def retry(times=3, exceptions=(Exception,), delay=0.5, backoff=2.0):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            wait = delay
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except exceptions as exc:
                    if attempt == times:
                        raise
                    print(f"第 {attempt} 次失败:{exc},{wait:.1f}s 后重试")
                    time.sleep(wait)
                    wait *= backoff
        return wrapper
    return decorator


@retry(times=3, exceptions=(ConnectionError,), delay=0.5)
def fetch_data():
    ...

注意这里只在最后一次失败时 raise,把原始异常抛给调用方, 而不是吞掉它。指数退避(backoff)能避免重试风暴把下游压垮。

几个容易踩的坑

  • 装饰顺序:@a 在 @b 上方时, 等价于 a(b(func)),即离函数最近的先执行。
  • 忘记返回值:包装函数里漏写 return, 原函数的返回值会变成 None,这类 bug 很隐蔽。
  • 装饰器作用在导入时:模块被 import 时装饰器就会执行, 所以不要在装饰器里做耗时操作。
  • 方法装饰器:装饰类的方法时,第一个参数是 self, *args 已经能正确处理,不需要特殊写法。

小结

装饰器 = 高阶函数 + 闭包。掌握三层结构(参数层 → 装饰器层 → 包装层), 再加上 functools.wraps,日常开发中需要的功能基本都能写出来。 标准库里的 lru_cache、singledispatch 也值得读一读源码, 是很好的学习材料。