装饰器原理

可视化演示

展示系统处理流水线、实时性能指标曲线及多方案对比分析，包含数据流转、吞吐延迟监控与方案评估。

装饰器本质

小明新买了一部手机，出厂时是光秃秃的裸机。裸机完全可以正常打电话、刷视频，但他总担心手滑摔坏。他走进手机壳店，挑了一个壳套上去——手机还是那部手机，功能一点没变，只是更耐摔了。在 Python 世界里，函数体就像手机，装饰器就像手机壳：它包住函数，不动内部代码，却能给函数增加“抗摔”“美观”这类新特性。

为什么 Python 能做到“包住不动内部”？因为 Python 里函数是一等公民——函数可以像整数、字符串一样被传递：能放进列表、能当参数传进另一个函数，也能被另一个函数当作结果返回。这种“接收函数或返回函数”的函数叫高阶函数。装饰器本质上就是一个高阶函数：塞进去的是原函数，吐出来的是被包装过的新函数。

最常见的写法是用 @ 语法糖：

@ 只是一个语法缩写，让代码更可读。完整看：timer 接收 work 函数 → 构造一个新的 wrapper 函数 → 把 wrapper 重新赋给 work 这个名字。此后调用 work()，实际执行的是 wrapper()，而 wrapper 内部又调用原来的 work。

$$\text{@decorator} \equiv \text{func} = \text{decorator}(\text{func})$$

1. 语法糖标记：@ 写在函数定义上方，表示“把这函数交给装饰器处理”。

$$\text{@decorator}$$

2. 重新绑定：func = 表示原函数名最终被重新指向新函数。

$$\text{func} =$$

3. 函数调用：decorator(func) 把原函数作为参数传入，返回包装后的新函数。

$$\text{decorator}(\text{func})$$

手机壳店老板干的活和装饰器一模一样：你递给他一部裸机，他加工出一个套了壳的手机，再交到你手上——从此你手里这部手机，外壳变了，灵魂还是原来的灵魂。

@timerdef work():    pass# 等价于 work = timer(work)

闭包机制

手机壳内部有一层缓冲棉，这层棉和你的手机轮廓“咬合”在一起，即使壳被拿远，棉依然记得手机的形状。Python 的闭包就是这层“记忆棉”：它让内层函数牢牢记住外层函数的局部变量，哪怕外层函数已经执行完毕。

装饰器的核心是“外函数包裹内函数”。外层函数执行时定义了内层函数，内层函数里用到了外层函数的局部变量——这种“内函数 + 被捕获的外层变量”的组合，就叫闭包。看这段代码：

outer 的局部变量 x 在 inner 中被引用。outer 执行完返回 inner 后，理论上 x 的栈帧应该被销毁，但 Python 发现 x 被 inner 捕获了，就把 x 一起打包进 inner 的闭包环境里。之后只要调用 inner()，x 就奇迹般地还在。

$$\text{inner} = \text{outer}(x), \quad x \text{ is captured}$$

1. 外层调用：outer(x) 带着参数 x 被执行，x 是外层局部变量。

$$\text{outer}(x)$$

2. 返回内层：inner = 表示 outer 返回的是函数 inner，而不是普通数值。

$$\text{inner} =$$

3. 捕获变量：x is captured 指 inner 引用了 x，x 被保存进 inner 的闭包环境。

$$\text{x is captured}$$

这就像手机壳的缓冲棉：它是在“套壳”这个动作发生时装进去的，但壳做好后，就算生产线把手机拿走，棉层依然记得手机的轮廓。装饰器里被捕获的外层变量通常就是原函数 func——wrapper 里随时能调用原函数，正是闭包在背后撑着。

def outer(x):    def inner():      # 内层函数        return x + 1  # 引用外层变量 x    return inner      # 把内层函数返回出去

元信息丢失

你买了一部 iPhone 15，套上一个全包裹壳后，翻到手机背面，看到的不是 “iPhone 15“，而是壳上印的 ”shell-style v2“。手机还是那台手机，但”身份标识”看不到了。函数也有身份标识——__name__、__doc__ 这些内置属性。__name__ 是函数名，__doc__ 是函数开头的文档字符串。一旦被装饰器包装，这些属性就悄悄变了。

因为 greet 这个名字被重新绑定到 wrapper 上了，而 wrapper 是装饰器内部临时造出来的函数，它没有自己的名字和文档字符串。对调试来说这是灾难：异常堆栈里出现一串 wrapper，日志统计时根本分不清是哪个业务函数出了问题。

$$\text{decorated}.\_\_name\_\_ = \text{'wrapper'} \neq \text{original}.\_\_name\_\_$$

1. 装饰结果：decorated 是被装饰后的函数对象。

$$\text{decorated}$$

2. 名字属性：__name__ 是函数的“身份证姓名”属性。

$$\text{.\_\_name\_\_}$$

3. 标签替换：它变成了 wrapper——装饰器内部临时函数的默认名字。

$$\text{= 'wrapper'}$$

4. 身份错位：与原函数 original.__name__ 已经不同。

$$\neq \text{original}.\_\_name\_\_$$

壳把型号标签盖住了，用户不知道这手机其实是 iPhone 15。如果再叠几层壳，每层都叫 wrapper，那就是手机被套了三层壳，每层都写着 "unknown model"——调试的人想找都找不到原机。

@timerdef greet():    """向世界问好"""    print('hi') print(greet.__name__)  # wrapper，而不是 greet！print(greet.__doc__)   # None！

functools.wraps

好的手机壳会在摄像头、充电口、按键位置精准预留开口。用 functools.wraps 就相当于在壳上按原手机的位置开孔，让摄像头（__name__）和呼吸灯（__doc__）重新露出来。它是标准库给我们的“开孔工具”。

@wraps(func) 底层调用 functools.update_wrapper(wrapper, func)。update_wrapper 默认把 func 的 __name__、__doc__、__module__、__qualname__ 等复制到 wrapper，还会同步 __dict__。结果：greet.__name__ 恢复成 greet。

$$\text{@wraps}(\text{func}) \equiv \text{update\_wrapper}(\text{wrapper},\ \text{func})$$

1. wraps 使用：@wraps(func) 装饰内层 wrapper，参数是原函数。

$$\text{@wraps}(\text{func})$$

2. 等价实现：它本质上等价于调用 update_wrapper。

$$\equiv \text{update\_wrapper}$$

3. 复制方向：(wrapper, func) 表示把 func 的元信息复制给 wrapper，方向是从原函数到包装函数。

$$\text{update\_wrapper}(\text{wrapper},\ \text{func})$$

戴上“预留开口”的手机壳后，翻到背面依然能看见 "iPhone 15" 的型号名。用户完全不觉得这部手机被套过壳，用起来和裸机一模一样，但实际已经获得了防摔保护。

from functools import wraps def timer(func):    @wraps(func)  # 把 func 的元信息复制给 wrapper    def wrapper(*args, **kwargs):        ...    return wrapper

带参装饰器

普通手机壳是“通版”，但有人想要印上自己名字的定制壳。通版壳工厂（装饰器）不够用，需要“定制壳工厂”——先接收“名字”这个参数，再产出对应的壳。有时候装饰器自己需要参数（比如重试次数、日志级别），这时 @timer 就变成 @timer(level='debug')，写法上多一层。

三层函数各司其职：repeat(times) 是工厂，接收配置参数，返回真正的装饰器；decorator(func) 接收原函数，返回 wrapper；wrapper 是最终代替原函数执行的新函数。注意 times 同样被闭包捕获，存在于每一层里。

$$\text{repeat}(\text{times}) \to \text{decorator}(\text{func}) \to \text{wrapper}$$

1. 工厂层：repeat(times) 接收配置参数 times。

$$\text{repeat}(\text{times})$$

2. 装饰器层：返回的 decorator 接收原函数 func。

$$\text{decorator}(\text{func})$$

3. 包装层：最终产出 wrapper，替代原函数执行。

$$\text{wrapper}$$

定制壳工厂的流水线是：你提交“印名字 XYZ”的需求 → 工厂按需生成版型 → 把手机套进版型。每次 @repeat(3) 都是一条定制流水线，3 就是夹在壳层里的定制信息。

def repeat(times):          # 第一层：工厂    def decorator(func):    # 第二层：真正的装饰器        @wraps(func)        def wrapper(*args, **kwargs):  # 第三层：包装函数            for _ in range(times):                func(*args, **kwargs)        return wrapper    return decorator @repeat(3)def say(): ...

多层装饰

套了壳还要贴膜，贴了膜还要挂手机链。一层叠一层，每层各管一件事。一个函数可以同时被多个装饰器装饰，顺序和执行时机有讲究。

从下往上装饰：timer 先包住 work，log 再包住 timer(work)。调用时从外往里执行：log 先打日志 → 调用 timer 包装的函数 → timer 计时 → 调用真正的 work。所以口诀是：“装饰自下而上，执行自外向内”。

$$\text{@log}\ \text{@timer} \equiv \text{work} = \text{log}(\text{timer}(\text{work}))$$

1. 叠罗汉：@log 在上、@timer 在下，离函数最近的先被应用。

$$\text{@log}\ \text{@timer}$$

2. 先包内层：timer(work) 先用计时壳包住原函数。

$$\text{timer}(\text{work})$$

3. 再包外层：log(...) 再把日志壳包在最外面。

$$\text{log}(\text{timer}(\text{work}))$$

4. 重绑定：work 最终指向最外层包装函数。

$$\text{work} =$$

贴膜后壳上落灰，链子又在膜外面摇晃；收拾时却得先摘链、再揭膜、最后才脱壳。执行顺序和装饰顺序正好相反。这提醒我们：叠加装饰器时，越通用的逻辑越要放在外层。

@log@timerdef work(): ...# 等价于 work = log(timer(work))

工业应用

手机壳产业已经标准化：防摔、防水、磁吸，每款壳都留开口、标型号。工业级装饰器也一样，成体系的写法让“给函数加装备”变成流水线操作。真实系统中最常见的四类用途是日志记录、性能计时、权限校验、结果缓存。

• 日志与鉴权：@login_required 包装 Web 视图函数，先验证登录态再执行业务；@check_quota 校验 API 配额。

• 性能计时：@timer 包裹耗时接口，自动上报单次调用耗时，形成监控曲线。

• 结果缓存：@lru_cache 和自定义 @cache 先查缓存，未命中才执行原函数，大幅降低重复计算。

• 最佳实践：① 一律 @wraps(func)；② wrapper 参数统一用 (*args, kwargs) 透传；③ 一个装饰器只做一件事；④ 装饰器内部保持小函数、内聚。

这样即使 100 个接口都加了装饰器，异常堆栈依然清晰可辨。

$$T_{\text{decorated}} = T_{\text{original}} + O(1)$$

1. 总耗时：T_decorated 是加壳后每次调用的总耗时。

$$T_{\text{decorated}}$$

2. 原函数耗时：T_original 是函数本身纯粹的业务耗时。

$$T_{\text{original}}$$

3. 恒定开销：O(1) 指壳层增加的日志、鉴权、缓存检查时间，是常量级。

$$O(1)$$

标准化壳厂出货的每一个壳都开孔、都标型号，于是生产线上的每一部手机都能既享受保护又保持身份。工程师遵循同样的规范，写出一个个“标准壳”，让横切逻辑以统一姿态嵌入业务函数。

AI 应用场景

Python 演示

"""装饰器原理演示：闭包 + 高阶函数 + functools.wraps运行: python decorator_demo.py"""from functools import wrapsimport time  def timer_without_wraps(func):    """不带 @wraps 的计时装饰器（元信息会丢失）"""    def wrapper(*args, **kwargs):        start = time.perf_counter()        result = func(*args, **kwargs)        elapsed = time.perf_counter() - start        print("[timer] {:.4f}s".format(elapsed))        return result    return wrapper  def timer_with_wraps(func):    """带 @wraps 的计时装饰器（保留 __name__ / __doc__）"""    @wraps(func)    def wrapper(*args, **kwargs):        start = time.perf_counter()        result = func(*args, **kwargs)        elapsed = time.perf_counter() - start        print("[timer] {:.4f}s".format(elapsed))        return result    return wrapper  def repeat(times):    """带参装饰器工厂：让函数重复执行 times 次"""    def decorator(func):        @wraps(func)        def wrapper(*args, **kwargs):            for i in range(times):                print("  run {}/{}".format(i + 1, times))                func(*args, **kwargs)        return wrapper    return decorator  @timer_without_wrapsdef bad_greet():    """向世界问好（元信息会丢失）"""    print("hello world")  @timer_with_wraps@repeat(3)def good_greet():    """向世界问好（元信息被保留）"""    print("hello world")  def main():    print("== 不使用 @wraps ==")    bad_greet()    print("bad_greet.__name__ =", bad_greet.__name__)    print("bad_greet.__doc__ =", bad_greet.__doc__)    print()    print("== 使用 @wraps ==")    good_greet()    print("good_greet.__name__ =", good_greet.__name__)    print("good_greet.__doc__ =", good_greet.__doc__)  if __name__ == "__main__":    main()

1. def wrapper(*args, **kwargs):wrapper 是手机壳本体，*args, **kwargs 保证任何形状的手机都能套进去。
2. @wraps(func)在壳上按原机型开孔，把 __name__ 和 __doc__ 复制到壳上。
3. def repeat(times):定制壳工厂的第一层：先接收“3 次”这个参数。
4. return wrapper工厂出货：把包装好的新函数交回给 Python 运行时。
5. @timer_with_wraps @repeat(3)先贴膜再套壳；调用时先走计时壳，再走进门壳里的重复逻辑。
6. bad_greet.__name__读一读壳上的标签，发现没开孔时标签悄悄变成了 wrapper。
7. good_greet.__doc__有开孔的壳保留了原文档字符串“向世界问好（元信息被保留）”。

常见误区

面试题