带参数装饰器必须返回真正的装饰器函数，即三层嵌套结构：最外层接收参数并校验，中间层接收被装饰函数并返回内层函数，最内层执行逻辑且需用@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__，直接崩。统一要求带括号，能减少歧义。
