Python带参数装饰器写法详解

Python带参数装饰器的核心在于理解其必须采用三层嵌套结构——最外层接收并校验参数，中间层接收被装饰函数并返回包装器，最内层执行增强逻辑；若结构错乱（如漏掉中间层、误调用wrapper()或忽略@functools.wraps），轻则导致TypeError，重则破坏函数元信息、干扰调试与框架集成；文章不仅剖析了常见错误根源，还提供了函数式与类式两种规范写法，并强调参数校验前置、资源初始化提级、状态管理优化等实战要点，帮你写出健壮、可维护且符合Python最佳实践的带参装饰器。

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

很多人写 @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 是中间层传入的那个原始函数。

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

如果允许用户传非法 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__，直接崩。统一要求带括号，能减少歧义。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python带参数装饰器写法详解》文章吧，也可关注golang学习网公众号了解相关技术文章。