@functools.wraps是必须的，因为它将原函数的__module__、__name__、__doc__、__annotations__等元数据复制到包装函数，避免help()、inspect.signature()等返回装饰器内部信息而丢失原始函数文档和类型提示。
为什么@functools.wraps是必须的？
直接用装饰器包裹函数后，help()、inspect.signature()、__name__、__doc__这些都会变成装饰器内部函数的信息，不是原始函数的。比如你写了个retry_on_failure装饰器，但调用help(my_func)却显示“这是重试装饰器”，这就没法调试、IDE 也无法正确补全参数。
根本原因是 Python 默认不自动复制元数据，装饰器本质是把新函数赋值给原名，覆盖了原始对象的属性。
-
@functools.wraps(func)会把func的__module__、__name__、__qualname__、__doc__、__annotations__等全部拷贝到包装函数上 - 它底层调用的是
functools.update_wrapper()，但@wraps更简洁、更常用 - 不加它，
my_func.__name__会变成'wrapper'，而不是你定义的函数名
异常处理装饰器里怎么正确用@wraps？
常见错误是把@wraps放在错的位置——它必须作用在内层包装函数上，不是外层装饰器工厂函数。
比如你要写一个捕获ValueError并返回默认值的装饰器：
立即学习“Python免费学习笔记（深入）”；
from functools import wraps <p>def catch_value_error(default=None): def decorator(func): @wraps(func) # ← 这里！不是放在 catch_value_error 上 def wrapper(*args, *<em>kwargs): try: return func(</em>args, **kwargs) except ValueError: return default return wrapper return decorator
如果漏掉@wraps(func)，哪怕只装饰一个函数，my_func.__doc__也会丢失；如果用了typing.get_type_hints(my_func)，还会因__annotations__为空而报错。
- 装饰器带参数（如
catch_value_error(default=...)）时，@wraps一定在最内层wrapper定义前 - 不带参数的装饰器（直接
@catch_exc），也一样：在def wrapper之前加@wraps(func) - 别试图手动赋值
wrapper.__name__ = func.__name__——漏掉__annotations__或__dict__可能引发后续问题
保留元数据后还可能出什么问题？
@wraps能解决大部分元数据丢失问题，但有些场景它帮不上忙：
-
inspect.signature()在某些动态生成函数（如用exec()或types.FunctionType构造）上仍可能失效，因为签名信息没被写入__signature__ - 如果你在
wrapper里修改了**kwargs或重写了参数逻辑，inspect.signature(wrapper)显示的仍是原始函数签名，和实际行为不一致——这是设计使然，不是 bug - Pydantic 或 FastAPI 这类依赖函数签名做校验的框架，会读
__signature__，所以即使@wraps生效，也要确保wrapper的调用协议和原函数兼容
简单说：@wraps让元数据“看起来对”，但不保证运行时行为完全透明。异常处理装饰器若改变了参数传递方式（比如强制注入retry_times），就得额外处理签名。
