Python装饰器为什么会丢失被装饰函数的元信息

在Python中，函数也是一个对象，它拥有许多元信息，例如函数名 __name__、文档字符串 __doc__ 等。当你编写一个装饰器来“包装”一个函数时，如果不做特殊处理，这些元信息会被装饰器内部函数的元信息覆盖。

1. 编写一个简单的装饰器来观察问题

创建一个名为 meta_issue.py 的文件，输入以下代码。这段代码定义了一个没有使用任何修复措施的装饰器 my_decorator。

def my_decorator(func):
    def wrapper():
        print("装饰器内部：正在执行被装饰函数")
        return func()
    return wrapper

@my_decorator
def say_hello():
    """这是一个简单的打招呼函数"""
    print("Hello, World!")

运行代码来检查元信息。

print(f"函数名称: {say_hello.__name__}")
print(f"函数文档: {say_hello.__doc__}")

观察输出结果。你会发现，虽然我们调用的是 say_hello 函数，但它的名称变成了 wrapper，文档字符串也变成了 None。

函数名称: wrapper
函数文档: None

2. 理解元信息丢失的根本原因

问题的核心在于装饰器的语法糖机制。

当 使用 @my_decorator 时，Python解释器实际上执行了这样一步操作：

say_hello = my_decorator(say_hello)

1. my_decorator 接收原始的 say_hello 函数作为参数 func。
2. my_decorator 定义了一个新的内部函数 wrapper，并 返回这个 wrapper 函数。
3. 原始变量 say_hello 指向了新返回的 wrapper 函数对象。

当你访问 say_hello.__name__ 时，Python 实际上是在访问 wrapper.__name__。因为 wrapper 是一个新定义的函数，它的默认名称就是 "wrapper"，且没有定义文档字符串。原始函数 func 的元信息被“埋”在闭包里，无法通过外部直接访问。

这会导致严重的副作用，例如依赖函数签名的框架（如 Flask, FastAPI）可能无法正确路由，或者文档生成工具（如 Sphinx）无法提取正确的说明。

3. 使用 functools.wraps 修复元信息丢失

Python 标准库中的 functools 模块提供了一个名为 wraps 的装饰器，专门用于解决这个问题。它本质上是一个简化版的 update_wrapper，用于将原始函数的 __module__、__name__、__qualname__、__annotations__ 和 __doc__ 属性复制到包装函数上。

修改之前的 meta_issue.py，导入 functools 模块，并 应用 @wraps(func) 到内部函数 wrapper 上。

import functools

def my_decorator(func):
    @functools.wraps(func)
    def wrapper():
        print("装饰器内部：正在执行被装饰函数")
        return func()
    return wrapper

@my_decorator
def say_hello():
    """这是一个简单的打招呼函数"""
    print("Hello, World!")

注意：@functools.wraps(func) 必须紧贴在 def wrapper(): 之上，它会在 wrapper 函数定义后立即执行属性复制。

4. 验证修复效果

再次运行检查代码。

print(f"函数名称: {say_hello.__name__}")
print(f"函数文档: {say_hello.__doc__}")

确认输出结果已经恢复正常。

函数名称: say_hello
函数文档: 这是一个简单的打招呼函数

5. 对比修复前后的差异

为了更直观地理解修复带来的变化，请参考下表。它展示了在被装饰函数 example 拥有特定元信息的情况下，使用 wraps 前后的状态对比。

特别关注最后一行的 __wrapped__ 属性。@functools.wraps 不仅复制了元信息，还在包装函数上添加了一个指向原始函数的引用。这允许你在需要的时候（例如调试或去除装饰器效果时）访问原始函数。

original_function = say_hello.__wrapped__
print(original_function.__name__)  # 输出: say_hello