被装饰函数的__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 wrapsdef my_decorator(func): @wraps(func) # ← 关键：加在这儿 def wrapper(*args, *kwargs): print("Before") result = func(args, **kwargs) print("After") return result return wrapper
@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 wrapsclass CountCalls: def init(self, func): self.func = func self.count = 0
注意：这里不能直接 wraps(self)，因为 self 不是函数
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__，而是中间某层包装函数的。
