Python装饰器是什么：从闭包原理到语法糖的执行流程

Python 装饰器本质上是一个接收函数作为输入、并返回一个替换函数（或可调用对象）的高阶函数。它能够在不修改原函数代码以及调用方式的前提下，为函数动态增加日志记录、执行计时、权限校验或缓存等横向通用功能。理解装饰器的关键，在于掌握 Python 中“函数是一等公民”的特性、自由变量绑定的闭包原理，以及 @ 语法糖在代码导入解析期与运行调用期的精确流转机制。

一、基石：函数作为一等公民与闭包机制

在 Python 中，函数与其他基本数据类型（如整数、字符串、列表）地位完全相同，被称为“一等公民”。这意味着函数可以赋值给变量、作为实参传递给另一个函数，也可以作为另一个函数的返回值。这种特性为高阶函数提供了可能。

当一个嵌套定义的内部函数引用了外部非全局作用域中的变量时，即使外部函数已经执行完毕并退出，内部函数仍然保留对该外部作用域变量的绑定，这种结构便称为闭包（Closure）。被引用的外部变量被称为自由变量（Free Variable），保存在内部函数的 __closure__ 单元属性中。

def make_multiplier(factor):
    # factor 为外部函数作用域中的变量
    def multiply(x):
        # 内部函数引用了外部的自由变量 factor
        return x * factor
    return multiply

double = make_multiplier(2)
print("示例输出: 5 * 2 =", double(5))  # 输出 10

图 1：闭包中外部局部变量通过 Cell 单元转为自由变量保留在内存中的机制

二、装饰器的本质：闭包在函数替换中的应用

装饰器正是利用了高阶函数与闭包：外部装饰函数接收被装饰的原始函数 func，在其内部定义一个包装函数 wrapper。wrapper 内部不仅可以执行额外逻辑，还可以直接调用 func，最后外部装饰函数将 wrapper 返回，完成变量名与新函数的绑定。

如果不使用任何专门语法，最原始的手动装配方式如下：

def my_decorator(func):
    def wrapper(*args, **kwargs):
        print("[日志] 函数准备执行...")
        result = func(*args, **kwargs)
        print("[日志] 函数执行完毕。")
        return result
    return wrapper

def greet(name):
    print("你好，" + name)

# 手动应用装饰器：原函数名重新绑定到 wrapper 对象
greet = my_decorator(greet)

# 执行调用
greet("小明")
# 示例输出：
# [日志] 函数准备执行...
# 你好，小明
# [日志] 函数执行完毕。

在上述代码中，greet = my_decorator(greet) 这一步是核心。原本指向 greet 原始函数体的标识符，被重新指向了 my_decorator 返回的 wrapper 函数。而 wrapper 作为一个闭包，记住了被传入的原始 greet。

三、语法糖 @ 的执行流程：定义期与调用期

Python 提供了 @ 符号作为装饰器的专用语法糖。@my_decorator 只是在编译与载入阶段将上述手动重新绑定的赋值过程自动化，其运行逻辑分为清晰的两个阶段：定义期执行与调用期执行。

@my_decorator
def greet(name):
    print("你好，" + name)

# 等价于在定义完成的瞬间自动执行：
# greet = my_decorator(greet)

图 2：@ 语法糖在定义期（替换绑定）与调用期（拦截代理）的详细步骤分解

四、进阶模式：带参数装饰器与多层堆叠

在实际工程中，常常需要向装饰器本身传递配置参数，或者在同一个函数上叠加多个装饰器。

1. 带参数的装饰器（三层嵌套）

如果装饰器本身需要接收参数（例如 @repeat(num=3)），则需要再向外包装一层函数。最外层函数负责接收装饰器配置参数，中间层函数接收原函数，最内层函数负责具体执行代理。

def repeat(num):
    def decorator(func):
        def wrapper(*args, **kwargs):
            result = None
            for _ in range(num):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(num=3)
def ping():
    print("pong")

# 语法糖执行等价于：
# ping = repeat(num=3)(ping)

2. 多装饰器的堆叠顺序

当一个函数同时被多个装饰器修饰时，其装配顺序是由下至上（从内到外），而实际执行包装调用的顺序则是从上至下（外层优先）：

@dec_a
@dec_b
def work():
    pass

# 装配等价于：work = dec_a(dec_b(work))

图 3：多层装饰器的洋葱包裹模型：装配方向与实际调用执行方向的关系

五、规范与总结：元信息丢失与最佳实践

由于装饰器将原函数名重新绑定到了 wrapper，如果不做特殊处理，被装饰函数的 __name__、__doc__ 等元信息都会变成 wrapper，这会严重破坏反射机制和自动化文档工具。

标准库提供了 functools.wraps 装饰器，专门用于将原函数的元信息拷贝回 wrapper 中。编写任何工业级装饰器时，都应当养成始终添加 @functools.wraps(func) 的习惯。

import functools
import time

def timer(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        duration = time.perf_counter() - start
        print(f"[耗时统计] {func.__name__} 执行耗时: {duration:.4f}s")
        return result
    return wrapper

@timer
def compute():
    """执行复杂数值计算"""
    return sum(i * i for i in range(100_000))

print("函数名:", compute.__name__)  # 正确保留输出: compute
print("文档说明:", compute.__doc__)   # 正确保留输出: 执行复杂数值计算

图 4：Python 装饰器从语言原理到生产实践的核心知识体系总结