Python 带参数装饰器的正确写法

带参数装饰器必须返回真正的装饰器函数，即三层嵌套结构：最外层接收参数并校验，中间层接收被装饰函数并返回内层函数，最内层执行逻辑且需用@functools.wraps(func)保留原函数元信息。

带参数装饰器必须返回一个真正的装饰器函数

很多人写 @log(level="DEBUG") 时直接在最外层函数里写逻辑，结果报错 TypeError: 'NoneType' Object is not callable。根本原因是：带参数的装饰器结构是三层函数，最外层接收参数，中间层接收被装饰的函数，最内层才是实际执行逻辑的闭包。

常见错误写法：def log(level): ... return wrapper()（多写了括号，直接调用了）；或漏掉中间层，导致 python 尝试用函数本身去装饰目标函数，而它又不是可调用对象。

• 最外层：接收装饰器参数，比如 level、name
• 中间层：接收被装饰的函数 func，必须返回内层函数
• 最内层：接收 *args, **kwargs，负责调用原函数并添加逻辑

正确结构模板：三阶嵌套 + functools.wraps 不可省

不加 @functools.wraps(func)，被装饰函数的 __name__、__doc__ 全变成内层函数的名字（比如 inner），对调试、文档生成、框架反射（如 fastapi 路由注册）都会出问题。

from functools import wraps  def log(level="INFO"):     def decorator(func):         @wraps(func)         def inner(*args, **kwargs):             print(f"[{level}] Calling {func.__name__}")             return func(*args, **kwargs)         return inner     return decorator

注意：@wraps(func) 必须作用于最内层函数（inner），且 func 是中间层传入的那个原始函数。

立即学习“Python免费学习笔记（深入）”；

参数校验和默认值要在最外层处理

如果允许用户传非法 level（比如 @log(level="TRACE") 但日志系统不支持），应该在最外层就抛错，而不是等函数运行时才检查——否则每次调用都重复判断，浪费性能，也掩盖了配置错误。

• 参数类型/范围检查放在最外层函数体中（def log(level=...): 后立即校验）
• 避免在 inner 中做耗时初始化（如打开文件、连接数据库），应提至中间层或最外层完成
• 若需动态参数（如从环境变量读取），可在最外层用 Lambda 或闭包捕获，但要小心延迟求值陷阱

类实现的带参装饰器：更易维护但要注意 __call__ 签名

当逻辑变复杂（比如要缓存状态、支持重置、多参数组合），用类比嵌套函数更清晰。但必须确保类实例是可调用的，且中间层行为不被绕过。

class Log:     def __init__(self, level="INFO"):         self.level = level      def __call__(self, func):         @wraps(func)         def inner(*args, **kwargs):             print(f"[{self.level}] {func.__name__}")             return func(*args, **kwargs)         return inner  @Log(level="WARNING") def foo(): pass

关键点：__call__ 方法就是中间层，它接收 func 并返回包装函数；类初始化只跑一次，适合带状态的装饰逻辑。但别忘了 @wraps 仍得用在 inner 上。

容易忽略的是：类装饰器无法像函数装饰器那样支持 @Log() 和 @Log 两种写法同时存在——后者会把类本身当 func 传给 __call__，直接崩。统一要求带括号，能减少歧义。