Python中使用装饰器处理函数异常时如何保留原始函数的元数据？-Python教程-PHP中文网

@functools.wraps是必须的，因为它将原函数的__module__、__name__、__doc__、__annotations__等元数据复制到包装函数，避免help()、inspect.signature()等返回装饰器内部信息而丢失原始函数文档和类型提示。

python中使用装饰器处理函数异常时如何保留原始函数的元数据？

为什么`@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-parallelization

将顺序 Python 代码转换为并行/并发实现，用于在需要并行化 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</p>

如果漏掉@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的调用协议和原函数兼容