《Python 装饰器进阶指南：正名之术与 functools.wraps 的魔法》

《Python 装饰器进阶指南：正名之术与 functools.wraps 的魔法》

---

一、引言：装饰器的魅力与陷阱

在 Python 的世界里，装饰器是一种优雅而强大的语法糖。它让我们可以在不修改原函数代码的前提下，动态地添加功能，比如日志记录、权限验证、性能分析等。正因如此，装饰器在 Web 开发、数据处理、自动化脚本等场景中被广泛应用。

但在使用装饰器的过程中，许多开发者会遇到一个隐蔽却关键的问题：被装饰函数的元信息丢失。这不仅影响调试和文档生成，还可能导致框架行为异常。本文将深入剖析这个问题，并通过 functools.wraps 的“正名之术”来解决它。

---

二、问题重现：装饰器为何“篡改”函数身份？

我们先来看一个简单的装饰器示例：

def simple_decorator(func):
    def wrapper(*args, **kwargs):
        print("函数即将执行...")
        return func(*args, **kwargs)
    return wrapper

@simple_decorator
def greet(name):
    """向用户打招呼"""
    print(f"你好，{
     
     name}！")

greet("小明")
print(greet.__name__)  # 输出 wrapper
print(greet.__doc__)   # 输出 None

❗问题分析：

• 原函数 greet 的 __name__ 被替换成了 wrapper。
• 原函数的 __doc__（文档字符串）也丢失了。
• 如果你使用 help(greet) 或自动文档工具（如 Sphinx），将无法获取正确的函数信息。

这就是装饰器的“副作用”：它返回的是一个新函数对象，原函数的元信息没有被保留。

---