python装饰器带参数怎么写

在 Python 中写带参数的装饰器，核心方法是在常规双层装饰器的外层再包裹一层函数，形成“三层嵌套函数”的闭包结构：最外层函数负责接收自定义配置参数并返回真实的装饰器，中间层函数接收被修饰的目标函数，最内层包装函数则接收目标函数的调用实参并执行前后置逻辑。

一、为什么带参数的装饰器必须写成三层？

很多开发者在刚接触 Python 装饰器时，通常习惯了无参装饰器的双层写法。要想清晰理解带参数装饰器怎么写，必须先看清 Python 解释器在遇到 @ 语法糖时的执行本质。

对于普通的无参装饰器，@decorator 本质上是等价于 func = decorator(func)。此时，decorator 必须是一个直接接收函数对象的可调用对象。

但当我们在装饰器后面带上括号与参数时，例如 @repeat(num=3)，Python 解释器在加载该函数定义时执行的等价语句变成了：

# 解释器遇到 @repeat(num=3) 时的执行过程：
func = repeat(num=3)(func)

这意味着，解释器会首先执行 repeat(num=3)，并将这一步调用的返回值作为真正作用于 func 的装饰器。为了让后续的 (func) 调用合法，repeat(num=3) 的返回值必须是一个能够接收函数的第二层函数；而第二层函数又必须返回真正替代原函数的第三层函数。这就是为什么带参数装饰器必然需要三层结构。

二、标准写法：三层闭包函数的四个编写步骤

编写带参数装饰器的标准做法是使用闭包（Closure）。闭包能够将外层函数的参数“打包”保存在内部函数的作用域中，即便外层函数早已执行完毕，内层逻辑依然可以随时访问这些配置。

下面通过一个实际场景演示编写过程：编写一个 @retry(max_attempts=3, delay_seconds=1) 装饰器，当目标函数抛出异常时根据传入的参数自动重试指定次数。

步骤 1：定义最外层配置函数

最外层函数的唯一职责是接收用户在使用装饰器时传入的配置参数（如次数、日志等级、超时时间等），并为内部逻辑建立闭包环境。

def retry(max_attempts=3, delay_seconds=1):
    # 外层接收配置参数：max_attempts 和 delay_seconds

步骤 2：定义中间层装饰器函数并使用 @wraps

中间层函数接收目标函数 func，它才是真正符合常规装饰器签名的函数。为了防止目标函数的名称、文档注释等元信息被篡改，必须使用 Python 内置库 functools.wraps 修饰内层函数。

    import time
    from functools import wraps

    def decorator(func):
        @wraps(func)  # 关键步骤：保留 func 的原始 __name__ 与 __doc__

步骤 3：定义最内层包装函数处理业务逻辑

最内层包装函数 wrapper 负责接收目标函数执行时的真实入参 *args, **kwargs，并在前后加入增强逻辑（如循环重试、计算耗时、权限鉴权等）。

        def wrapper(*args, **kwargs):
            last_exception = None
            for attempt in range(1, max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as exc:
                    last_exception = exc
                    print(f"[提示] 第 {attempt} 次执行失败: {exc}，等待 {delay_seconds} 秒...")
                    time.sleep(delay_seconds)
            raise last_exception

步骤 4：严格逐层返回函数对象

这是最容易疏忽的一步：中间层必须 return wrapper，最外层必须 return decorator。返回的是函数对象本身，严禁在 return 后添加调用括号 ()。

        return wrapper    # 中层返回内层包装器
    return decorator      # 外层返回真正的装饰器

完整代码示例与执行验证

以下是在 Python 3 环境下可直接运行的完整代码示例：

import time
from functools import wraps

def retry(max_attempts=3, delay_seconds=1):
    """带参数的重试装饰器"""
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            last_exc = None
            for attempt in range(1, max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    last_exc = e
                    print(f"-> 尝试第 {attempt} 次失败: {e}")
                    if attempt < max_attempts:
                        time.sleep(delay_seconds)
            print(f"-> 已达到最大重试次数 {max_attempts}，抛出异常")
            raise last_exc
        return wrapper
    return decorator

# 使用带参数的装饰器修饰网络请求模拟函数
@retry(max_attempts=3, delay_seconds=0.5)
def fetch_api_data(url):
    print(f"正在请求接口: {url}")
    raise ConnectionResetError("网络连接抖动")

# 执行测试
if __name__ == "__main__":
    try:
        fetch_api_data("https://api.example.com/v1/status")
    except ConnectionResetError:
        print("主程序捕获到最终异常，重试流程验证完成。")

三、关键差异：三层函数闭包 vs 基于类的装饰器

在 Python 中，实现带参数装饰器除了三层函数闭包外，另一种常见做法是使用“类（Class）”。在一致的使用条件下（同样支持 @decorator(args) 语法），两种做法在机制与设计上存在显著差异。

当使用类实现带参装饰器时，类的 __init__ 负责接收配置参数，而实例的 __call__ 方法则接管目标函数或执行过程。

类装饰器代码示例对照

from functools import wraps

class RateLimit:
    """基于类实现的带参限流/重试装饰器"""
    def __init__(self, limit=10, interval=60):
        # 步骤 1：__init__ 接收装饰器参数并保存在实例属性中
        self.limit = limit
        self.interval = interval

    def __call__(self, func):
        # 步骤 2：__call__ 接收被装饰函数，并返回内部 wrapper
        @wraps(func)
        def wrapper(*args, **kwargs):
            # 内部可以直接访问 self.limit 与 self.interval
            print(f"[限流检查] 允许上限: {self.limit} 次/{self.interval} 秒")
            return func(*args, **kwargs)
        return wrapper

# 使用方式与函数装饰器完全相同
@RateLimit(limit=5, interval=10)
def send_message(msg):
    print(f"发送消息: {msg}")

四、避坑指南：带参数装饰器最易犯的三个错误

五、知识梳理与核心总结

掌握 Python 带参数装饰器的本质，关键在于看透“语法糖求值顺序”与“闭包作用域”的结合。只要遵循三层闭包的标准范式，就能游刃有余地为函数注入灵活可配的附加能力。