为什么Python装饰器会丢失函数元数据？用functools.wraps解决

一、现象直击：装饰器如何让函数“失去身份”

在编写性能监控、日志审计或权限验证逻辑时，开发者经常会自定义装饰器。以下是一个常见的函数执行计时装饰器示例：

import time

def timer(func):
    def wrapper(*args, **kwargs):
        """计时包装层函数"""
        start = time.perf_counter()
        result = func(*args, **kwargs)
        duration = time.perf_counter() - start
        print(f"[耗时统计] 函数耗时: {duration:.6f}s")
        return result
    return wrapper

@timer
def calculate_tax(base_salary: float, tax_rate: float = 0.1) -> float:
    """计算应纳个人所得税税额。"""
    time.sleep(0.05)
    return base_salary * tax_rate

被 @timer 修饰后，业务函数 calculate_tax 可以正常调用并输出耗时，但在执行内省（Introspection）时却出现了意外的现象：

# 检查函数的基本自省属性
print("函数名称:", calculate_tax.__name__)
print("文档说明:", calculate_tax.__doc__)
print("类型注解:", calculate_tax.__annotations__)

可以看到，原函数的元数据几乎全部丢失，函数的真实名称变成了内部通用的 wrapper，原始业务文档被替换成了包装层的说明，参数注解也变成了空字典。

二、根本原因：符号重绑与闭包包装函数的本质

要理解元数据丢失的原因，必须回归 Python 语法糖的本质。Python 中用 @ 修饰函数的语法：

@timer
def calculate_tax(base_salary, tax_rate=0.1):
    ...

在语法解析层面完全等价于显式赋值调用：

calculate_tax = timer(calculate_tax)

这个过程可以精确拆解为以下三个步骤：

1. 原函数创建：Python 解释器在内存中创建名为 calculate_tax 的函数对象（假设位于堆内存地址 0x101），此时该对象拥有一整套完整的属性：__name__ = 'calculate_tax'、__doc__ = '计算应纳个人所得税税额。' 以及参数注解等。
2. 装饰器执行：解释器调用 timer(calculate_tax)。在 timer 内部，解释器新定义了一个闭包函数 wrapper（位于内存地址 0x202），它的 __name__ 自然是 'wrapper'，原函数对象 calculate_tax 则被保存在 wrapper 的闭包单元（__closure__）中。随后，timer 返回了 wrapper 的对象引用。
3. 标识符重绑：模块全局作用域中的变量名 calculate_tax 被重新绑定到了新返回的 wrapper 对象（0x202）上。

因此，修饰完成后，代码中访问的 calculate_tax 实质上是 wrapper 对象。所有对 calculate_tax.__name__ 或 help(calculate_tax) 的访问，自然读取的都是 wrapper 自身的属性。

三、解决方案：使用 functools.wraps 恢复元数据

Python 标准库 functools 模块提供了开箱即用的装饰器 @wraps，专门用于解决这一问题。

标准修复实现代码

修复方式非常简明：在 wrapper 函数定义的上方，添加 @wraps(func)。

import time
from functools import wraps

def timer(func):
    @wraps(func)  # 关键修复点：将原函数 func 的元数据自动拷贝到 wrapper 上
    def wrapper(*args, **kwargs):
        """计时包装层函数"""
        start = time.perf_counter()
        result = func(*args, **kwargs)
        duration = time.perf_counter() - start
        print(f"[耗时统计] 函数耗时: {duration:.6f}s")
        return result
    return wrapper

@timer
def calculate_tax(base_salary: float, tax_rate: float = 0.1) -> float:
    """计算应纳个人所得税税额。"""
    time.sleep(0.05)
    return base_salary * tax_rate

结果验证

再次打印 calculate_tax 的元数据，观察输出结果：

print("函数名称:", calculate_tax.__name__)
print("限定名称:", calculate_tax.__qualname__)
print("文档说明:", calculate_tax.__doc__)
print("类型注解:", calculate_tax.__annotations__)
print("原始函数引用:", calculate_tax.__wrapped__)

可以看到，原函数的名称、限定名、文档说明和类型注解全部恢复正常，同时还额外获得了指向无修饰原函数的 __wrapped__ 属性。

四、原理解析：functools.wraps 底层做了什么？

functools.wraps 并非黑魔法，它本质上是一个调用 functools.update_wrapper 的便捷装饰器工厂。在 Python 官方源码中，它的实现非常凝练：

# 标准库 functools 中的实现逻辑原型
WRAPPER_ASSIGNMENTS = ('__module__', '__name__', '__qualname__', '__doc__',
                       '__annotations__')
WRAPPER_UPDATES = ('__dict__',)

def update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES):
    for attr in assigned:
        try:
            value = getattr(wrapped, attr)
        except AttributeError:
            pass
        else:
            setattr(wrapper, attr, value)
    for attr in updated:
        getattr(wrapper, attr).update(getattr(wrapped, attr, {}))
    # 建立回溯链条
    wrapper.__wrapped__ = wrapped
    return wrapper

def wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES):
    return partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)

通过源码分析，functools.wraps 在底层执行了三件关键工作：

__wrapped__ 的巨大价值：直接访问无修饰函数

在编写单元测试或集成测试时，有时我们只希望测试函数的纯业务逻辑，而不希望触发装饰器内部的切面行为（例如缓存读取、权限校验或网络请求）。借助 __wrapped__，可以直接跳过装饰器：

# 1. 正常调用：带有耗时统计
result1 = calculate_tax(10000, 0.2)

# 2. 绕过装饰器：直接调用未修饰的原函数（无耗时统计输出）
raw_func = calculate_tax.__wrapped__
result2 = raw_func(10000, 0.2)

assert result1 == result2

五、典型进阶场景与使用细节

1. 带参数的装饰器中的正确放置位置

当装饰器本身需要接收配置参数时，通常需要嵌套三层函数。初学者经常容易混淆 @wraps 应该修饰哪一层：

def repeat(num_times: int):
    """外层 1：接收装饰器参数"""
    def decorator(func):
        """外层 2：接收被修饰的原函数"""
        @wraps(func)  # 正确：必须修饰最内层最终执行调用的 wrapper！
        def wrapper(*args, **kwargs):
            """最内层：实际替换原函数的执行入口"""
            for _ in range(num_times - 1):
                func(*args, **kwargs)
            return func(*args, **kwargs)
        return wrapper
    return decorator

判断准则：哪个函数最终替代原函数被外部调用并返回，@wraps(func) 就必须紧贴声明在哪个函数正上方。

2. 类装饰器中的元数据处理

如果装饰器是用类（基于 __call__）实现的，无法直接用 @wraps(func) 修饰实例方法。此时应在类的 __init__ 中直接调用 functools.update_wrapper(self, func)：

from functools import update_wrapper

class MetricCollector:
    def __init__(self, func):
        self.func = func
        # 手动同步元数据到实例对象 self 上
        update_wrapper(self, func)

    def __call__(self, *args, **kwargs):
        print(f"[监控打点] 正在调用: {self.__name__}")
        return self.func(*args, **kwargs)

@MetricCollector
def process_data(data: list):
    """数据批处理管道"""
    return [x * 2 for x in data]

print(process_data.__name__)  # 输出: process_data
print(process_data.__doc__)   # 输出: 数据批处理管道

六、总结与工程规范清单

函数元数据丢失并非 Python 运行时的故障，而是“装饰器语法糖本质是引用重绑”这一机制带来的自然结果。为了确保代码在自省、文档生成、测试以及现代 Web 框架中的稳健运行，建议在日常开发中遵守以下工程规范：

• 编写闭包即加 wraps：只要在装饰器内部定义了替代原函数执行的 wrapper，第一行必须写上 @wraps(func)。
• 透传参数不遗漏：内部 wrapper 函数的形参和调用应保持 *args, **kwargs 的完全透传，确保类型提示与参数反射不受阻碍。
• 单元测试优先解包：对于包含复杂副作用（如鉴权、网络、重试）的装饰函数，单元测试中优先借助 func.__wrapped__ 或 inspect.unwrap(func) 对原业务逻辑进行纯净隔离测试。
• 类装饰器使用 update_wrapper：在基于类的装饰器中，在 __init__ 构造函数中显式执行 update_wrapper(self, func)。