被装饰函数的__name__和__doc__丢失是因为装饰器用新函数替换了原函数，而wrapper默认携带自身元数据；functools.wraps可自动同步__name__、__doc__等属性，避免手动赋值遗漏，类装饰器及嵌套装饰器中同样必须使用。
为什么被装饰函数的 __name__ 和 __doc__ 会丢失
Python 装饰器本质是用新函数替换了原函数对象。如果装饰器内部直接返回一个普通闭包（比如 def wrapper(*args, **kwargs): ...），那么这个 wrapper 的 __name__ 就是 "wrapper"，__doc__ 也来自它自身，和原函数无关。常见现象包括：help(my_decorated_func) 显示的是装饰器里的文档，而不是原函数的；my_decorated_func.__name__ 返回 "wrapper" 而非预期名称。
用 functools.wraps 一键同步元数据
functools.wraps 是标准解法，它本身是个装饰器，作用是把被装饰函数的 __module__、__name__、__qualname__、__doc__、__annotations__ 等属性复制到包装函数上。
使用方式很简单：
from functools import wraps
<p>def my_decorator(func):
@wraps(func) # ← 关键：加在这儿
def wrapper(*args, *<em>kwargs):
print("Before")
result = func(</em>args, **kwargs)
print("After")
return result
return wrapper</p><p>@my_decorator
def say_hello():
"""Say hello to the world."""
return "Hello!"
此时 say_hello.__name__ 是 "say_hello"，say_hello.__doc__ 也是 "Say hello to the world."。
立即学习“Python免费学习笔记（深入）”；
不使用 @wraps 时手动同步的隐患
有人尝试手动赋值，比如在 wrapper 内部写 wrapper.__name__ = func.__name__，但这只解决表面问题：
-
__doc__、__module__、__annotations__、__dict__等都得逐个处理，容易遗漏 -
__wrapped__属性不会自动建立，导致无法通过inspect.unwrap()反向获取原始函数 - 某些框架（如 Flask、Click）依赖完整的元数据，手动同步可能引发兼容性问题
- Python 3.12+ 对
__qualname__和嵌套函数名更敏感，漏掉会导致调试困难
装饰器类里也要用 wraps 吗
要。即使你写的是类装饰器，只要返回的是可调用对象（比如实现了 __call__），且希望保留原函数元数据，就必须在 __call__ 内部或返回的包装函数上应用 @wraps。
例如：
from functools import wraps
<p>class CountCalls:
def <strong>init</strong>(self, func):
self.func = func
self.count = 0</p><h1>注意：这里不能直接 wraps(self)，因为 self 不是函数</h1><pre class="brush:php;toolbar:false;">def __call__(self, *args, **kwargs):
self.count += 1
@wraps(self.func) # ← 必须在这里 wrap 包装逻辑
def wrapped(*a, **kw):
return self.func(*a, **kw)
return wrapped(*args, **kwargs)
不过更常见的写法是把 @wraps 放在 __call__ 返回的闭包上，或者直接在 __init__ 中用 wraps 处理 self 的属性 —— 但最稳妥、最符合直觉的方式仍是：**只要你在返回一个新函数，且它替代了原函数，就对那个新函数用 @wraps(func)**。
真正容易被忽略的，是装饰器嵌套场景：比如 @retry @cache @log，每一层都必须正确使用 wraps，否则最外层拿到的就不是原始函数的 __doc__，而是中间某层包装函数的。
