带参数的装饰器必须三层：外层接收参数并返回装饰器，中层接收函数，内层接收调用参数；不加@functools.wraps会导致__name__、__doc__等元信息丢失，影响调试、反射和IDE功能；参数校验应放在外层。
为什么带参数的装饰器必须用三层函数
因为 Python 的 @ 语法只接受一个可调用对象作为装饰器，而你传进去的 @log(level="DEBUG") 实际上是先执行 log(level="DEBUG")，它必须返回一个真正的装饰器（即接收函数并返回新函数的二层函数）。所以结构固定为：外层接收装饰器参数 → 中层接收被装饰函数 → 内层接收函数调用时的参数。
常见错误是试图写成两层还硬塞参数，结果报 TypeError: 'function' object is not callable 或装饰器不生效 —— 那基本就是少了一层闭包。
@functools.wraps 不加会出什么问题
不加 @functools.wraps(func) 会导致被装饰函数的 __name__、__doc__、__module__ 全部变成内层函数的名字（比如 wrapper），断点调试、日志打点、框架反射（如 FastAPI 的依赖注入）都会失效。
实操建议：
- 只要写了自定义装饰器，
import functools+ 在内层函数前加@functools.wraps(func)是铁律 - 如果用
inspect.signature获取参数签名，不加@wraps会拿到wrapper的空签名，不是原函数的 - 某些 IDE（如 PyCharm）的跳转和类型提示也会失灵
参数校验和默认值该放在哪一层
装饰器参数（如 level、retry_times）的合法性检查，应该放在最外层函数里。因为它们在装饰发生时就已确定，早报错比晚报错更明确。
示例场景：写一个带重试次数和延迟的装饰器 @retry(times=3, delay=1)：
Python 3.14.3
微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。
def retry(times=3, delay=1):
if not isinstance(times, int) or times < 0:
raise ValueError("times must be non-negative integer")
if not isinstance(delay, (int, float)) or delay < 0:
raise ValueError("delay must be non-negative number")
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
# ...
return wrapper
return decorator
注意：times 和 delay 的校验在 retry() 调用时就完成，不是每次 wrapper 执行时再校验。
带参数装饰器和类装饰器怎么选
纯函数式三层嵌套适合逻辑简单、参数少、无状态的场景（比如日志级别、缓存过期时间）。一旦需要维护状态（如累计调用次数）、复用配置、或参数组合复杂，类装饰器更清晰。
容易踩的坑：
- 用类实现时，别忘了在
__init__接收装饰器参数，在__call__接收被装饰函数 —— 顺序错了就变不成装饰器 - 类装饰器里如果要支持
@MyDeco()和@MyDeco两种写法（即参数可省略），得在__call__里判断第一个参数是不是函数，逻辑会变臃肿；三层函数反而天然支持（靠是否传参决定调用哪一层） - 类装饰器的
__call__方法如果不加@functools.wraps，同样丢失元信息 —— 这点常被忽略
真正难的不是嵌套层数，而是闭包变量捕获时机：所有外层参数（如 level）在中层函数定义时就绑定进闭包，不会随后续调用改变。这点在循环生成多个装饰器时尤其关键。
