带参数的装饰器必须是三层函数，因为@decorator(arg)会先调用decorator(arg)返回一个接收函数的装饰器；外层传参数，中层接函数，内层处理调用，需用functools.wraps保留原函数属性，复杂状态逻辑才考虑类实现。
带参数的装饰器为什么必须是三层函数
因为 Python 解释器在遇到 @decorator(arg) 语法时，会先调用 decorator(arg)，期望它返回一个「真正的装饰器」（即接收函数并返回新函数的可调用对象）。如果只写两层，decorator(arg) 返回的就不是可调用对象，或者无法正确接收被装饰函数，运行时会报 TypeError: 'function' object is not callable 或直接抛出 TypeError 说缺少参数。
常见错误现象：TypeError: wrapper() takes 0 positional arguments but 1 was given —— 这通常是因为最内层函数没接收 *args, **kwargs，或中间层漏掉了返回函数。
- 外层函数（如
log_calls）负责接收装饰器参数，必须返回中层函数 - 中层函数（如
decorator）接收被装饰的函数func，必须返回内层函数 - 内层函数（如
wrapper）接收实际调用时的参数，执行逻辑并调用原函数
如何正确传递和使用装饰器参数
装饰器参数（比如日志级别、重试次数、超时时间）应在最外层捕获，然后通过闭包传入内层。不能在 wrapper 里重新读取外部变量（除非是不可变且确定不变的），否则容易因作用域或延迟求值出错。
示例：实现一个带 level 参数的日志装饰器：
def log_calls(level="INFO"):
def decorator(func):
def wrapper(*args, **kwargs):
print(f"[{level}] Calling {func.__name__}")
return func(*args, **kwargs)
return wrapper
return decorator
<p>@log_calls(level="DEBUG")
def add(a, b):
return a + b
</p>
注意：level 在 log_calls() 调用时就被固定下来，每个被该装饰器实例修饰的函数都拥有独立的 level 值 —— 这正是闭包的作用。
带参数装饰器与 functools.wraps 的配合要点
如果不加 @functools.wraps(func)，被装饰函数的 __name__、__doc__、__module__ 都会变成 wrapper 的，导致调试困难、IDE 提示异常、文档生成失败（如 Sphinx 抓不到 docstring）。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
必须把 @functools.wraps(func) 放在最内层函数定义之后、返回之前：
from functools import wraps <p>def retry(times=3): def decorator(func): @wraps(func) # ← 关键：放在这里，不是在外层或中层 def wrapper(*args, *<em>kwargs): for i in range(times): try: return func(</em>args, **kwargs) except Exception: if i == times - 1: raise return None return wrapper return decorator </p>
漏掉 @wraps 是生产环境高频踩坑点，尤其当函数需要被反射、序列化或集成进框架（如 FastAPI、pytest）时，行为可能完全不可预期。
什么时候该用类实现带参数装饰器
当装饰器逻辑较重、需要维护状态（如累计调用次数、缓存上次结果）、或参数本身是可变对象（如列表、字典）时，函数式三层嵌套容易混乱，此时用类更清晰。
类装饰器需实现 __init__（接收装饰器参数）、__call__（接收被装饰函数）、再定义一个内部方法或在 __call__ 中返回闭包 —— 但要注意：类实例必须可调用，且要手动处理 __name__ 等属性，或仍需搭配 @wraps（对 __call__ 中包装的函数）。
简单原则：90% 场景用函数式三层足够；只有真正需要实例状态或复杂初始化逻辑时，才切换到类。
容易忽略的一点：类装饰器若未显式定义 __get__ 方法，在装饰实例方法时可能丢失 self 参数，导致 TypeError: wrapper() missing 1 required positional argument: 'self' —— 这比函数式更隐蔽。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
