不加 @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__：前者影响类型安全，后者是调试时唯一能快速回溯到原始函数的线索。
