38｜装饰器如何包装函数

这套课程按知识依赖排列。本篇的前置知识是：第 22、23、27 篇。学完后，你应该能够理解函数被包装后的调用顺序。

本篇要解决的问题

本篇只处理“装饰器如何包装函数”这一件事。示例基于 Python 3.14.6，在 macOS 环境核验；除明确标注的终端命令外，代码本身只使用 Python 标准能力。

先看清一个容易误解的细节

装饰器接收原函数并返回包装函数。名称重新绑定后，调用看似仍是原函数名，实际会先进入包装层，再决定何时调用原函数。

核心概念

• @trace 等价于 add = trace(add)。
• 包装函数必须返回原函数结果，否则调用语义会被改变。
• functools.wraps 保留原函数名称和文档信息。

跟着示例运行

把下面代码保存到本课脚本并运行：

from functools import wraps

def trace(function):
    @wraps(function)
    def wrapper(*args, **kwargs):
        print("开始：", function.__name__)
        result = function(*args, **kwargs)
        print("结束：", function.__name__)
        return result
    return wrapper

@trace
def add(left, right):
    return left + right

print(add(2, 3))

预期结果：

开始： add
结束： add
5

输出中包含环境路径、集合元素或日志格式时，具体文字和顺序可能随本机环境变化；判断是否成功应以本篇说明的关键结果为准。

按执行顺序拆开看

1. 解释器执行定义时，把原 add 函数交给 trace，返回的 wrapper 重新绑定到名字 add。
2. 调用时先进入包装函数，包装函数再调用原函数、取得结果并原样返回。

再看一个具体细节

装饰器语法看起来特殊，但可以还原成普通赋值。

@trace 位于函数定义上方，效果等价于定义结束后执行 add = trace(add)。

初学者容易混淆的地方

• 包装函数忘记返回原函数结果，调用方得到 None。
• 装饰器叠加过多且修改隐藏行为，使调用路径难以追踪；基础项目优先保持层数少。

练习

1. 编写只记录调用次数的简单装饰器。
2. 删除包装函数的 return result，观察调用方得到什么。

练习应先独立完成，再通过增加 print 输出或检查文件内容观察中间状态。当前课程尚未讲到的能力，不要求提前搜索复杂写法。

本篇边界

本篇目标是理解函数被包装后的调用顺序。没有展开的高级机制会放到后续课程；先确保能够解释示例中每一行代码，再进入下一篇。