装饰器失效主因是未正确调用或语法位置错误；带参装饰器需三层嵌套且中层必须返回包装函数；务必使用@functools.wraps保留原函数元数据；修改参数或提前返回需谨慎处理副作用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
装饰器写不生效？先检查 @ 语法和函数调用位置
装饰器失效最常见原因是没真正调用被装饰的函数，或者把 @decorator 写在了函数定义之外。Python 装饰器本质是函数调用 + 赋值： @log_calls 等价于 func = log_calls(func)，如果 func 没被重新赋值或后续没调用，就什么都不会发生。
- 确保
@紧贴在def上方，中间不能有空行或注释干扰解析 - 确认你运行的是装饰后的函数，不是原函数名（比如写了
@cache却还手动调用了未装饰的original_func()） - 类方法上用装饰器时，注意
self参数是否被意外吞掉——普通函数装饰器套在实例方法上大概率出错
带参数的装饰器为什么总报 TypeError: 'function' object is not callable
这是三层嵌套没写对的典型症状。带参数的装饰器必须返回一个“真装饰器”，也就是一个接收函数并返回包装函数的函数。漏掉任意一层，Python 就会尝试直接调用你返回的东西，而它往往是个函数对象本身。
- 结构必须是：外层接收装饰器参数 → 中层接收被装饰函数 → 内层是实际执行逻辑的闭包
- 别忘了中层函数要加
@functools.wraps(func)，否则help()和func.__name__全乱 - 错误示例：
@retry(max_attempts=3)如果retry直接返回包装函数而非“装饰器工厂”，就会触发该错误
def retry(max_attempts):
def decorator(func): # ← 这一层不能少
@functools.wraps(func)
def wrapper(*args, **kwargs):
for i in range(max_attempts):
try:
return func(*args, **kwargs)
except Exception:
if i == max_attempts - 1:
raise
return wrapper
return decorator # ← 必须返回这个函数，不是调用它
用 functools.wraps 不只是为好看，它影响调试和框架识别
不加 @functools.wraps(func) 的装饰器会让被装饰函数丢失原始元数据，这在日志、序列化、类型检查甚至 FastAPI 路由注册时都会出问题。比如 inspect.signature() 拿不到原函数参数，help(my_api_route) 显示的是 wrapper 而不是你的视图函数。
- 只要装饰器里用了闭包包装函数，就必须加
@functools.wraps(func)，没有例外 - 它只修复
__name__、__doc__、__module__、__annotations__和__dict__，不解决闭包变量捕获问题 - 如果你自己手动复制这些属性（比如
wrapper.__name__ = func.__name__），容易漏项且不可靠
装饰器里改 **kwargs 或提前 return，要注意副作用传播
很多装饰器会在包装函数里修改传入参数、注入新参数，或者根据条件跳过原函数执行。这类操作看似简单，但容易破坏调用链的可预测性，尤其当多个装饰器叠加时。
立即进入“豆包AI人工智官网入口”；
立即学习“豆包AI人工智能在线问答入口”；
- 修改
kwargs后一定要return func(*args, **kwargs)，别忘了传回去——有人写成func(args, kwargs)导致参数全变成位置参数 - 缓存装饰器如果对 mutable 类型（如
list、dict）做 key，可能命中错误结果；建议用repr()或json.dumps()序列化，但要注意性能 - 异步函数不能直接用同步装饰器包装，
await wrapper(...)会报RuntimeWarning: coroutine ... was never awaited
装饰器的复杂点不在语法，而在它悄悄改变了函数的身份和行为边界。最容易被忽略的是：你以为在调用 A 函数，其实运行的是 N 层嵌套后的闭包；你以为参数没变，其实某层装饰器已经偷偷塞进了 request_id 或重写了 timeout。写完记得用 inspect.getsource() 或断点进 wrapper 看一眼真实调用栈。
