Python functools.wraps 的必要性解析

不加 @functools.wraps 会导致被装饰函数的 name__、__doc__、__module__、__annotations 等元信息丢失，变为包装函数的值，影响调试、文档生成、类型检查和框架路由注册。

装饰器里不加 @functools.wraps 会丢掉什么

函数的 __name__、__doc__、__module__、__annotations__ 这些元信息全都会变成内层包装函数的，而不是原始函数的。调试、文档生成（比如 sphinx）、类型检查（mypy）、甚至某些框架的路由注册（如 fastapi）都依赖这些字段。

常见错误现象：help(my_decorated_func) 显示的是包装函数的空文档；用 inspect.signature() 拿到的是包装函数的签名，不是原函数的；日志里打出来的函数名是 wrapper 而不是你写的 fetch_user。

• 所有被装饰函数的 __name__ 默认变成 'wrapper'
• __doc__ 变成 None 或包装函数自己的字符串
• ide 自动补全和跳转可能失效（尤其依赖 __qualname__ 的场景）

@functools.wraps(func) 到底做了哪些事

它不是魔法，只是把 func 的关键属性批量复制到包装函数上。底层调用的是 functools.WRAPPER_ASSIGNMENTS 和 functools.WRAPPER_UPDATES 定义的字段列表。

实际等价于手动写：

立即学习“Python免费学习笔记（深入）”；

def wrapper(*args, **kwargs):     ... wrapper.__name__ = func.__name__ wrapper.__doc__ = func.__doc__ wrapper.__module__ = func.__module__ wrapper.__annotations__ = func.__annotations__ wrapper.__dict__.update(func.__dict__)

但别手写——漏掉 __dict__ 更新会导致自定义属性丢失；漏掉 __annotations__ 会让类型提示失效；而 @wraps 一行就覆盖全部。

• 它只复制明确列出的属性，不碰 __code__ 或 __defaults__（那些属于行为，不是元数据）
• 不影响函数执行逻辑，纯粹是“让外人认得出来这是谁”
• python 3.5+ 后还顺带处理了 __wrapped__ 属性（指向原函数），方便解包

不加 @wraps 在真实项目里踩过哪些坑

不是“看起来不太好看”，而是直接导致工具链断裂。比如：

• FastAPI 把装饰后函数的 __name__ 当作路由 endpoint 名，结果 OpenAPI 文档里全是 wrapper
• mypy 报错 Argument 1 has incompatible type "Callable[..., Any]"，因为签名丢失后类型推导失败
• pytest 收集测试时，test_foo.py::wrapper 出现在报告里，根本找不到对应源码位置
• 用 Logging.getLogger(__name__) 的模块名变成 functools，日志全串了

这些都不是报错，而是静默错位——问题往往在集成阶段才暴露，查起来绕一大圈。

什么时候可以不用 @functools.wraps

极少。只有两种情况：你明确认为「这个装饰器就是故意要隐藏原函数身份」，或者「这个函数压根不会被反射、调试、文档化、类型检查」。

• 写一次性脚本里的私有装饰器，且全程不用 help()、inspect、IDE 补全
• 做 AOP 式日志埋点，且日志里只记时间戳和参数，不记函数名

但只要涉及协作、维护、或任何自动化工具链，就默认加上。它成本为零，收益确定——漏掉一次，排查半天。

最常被忽略的其实是 __annotations__ 和 __wrapped__：前者影响类型安全，后者是调试时唯一能快速回溯到原始函数的线索。