Python装饰器默认覆盖原函数签名（如__name__、__doc__等），因闭包函数与原函数是不同对象；用functools.wraps可自动复制元信息，确保调试、文档生成和框架反射正常。
Python 装饰器默认会覆盖原函数的签名（如 __name__、__doc__、__annotations__ 等），导致调试、文档生成、类型检查或框架反射（如 FastAPI、Flask）出错。关键在于装饰器内部返回的新函数没有继承原函数的元信息。
为什么签名会被改写？
典型装饰器返回一个闭包函数，它与原函数是完全不同的对象：
- 新函数的
__name__是闭包名（如wrapper），不是原函数名 -
__doc__默认为None或闭包自身的文档字符串 -
__annotations__、__module__、__qualname__等也丢失 - 参数签名（通过
inspect.signature()获取）变成闭包的参数，而非原函数的
如何保留原始签名？
使用 functools.wraps 是最标准、推荐的做法。它把原函数的关键属性复制到包装函数上：
from functools import wraps
<p>def my_decorator(func):
@wraps(func) # ← 关键：自动复制 <strong>name</strong>, <strong>doc</strong>, <strong>annotations</strong> 等
def wrapper(*args, *<em>kwargs):
print("Before")
result = func(</em>args, **kwargs)
print("After")
return result
return wrapper</p><p>@my_decorator
def greet(name: str) -> str:
"""Say hello to someone."""
return f"Hello, {name}"
</p>
此时 greet.__name__ 仍是 "greet"，greet.__doc__ 仍是 "Say hello to someone."，inspect.signature(greet) 也正确显示 (name: str) -> str。
Python 环境工具专业版
下载
Python 环境工具专业版功能概述Python 环境工具专业版是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。执行完成后建议检查结果是否符合预期，并保留必要记录。使用与执行同时注意输入完整性、执行条件和输出可用性。从功能定位来看，该技能
手动修复签名（不推荐，仅作了解）
若不用 @wraps，可手动赋值，但易遗漏：
wrapper.__name__ = func.__name__wrapper.__doc__ = func.__doc__wrapper.__annotations__ = func.__annotations__wrapper.__module__ = func.__module__- 还需处理
__qualname__、__dict__等，容易出错
带参数的装饰器要注意什么？
多一层嵌套时，@wraps 仍要作用于最内层包装函数：
def repeat(times: int):
def decorator(func):
@wraps(func) # ← 放在 inner wrapper 上，不是外层 decorator
def wrapper(*args, **kwargs):
for _ in range(times):
result = func(*args, **kwargs)
return result
return wrapper
return decorator
漏掉这行，即使装饰器本身有参数，签名依然丢失。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
