装饰器是 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 也值得读一读源码,
是很好的学习材料。