跳到主内容

LangChain Python

最后更新: 2026-10-11

1. 包装

装饰器(decorator)是一种接收函数、再返回新函数的高阶函数。新函数通常会先执行一些附加逻辑,再调用原函数。

例如,很多函数都需要记录「开始执行」和「执行结束」。如果每个函数都手动写一遍,代码会重复。可以把这段公共逻辑放进装饰器:

log-decorator.py
01
def log_call(function):
02
def wrapper():
03
print("开始执行")
04
result = function()
05
print("执行结束")
06
return result
07
08
return wrapper
09
10
def greet():
11
print("你好,Python")
12
13
greet = log_call(greet)
14
greet()

log_call() 接收原来的 greet,返回一个新的 wrapper。重新赋值后,调用 greet() 实际上是在调用包装函数,原来的问候逻辑仍然由 function() 执行。

装饰器的重点是「在不修改原函数主体的情况下,为它增加行为」。日志、计时、权限检查、缓存和重试都适合抽成这种公共包装逻辑。

2. 语法

Python 提供 @ 语法,让装饰器的使用更直观:

at-syntax.py
01
def log_call(function):
02
def wrapper():
03
print("开始执行")
04
result = function()
05
print("执行结束")
06
return result
07
08
return wrapper
09
10
@log_call
11
def greet():
12
print("你好,Python")
13
14
greet()

函数定义前的 @log_call 等价于下面的重新赋值:

equivalent.py
01
def log_call(function):
02
def wrapper():
03
print("开始执行")
04
result = function()
05
print("执行结束")
06
return result
07
08
return wrapper
09
10
def greet():
11
print("你好,Python")
12
13
greet = log_call(greet)
14
greet()

装饰器在函数定义完成时执行一次,而不是每次调用函数时重新执行。也就是说,模块加载过程中先创建 greet,再调用 log_call(greet) 得到新的函数;以后每次 greet() 都只调用已经生成的包装函数。

这也解释了装饰器的两个调用阶段:装饰阶段接收函数并返回包装函数,运行阶段才由包装函数接收真正的业务参数。

3. 参数

真实函数通常有位置参数、关键字参数和返回值,包装函数应该使用 *args 与 **kwargs 接收它们,并把结果返回给调用方:

universal-wrapper.py
01
from functools import wraps
02
03
def log_call(function):
04
@wraps(function)
05
def wrapper(*args, **kwargs):
06
print(f"开始执行:{function.__name__}")
07
result = function(*args, **kwargs)
08
print(f"执行结束:{function.__name__}")
09
return result
10
11
return wrapper
12
13
@log_call
14
def add(left, right):
15
return left + right
16
17
print(add(2, right=3)) # 5

*args 收集位置参数,**kwargs 收集关键字参数;调用原函数时再次展开它们,才能保持原函数的调用方式。return result 也很重要,否则装饰后的函数会丢失原来的返回值。

@wraps(function) 来自 functools,它会把原函数的名称、文档字符串等信息复制到包装函数上。没有它时,add.__name__ 会变成 wrapper,调试、日志和框架读取函数信息时都不够准确。

包装函数还可以处理异常,但不要无意中吞掉异常。下面的 finally 无论成功还是失败都会执行,原异常仍然会继续抛出:

exception-wrapper.py
01
from functools import wraps
02
03
def log_result(function):
04
@wraps(function)
05
def wrapper(*args, **kwargs):
06
try:
07
return function(*args, **kwargs)
08
finally:
09
print(f"调用完成:{function.__name__}")
10
11
return wrapper
12
13
@log_result
14
def divide(left, right):
15
return left / right
16
17
print(divide(6, 2))

4. 配置

有时装饰器本身也需要参数,例如希望调用函数三次。此时需要多包一层:最外层接收配置,中间层接收函数,最内层才接收业务参数:

repeat-decorator.py
01
from functools import wraps
02
03
def repeat(times):
04
def decorator(function):
05
@wraps(function)
06
def wrapper(*args, **kwargs):
07
result = None
08
for _ in range(times):
09
result = function(*args, **kwargs)
10
11
return result
12
13
return wrapper
14
15
return decorator
16
17
@repeat(3)
18
def greet(name):
19
print(f"你好,{name}")
20
21
greet("小明")

@repeat(3) 并不是把数字直接传给 greet()。它会先执行 repeat(3),得到 decorator;再用 decorator(greet) 得到最终的 wrapper。调用 greet("小明") 时,wrapper 才会循环调用原函数三次。

装饰器配置还可以用于权限检查。把权限名称提前传入后,同一个装饰器工厂就能生成不同规则:

permission-decorator.py
01
from functools import wraps
02
03
def require_role(required_role):
04
def decorator(function):
05
@wraps(function)
06
def wrapper(user, *args, **kwargs):
07
if user["role"] != required_role:
08
raise PermissionError("没有执行权限")
09
10
return function(user, *args, **kwargs)
11
12
return wrapper
13
14
return decorator
15
16
@require_role("admin")
17
def delete_article(user, article_id):
18
return f"已删除文章 {article_id}"
19
20
admin = {"name": "小明", "role": "admin"}
21
print(delete_article(admin, 10))

在 FastAPI 项目中,鉴权、日志和限流也可以采用类似思路。不过框架通常已经提供了依赖注入或中间件机制,应该先使用框架的标准能力,再决定是否自定义装饰器。

5. 组合

一个函数可以同时使用多个装饰器。装饰器从下往上应用,但调用时从上往下进入:

stacked.py
01
from functools import wraps
02
03
def uppercase(function):
04
@wraps(function)
05
def wrapper(*args, **kwargs):
06
return function(*args, **kwargs).upper()
07
08
return wrapper
09
10
def add_prefix(function):
11
@wraps(function)
12
def wrapper(*args, **kwargs):
13
return "结果:" + function(*args, **kwargs)
14
15
return wrapper
16
17
@add_prefix
18
@uppercase
19
def message():
20
return "hello"
21
22
print(message()) # 结果:HELLO

上面的写法等价于:

stacked-equivalent.py
01
from functools import wraps
02
03
def uppercase(function):
04
@wraps(function)
05
def wrapper(*args, **kwargs):
06
return function(*args, **kwargs).upper()
07
08
return wrapper
09
10
def add_prefix(function):
11
@wraps(function)
12
def wrapper(*args, **kwargs):
13
return "结果:" + function(*args, **kwargs)
14
15
return wrapper
16
17
def message():
18
return "hello"
19
20
message = add_prefix(uppercase(message))
21
print(message()) # 结果:HELLO

调用 message() 时,先进入外层的 add_prefix 包装函数;它内部再调用 uppercase 包装函数,最后才执行原始的 message。装饰器较多时,要注意顺序,因为交换顺序可能改变最终结果。

Python 自带和标准库中也有很多装饰器,例如类文章中介绍过的 @property、@classmethod、@staticmethod,以及数据类使用的 @dataclass。它们本质上都在函数或类定义完成时,对定义结果进行包装或改造。

异步函数需要使用异步包装函数,否则包装器无法正确等待原函数:

async-decorator.py
01
import asyncio
02
from functools import wraps
03
04
def log_async(function):
05
@wraps(function)
06
async def wrapper(*args, **kwargs):
07
print("异步任务开始")
08
result = await function(*args, **kwargs)
09
print("异步任务结束")
10
return result
11
12
return wrapper
13
14
@log_async
15
async def greet(name):
16
await asyncio.sleep(0)
17
return f"你好,{name}"
18
19
async def show_result():
20
print(await greet("小明"))

在 FastAPI 的异步接口中调用 await show_result(),就会实际等待装饰后的函数;异步开始、结束和问候结果也会依次输出。浏览器案例已经运行在事件循环中,直接使用 await,无需再调用 asyncio.run()。

这类装饰器适合 FastAPI 的异步接口或异步 LangChain 调用。同步函数和异步函数不能直接使用同一种包装方式,需要保持 async 和 await 的调用模型一致。

6. 取舍

装饰器适合给多个函数增加相同的横切逻辑,但它也会增加调用链的间接层。看到一个被装饰的函数时,读者需要跳转到装饰器才能了解完整行为。

可以按照下面的原则判断是否使用装饰器:

  • 多个函数都需要相同的日志、计时、权限或重试逻辑时,适合使用装饰器;
  • 业务逻辑只出现一次,直接写在函数中通常更容易理解;
  • 装饰器应该保持职责单一,不要在一个包装器里同时完成鉴权、缓存和异常转换;
  • 尽量使用 @wraps,保留原函数的名称和文档信息;
  • 包装函数要正确传递参数、返回值和异常;
  • 为异步函数编写装饰器时,要使用 async def 和 await;
  • FastAPI 等框架已经提供中间件或依赖注入时,优先采用框架的标准扩展点。

装饰器不是为了让代码看起来更高级,而是为了把重复的外围逻辑集中维护。只要增加的抽象让调用关系更难理解,就应该考虑改回普通函数或使用更明确的服务对象。

7. 在线装饰器实验

本篇把前面的知识放进一个可修改的 Python 项目。main.py 只负责接收参数并调用实验函数,decorators_demo.py 保存本篇的逻辑。默认接口不需要密钥,也不会调用外部模型。

目录结构
使用上下方向键浏览目录,左右方向键展开或收起,Enter 或空格切换展开状态。
    • main.pyFastAPI 接口入口
    • decorators_demo.py本篇 Python 实验
    • pyproject.toml项目配置与基础依赖
    • .python-version本机 Python 3.12
    • .gitignore排除环境和缓存文件
    • README.md运行方法与实验说明

7.1 完整实验代码

decorators_demo.py
001
import asyncio
002
from functools import wraps
003
004
def log_call(function):
005
@wraps(function)
006
def wrapper(*args, **kwargs):
007
print(f"开始执行:{function.__name__}")
008
try:
009
return function(*args, **kwargs)
010
finally:
011
print(f"执行结束:{function.__name__}")
012
return wrapper
013
014
def repeat(times: int):
015
def decorator(function):
016
@wraps(function)
017
def wrapper(*args, **kwargs):
018
result = None
019
for _ in range(times):
020
result = function(*args, **kwargs)
021
return result
022
return wrapper
023
return decorator
024
025
def uppercase(function):
026
@wraps(function)
027
def wrapper(*args, **kwargs):
028
return function(*args, **kwargs).upper()
029
return wrapper
030
031
def add_prefix(function):
032
@wraps(function)
033
def wrapper(*args, **kwargs):
034
return "result: " + function(*args, **kwargs)
035
return wrapper
036
037
def require_role(required_role: str):
038
def decorator(function):
039
@wraps(function)
040
def wrapper(user, *args, **kwargs):
041
if user["role"] != required_role:
042
raise PermissionError("没有执行权限")
043
return function(user, *args, **kwargs)
044
return wrapper
045
return decorator
046
047
def log_async(function):
048
@wraps(function)
049
async def wrapper(*args, **kwargs):
050
print(f"异步任务开始:{function.__name__}")
051
try:
052
return await function(*args, **kwargs)
053
finally:
054
print(f"异步任务结束:{function.__name__}")
055
return wrapper
056
057
@log_call
058
def add(left: int, right: int) -> int:
059
"""把两个数字相加。"""
060
return left + right
061
062
@add_prefix
063
@uppercase
064
def message() -> str:
065
return "hello"
066
067
@uppercase
068
@add_prefix
069
def reversed_message() -> str:
070
return "hello"
071
072
@require_role("admin")
073
def delete_article(user, article_id: int) -> str:
074
return f"已删除文章 {article_id}"
075
076
@log_async
077
async def greet_async(name: str) -> str:
078
await asyncio.sleep(0)
079
return f"你好,{name}"
080
081
async def build_report(name: str, times: int, role: str) -> dict[str, object]:
082
calls = []
083
@repeat(times)
084
def greet(person: str) -> str:
085
calls.append(person)
086
print(f"第 {len(calls)} 次问候:{person}")
087
return f"你好,{person}"
088
089
repeated_result = greet(name)
090
try:
091
permission_result = {"allowed": True, "result": delete_article({"role": role}, 10)}
092
except PermissionError as error:
093
# 将这次教学用的权限失败作为结果展示,不吞掉其他异常。
094
permission_result = {"allowed": False, "error": type(error).__name__, "message": str(error)}
095
return {
096
"logged_add": add(2, 3),
097
"function_info": {"name": add.__name__, "docstring": add.__doc__},
098
"repeat": {"times": times, "actual_calls": len(calls), "result": repeated_result},
099
"order": {"prefix_outside": message(), "uppercase_outside": reversed_message()},
100
"permission": permission_result,
101
"async_result": await greet_async(name),
102
}
103

7.2 接口与配置

main.py
01
from typing import Literal
02
03
from fastapi import FastAPI, Query
04
05
from decorators_demo import build_report
06
07
app = FastAPI()
08
09
@app.get("/decorators")
10
async def decorators(
11
name: str = Query("小微", min_length=1, max_length=80),
12
times: int = Query(3, ge=1, le=5),
13
role: Literal["admin", "reader"] = "reader",
14
) -> dict[str, object]:
15
return await build_report(name, times, role)
16
pyproject.toml
01
[project]
02
name = "python-decorators"
03
version = "0.1.0"
04
description = "Python 装饰器"
05
readme = "README.md"
06
requires-python = ">=3.12"
07
dependencies = [
08
"fastapi[standard]==0.136.1; sys_platform != 'emscripten'",
09
"fastapi==0.136.1; sys_platform == 'emscripten'",
10
"pydantic==2.12.5",
11
"httpx==0.28.1",
12
]
13
14
[tool.uv]
15
package = false
16

其余配置文件可在在线案例左侧的文件目录中查看,也会包含在下载包里。接口的输入有明确的长度、数量或数值范围,超出范围时 FastAPI 会返回 422。

7.3 运行和观察

打开在线案例,点击运行,等待环境就绪。案例预览默认使用 GET,地址是:

code.ts
1
/decorators?name=小微&times=3&role=reader

默认请求会让问候函数实际执行三次,repeat.actual_calls 为 3,日志也会出现三条问候记录。function_info.name 仍然是 add,文档字符串也被保留,这是 @wraps 的作用。

两个堆叠顺序分别返回 result: HELLO 和 RESULT: HELLO。在线实验使用英文前缀,因此改变外层的大小写装饰器会产生可见差异。把 role 改为 admin 后,权限检查会成功;默认 reader 的 PermissionError 被明确捕获到响应字段中,接口仍正常返回。

异步函数确实由 await greet_async(name) 调用,日志会显示异步任务开始和结束,不使用 asyncio.run() 新建事件循环。可以修改 repeat() 或两个文本装饰器,保存并重新运行。次数限制在 1 到 5,避免重复实验占用过长时间。

7.4 本机运行

下载 ZIP 并解压,在项目目录执行:

code.ts
1
uv run fastapi dev main.py

然后打开 http://127.0.0.1:8000/docs,选择对应接口,填写和在线案例相同的参数发送请求。

本机使用 .python-version 指定的 Python 3.12,浏览器使用当前 Pyodide 的 Python 版本。在线案例通过 ASGITransport 执行 FastAPI,不监听本机端口,无需安装本机 Python。每次请求都会新建本次实验的状态,本篇的代码草稿、Git、日志和 Agent 对话也与其他文章分开保存。

正在验证登录状态
请稍候,验证完成后将继续显示文章内容

此段落已有评论,按 Enter 查看评论及回复列表。

评论-

文章反应
评论与回复

连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。

添加评论
    即时渲染