原文：Agentic RAG With Llama-index | Router Query Engine #01

作者：Prince Krampah

翻译：RyomaHan | 小白

提示：本文有对应的 YouTube 视频，本文中的我代指原作者

前言

你是否也厌倦了我在博文中经常提到的老式 RAG(Retrieval Augmented Generation | 检索增强生成) 系统？反正我是对此感到厌倦了。但我们可以做一些有趣的事情，让它更上一层楼。接下来就跟我一起将 agents 概念引入传统的 RAG 工作流，重新构建自己的 Agentic RAG 系统吧。

去年大模型领域最流行的关键词就是 RAG 了，而今年，一代新人换旧人，agents 已经取代 RAG 成为大模型领域的新宠。你大可不必为错过 RAG 的风口而沮丧，因为将 agents 引入 RAG 系统后会有更好的效果，所以现在开始学习也不晚。

在本文中，我会介绍如何使用 Llama-index 实现基本的 Agentic RAG 应用。我将在接下来的几周发布一系列（共四篇）有关 Agentic RAG 架构的文章，本文是这个系列的第一篇。

RAG 基础工作流

在开始新篇章前，让我们快速回顾一下传统的 RAG 架构的组织形式和工作原理。这部分知识在后续过程也会用到，那些对 RAG 没有任何经验的初学者务必仔细学习。

在上面简单的 RAG 架构图中，我们至少需要理解以下概念：

1. 文档（Documents）：用于增强 LLM 理解特定领域的上下文。可以是 PDF 或者任何文本文档，对于多模态的 LLM 来说甚至可以是图片；
2. 块（Chunks）/ 节点（nodes）：将较大的文档通过合适的算法分割成尺寸合适的块（或节点）；
3. 特征映射（Embedings）：在将文档分割成块后，我们需要为每个块创建与之对应的特征映射（一般以向量的形式存储）。当系统收到来自用户的查询时，RAG 系统会通过相似性搜索找到与查询内容相关性最高的文档块。这些被检索出来的文档块会与用户查询内容一起发送给 LLM，检索出来的文档块会充当此次 LLM 调用的上下文。最终，LLM 会根据以上内容生成响应。

以上就是典型的传统 RAG 系统的组织形式和工作原理。

为什么要创建 Agentic RAG

通过上一章节我们了解了传统 RAG 的实现，这种实现方案适用于少量文档的简单 QA 任务，不适合复杂的 QA 任务和对较大文档集的总结。

而这恰好是 agents 的强势领域，将 agents 与 RAG 结合能够将传统 RAG 系统提升到一个全新的水平。通过 Agentic RAG 系统，可以轻松地执行更复杂的任务，例如文档集摘要、复杂 QA 以及其他复杂任务。Agentic RAG 还能使 RAG 系统具有工具调用的能力，并且这些工具可以是自定义函数。

在本系列文章中我将讨论以下内容：

1. 路由式查询引擎（Router Query Engines）：这是最简单的 Agentic RAG 实现方式，它提供了添加逻辑声明的能力。这种能力可以帮助 LLM 根据需要执行的任务以及提供的工具确定通过何种路径能够达到最终目的；
2. 工具调用（Tool Calling）：在这篇文章中，我将介绍如何将自己定义的工具（方法）添加到 Agentic RAG 架构中。我会为 agents 实现一些接口，以便从我们提供的工具中选择合适的工具并通过 LLM 生成调用这些工具（这里我们默认工具是自定义的 Python 函数）所需要的参数；
3. 具有多步推理能力的 Agentic RAG；
4. 在文档集中具有多步推理能力的 Agentic RAG。

路由式查询引擎 | Router Query Engine

这是 Llama-index 中最简单的 Agentic RAG 实现方案。在这种方案中，我们只需要创建一个路由式查询引擎。它能够在 LLM 帮助下，（从提供的工具和查询引擎列表中）确定具体使用什么工具或查询引擎来解决用户查询的。

下图是本文要实现的路由式查询引擎的基本结构：

项目环境初始化

创建一个名为 agentic_rag 的目录作为本系列文章的项目目录，再在 agentic_rag 内部创建一个名为 basics 的目录作为本文代码实践的工作目录。创建完成后进入 basics 目录中进行环境初始化：

1
2

# /root/to/agentic_rag/basics
poetry init

在正式开始前，你需要先准备好你的 OpenAI API 密钥，如果你还没有密钥，可以从 此处 获取。准备好密钥后，将其添加到你的 .env 文件中：

1
2

# /root/to/agentic_rag/basics/.env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

译者注：也可以使用其他平台的 LLM 接口，你可以在 此链接 下确认 Llama-index 是否支持你期望的平台。

译者注：如果没有能力购买平台提供的 LLM 能力，也可以使用 Ollama 在本地运行指定模型，并参考 文档 在 Llama-index 中调用模型能力。

译者注：如果使用了不同平台的接口需要将后文中提到的 OpenAI 相关的接口替换成你所使用的平台的接口。

安装依赖

我们会在本项目中使用到 Llama-index 以及一些其他的依赖库，你可以通过如下命令进行安装：

1
2

# /root/to/agentic_rag/basics
poetry add python-dotenv ipykernel llama-index nest_asyncio

下载数据集

我们需要一个 PDF 文件用于后续代码实践，你可以点击 此链接 下载我所使用的 PDF。当然你也可以使用你手中的任何一个 PDF 文件（译者注：对于初学者来说最好是一个纯文本的 PDF 文件）。将它保存到 /path/to/agentic_rag/basic/datasets 目录下。

加载文档并将其处理成块

译者注：原文作者是使用 .ipynb 格式来编写并运行代码的，如果你不熟悉这个文件格式可以使用正常的 .py 文件。

现在我们已经将代码运行的基础环境准备好了，然我们先通过 python-dotenv 库加载环境变量：

1
2
3

import dotenv
%load_ext dotenv
%dotenv

随后我们需要引入 nest_asyncio 库，因为 Llama-index 在后台使用大量 asyncio 功能：

1
2

import nest_asyncio
nest_asyncio.apply()

现在，然我们加载准备好的 PDF 文档：

1
2
3
4

from llama_index.core import SimpleDirectoryReader  
  
# load lora_paper.pdf documents  
documents = SimpleDirectoryReader(input_files=["./datasets/lora_paper.pdf"]).load_data()

创建文档块

成功加载文档后，我们需要将其分解成合适大小的块：

1
2
3
4
5
6

from llama_index.core.node_parser import SentenceSplitter  
  
# chunk_size of 1024 is a good default value  
splitter = SentenceSplitter(chunk_size=1024)  
# Create nodes from documents  
nodes = splitter.get_nodes_from_documents(documents)

可以使用以下方法获取有关每个块的详细信息：

1
2

node_metadata = nodes[1].get_content(metadata_mode=True)  
print(node_metadata)

创建所需的 LLM 和 Embedding 模型对象

译者注：这里你需要将用到的模型类替换为你所使用的平台所对应的类，有些类需要添加额外的第三方依赖，详情请查看 Llama-index 文档。

在本次代码实践中，我将使用 OpenAI 的 gpt-3.5-turbo 模型作为 LLM 模型，使用 OpenAI 的 text-embedding-ada-002 模型作为 Embedding 模型。

1
2
3
4
5
6
7
8

from llama_index.core import Settings  
from llama_index.llms.openai import OpenAI  
from llama_index.embeddings.openai import OpenAIEmbedding  

# LLM model  
Settings.llm = OpenAI(model="gpt-3.5-turbo")  
# embedding model  
Settings.embed_model = OpenAIEmbedding(model="text-embedding-ada-002")

创建索引

正如前文基本结构图片所示，在本次代码实践中，我们将使用两个主要的索引：

1. 摘要索引（Summary Index）：根据 Llama-index 对应文档 所示，摘要索引是一种简单的数据结构，其中节点按顺序存储。在索引构建过程中，文档文本被分块、转换为节点并存储在列表中。在查询期间，摘要索引使用一些可选的过滤器参数迭代节点，并综合所有节点的答案。
2. 向量索引（Vector Index）：一个通过 Embedding 创建的常规索引存储，可以执行相似性搜索，以获得与搜索条件最相似的 n 个的索引。

可以使用下面的代码来创建这两个索引：

1
2
3
4
5
6

from llama_index.core import SummaryIndex, VectorStoreIndex  
  
# summary index  
summary_index = SummaryIndex(nodes)  
# vector store index  
vector_index = VectorStoreIndex(nodes)

将向量索引转换为查询引擎

在创建并存储向量索引后，我们需要继续创建查询引擎，后续会将它们转换为 agnets 使用的工具（又名查询工具）。

1
2
3
4
5
6
7
8

# summary query engine  
summary_query_engine = summary_index.as_query_engine(  
response_mode="tree_summarize",  
use_async=True,  
)  
  
# vector query engine  
vector_query_engine = vector_index.as_query_engine()

在上面的例子中，我们创建了两个不同的查询引擎。后续我们会将它们都挂载到路由式查询引擎下，然后路由式查询引擎会根据用户的查询内容决定具体使用哪个查询引擎。

在上面的代码中，我们指定了 use_async 参数以加快查询速度，这是我们必须使用 nest_asyncio 库的原因之一。

译者注：我刚去看 nest_asyncio 的代码库，发现被 archive 了，我还以为是 Python 官方支持了，后面在阅读 相关 issue 的时候才发现原来是代码库的作者年初去世了，RIP.

创建查询工具

查询工具是一个带有元数据（例如存储当前查询工具可以用来做什么）的查询引擎。这有助于路由式查询引擎能够根据传入的用户查询来决定具体使用哪个查询引擎。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

from llama_index.core.tools import QueryEngineTool  
  
  
summary_tool = QueryEngineTool.from_defaults(  
query_engine=summary_query_engine,  
description=(  
"Useful for summarization questions related to the Lora paper."  
),  
)  
  
vector_tool = QueryEngineTool.from_defaults(  
query_engine=vector_query_engine,  
description=(  
"Useful for retrieving specific context from the the Lora paper."  
),
)

创建路由式查询引擎

最后，我们需要创建最终用于查询的路由式查询引擎。它能够帮我们聚合上文所创建的所有查询工具，即 summary_tool 和 vector_tool。

1
2
3
4
5
6
7
8
9
10
11
12

from llama_index.core.query_engine.router_query_engine import RouterQueryEngine  
from llama_index.core.selectors import LLMSingleSelector  
  
  
query_engine = RouterQueryEngine(  
selector=LLMSingleSelector.from_defaults(),  
query_engine_tools=[  
summary_tool,  
vector_tool,  
],  
verbose=True  
)

LLMSingleSelector：是一个使用 LLM 从选项列表中选择出单个选项的选择器。你可以在 这个链接 中查看更多信息。

测试路由式查询引擎

译者注：在执行如下代码是记得把问题换成与你使用的 PDF 相关的问题。

可以通过如下代码测试我们创建的路由式查询引擎：

1
2

response = query_engine.query("What is the summary of the document?")  
print(str(response))

以上是论文的摘要，总结了我们传递给查询引擎的 Lora 论文的所有上下文。

由于我们使用的摘要索引是将所有块存储在顺序列表中，因此在生成摘要时会访问所有块并从中生成一个总摘要，然后再以此生成最终摘要。

可以通过检查响应中 source_nodes 列表的长度来确认这一点，source_nodes 属性是这次响应中用到的所有块的列表。

可以看到最终的结果 38 与我们前面创建的块的数量相同，这意味着所有的块都用于本次摘要生成。

再提问一个不涉及总结的问题：

1
2

response = query_engine.query("What is the long from of Lora?")  
print(str(response))

这次回答使用了向量索引，尽管响应内容不是很准确。

将代码合并

现在你已经大致理解了这套 Agentic RAG 工作流，让我们将其抽象成函数方便后续调用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

from llama_index.core.query_engine.router_query_engine import RouterQueryEngine  
from llama_index.core.selectors import LLMSingleSelector  
from llama_index.core.tools import QueryEngineTool  
from llama_index.core import SummaryIndex, VectorStoreIndex  
from llama_index.core import Settings  
from llama_index.llms.openai import OpenAI  
from llama_index.embeddings.openai import OpenAIEmbedding  
from llama_index.core.node_parser import SentenceSplitter  
from llama_index.core import SimpleDirectoryReader


async def create_router_query_engine(  
document_fp: str,  
verbose: bool = True,  
) -> RouterQueryEngine:  
# load lora_paper.pdf documents  
documents = SimpleDirectoryReader(input_files=[document_fp]).load_data()  
  
# chunk_size of 1024 is a good default value  
splitter = SentenceSplitter(chunk_size=1024)  
# Create nodes from documents  
nodes = splitter.get_nodes_from_documents(documents)  
  
# LLM model  
Settings.llm = OpenAI(model="gpt-3.5-turbo")  
# embedding model  
Settings.embed_model = OpenAIEmbedding(model="text-embedding-ada-002")  
  
# summary index  
summary_index = SummaryIndex(nodes)  
# vector store index  
vector_index = VectorStoreIndex(nodes)  
  
# summary query engine  
summary_query_engine = summary_index.as_query_engine(  
response_mode="tree_summarize",  
use_async=True,  
)  
  
# vector query engine  
vector_query_engine = vector_index.as_query_engine()  
  
summary_tool = QueryEngineTool.from_defaults(  
query_engine=summary_query_engine,  
description=(  
"Useful for summarization questions related to the Lora paper."  
),  
)  
  
vector_tool = QueryEngineTool.from_defaults(  
query_engine=vector_query_engine,  
description=(  
"Useful for retrieving specific context from the the Lora paper."  
),  
)  
  
  
query_engine = RouterQueryEngine(  
selector=LLMSingleSelector.from_defaults(),  
query_engine_tools=[  
summary_tool,  
vector_tool,  
],  
verbose=verbose  
)  
  
  
return query_engine

然后我们就可以通过如下方法便捷的调用次函数：

1
2
3

query_engine = await create_router_query_engine("./datasets/lora_paper.pdf")  
response = query_engine.query("What is the summary of the document?")  
print(str(response))

我们可以在当前目录下创建一个 utils.py 文件，用于存放刚刚抽象出来的函数：

之后我们就可以通过如下代码便捷的调用此函数：

1
2
3
4
5

from utils import create_router_query_engine  
  
query_engine = await create_router_query_engine("./datasets/lora_paper.pdf")  
response = query_engine.query("What is the summary of the document?")  
print(str(response))

结语

恭喜你走到这一步。以上就是本文的全部内容了，在下一篇文章中，我将介绍如何使用工具调用（也称函数调用）来进一步加强我们的 RAG 系统。

本文的主体内容大部分来自对 PEP 492 原文的翻译，剩余部分是本人对原文的理解，在整理过程中我没有刻意地区分二者，这两部分被糅杂在一起形成了本文。因此请不要带着「本文的内容是百分百正确」的想法阅读。如果文中的某些内容让你产生疑惑，你可以给我留言与我讨论或者对比 PEP 492 的原文加以确认。

注：PEP 492 创建于 2015-04-09，Python 3.5
注：文中的「当前版本」指的是本提案生效之前的版本
注：本文过长，虽然已经自我校对过一次，但还是难免存在错别字或语句不通顺的地方，如果您发现了问题欢迎留言给我

摘要

网络请求爆发性地增长引发了对低延时、可拓展代码的相关需求。本提案旨在让显式地编写异步、并发 Python 代码更容易、更 Pythoinc，并以此满足前述需求。

提案建议使协程成为 Python 中完全独立的新概念，并引入新的支持语法。最终的目的是在 Python 中建立一个简洁通用的异步编程心智模型，并使它尽可能接近同步编程。

在本提案中，假设异步任务都使用类似内置模块 asyncio.events.AbstractEventLoop 中的事件循环进行编排和协调。但是，本提案与任何特定的事件循环实现无关，只与使用 yield 作为调度信号的协程相关，也就是说协程会在事件（例如 IO）完成前保持等待。

我们相信，本提案能够让 Python 在快速增长的异步编程领域中继续保持竞争力，因为很多其他语言已经或计划采用近似的特性：2，5，7，8，10。

接口设计与实施修订

注：这部分是修订内容，可以放在最后阅读。

1. 以初始 Python 3.5 beta 版本的反馈为依据，重构本提案设置的对象模型。这次重构的目的是更明确地将原生协程与生成器分离，而不是将原生协程作为一种新的生成器，原生协程要设计成完全独立的类型（具体实施在 引用 17）。这么做的主要原因是在尝试为 Tornado Web Server 集成原生协程时遇到了问题（记录在 引用 18）。
2. CPython 3.5.2 更新了 __aiter__ 协议。在 3.5.2 之前，__aiter__ 返回一个可以被解析成 异步迭代器 的 可等待对象（awaitable）。从 3.5.2 开始，__aiter__ 直接返回异步迭代器。如果在 3.5.2 中使用旧协议，会抛出一个 PendingDeprecatioWarning 异常。而在 3.6 中，旧的 __aiter__ 协议仍旧会被支持，但会抛出一个 DeprecationWarning 异常。最终，在 3.7 中，旧的 __aiter__ 协议将被废弃，如果 __aiter__ 返回的不是异步迭代器，则会引发 RuntimeError。可以通过 引用 19 和 引用 20 来获取更多细节。

理由和目标

当前版本的 Python 支持通过生成器来实现协程（PEP 342），PEP 380 中引入的 yield from 语法进一步增强了这一特性。但是这种方案有很多缺点：

1. 生成器实现的协程和正常生成器的语法相同，因此很容易被混淆，对于新用户来说尤其如此；
2. 一个函数是否是协程取决于函数体中是否存在 yield 或 yield from 语句。在重构这些函数时，如果删除或新增了 yield 相关语句就可能会导致一些不明显的错误；
3. 只能在 yield 语法支持的地方进行异步调用，无法异步调用类似 with 或 for 这样的语句，限制了可用性。

本提案使协程成为 Python 语言的一种原生特性，并且清晰地将其与生成器区分开。这样做不仅消除了生成器与协程之间的歧义，还可以不依赖特定库直接定义协程。同时也提升了 linters 或 IDE 静态代码分析和重构的能力。

原生协程以及相关新语法使得在异步操作中定义上下文管理器和可迭代协议成为可能。稍后会在提案中提及：新的 async with 语句允许 Python 程序在进入或退出上下文上时执行异步调用，而新的 async for 语句可以在迭代器中执行异步调用。

规范

规范章节引入了新的语法和语义，以增强 Python 对协程的支持。

本规范假定阅读者已经了解此前 Python 中协程的实现（ PEP 342 和 PEP 380）。本规范涉及的语法修改动机来自 asyncio 模块提案（PEP 3156）和 Cofunctions 提案（PEP 3152，现已被本规范否决）。

在后文中，将使用「原生协程」来指代使用新语法声明的协程，使用「生成器式协程」指代基于生成器语法的协程。

原生协程声明语法

原生协程声明语法如下：

1
2

async def read_data(db):
pass

它的主要特性有：

1. 使用 async def 声明的函数一定是协程，即使内部不包含 await；
2. 在 async 函数中使用 yield 或 yield from 会引发 SyntaxError 异常；
3. 在内部，引入了两个新的 code object flags：
   1. CO_COROUTINE：用于标记原生协程；
   2. CO_ITERABLE_COROUTINE：使生成器式协程与原生协程兼容（由 types.coroutine 函数设置）。
4. 常规生成器返回一个生成器对象，类似的，协程返回一个协程对象；
5. 在协程中 StopIteration 会被 RuntimeError 代替，对于常规生成器来说，这种行为会在后续过程中支持（详情请看 PEP 479）；
6. 如果不使用 await 直接调用原生协程，当它被垃圾回收时会抛出一个 RuntimeWarning（点击 用于调试的特性 了解更多）；
7. 更多特性请看：协程对象 章节。

types.coroutine()

types 模块中新增了一个名为 coroutine(fn) 的函数。它能够帮助「asyncio 中现有的生成器式协程」与「本提案引入的原生协程」实现相互兼容：

1
2
3
4

@types.coroutine
def process_data(db):
data = yield from read_data(db)
...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# CPython 3.10 Lib.types.py
def coroutine(func):  
    if not callable(func):  
        raise TypeError('types.coroutine() expects a callable')  
  
    if (
    func.__class__ is FunctionType and 
    getattr(func, '__code__', None).__class__ is CodeType
):  
        co_flags = func.__code__.co_flags  

# 0x20 == CO_GENERATOR 生成器标识
# 0x180 == CO_COROUTINE | CO_ITERABLE_COROUTINE 原生协程标识 or 生成式协程标识
# 0x100 == CO_ITERABLE_COROUTINE 生成式协程标识

# 如果确定传入函数是一个原生协程则直接返回
        if co_flags & 0x180:  
            return func  

# 如果传入函数是一个生成器函数，
# 则将 CO_ITERABLE_COROUTINE 标记附加在此函数上，随后返回
        if co_flags & 0x20:
            co = func.__code__
            func.__code__ = co.replace(co_flags=co.co_flags | 0x100)
            return func  

# 下面的代码主要用于兼容「返回类似生成器对象」的函数
# 例如使用 Cython 编译的生成器
import functools
    import _collections_abc
    @functools.wraps(func)
    def wrapped(*args, **kwargs):  
        coro = func(*args, **kwargs)  
        if (coro.__class__ is CoroutineType or  
            coro.__class__ is GeneratorType and coro.gi_code.co_flags & 0x100):  
            return coro  
        if (isinstance(coro, _collections_abc.Generator) and  
            not isinstance(coro, _collections_abc.Coroutine)):  
            return _GeneratorWrapper(coro)  
        return coro  
  
    return wrapped

如果 fn 是生成器函数， types.coroutine() 会在它的 code object 中添加 CO_ITERABLE_COROUTINE 标志，使其返回一个协程对象。
如果 fn 不是生成器函数，types.coroutine() 会对齐进行包装。如果 fn 返回一个生成器函数，返回的函数会被 _GeneratorWrapper 包装。

type.coroutine() 不会为生成器函数附加 CO_COROUTINE 标志，以便区分「原生协程」和「生成器式协程」。

await 表达式

await 表达式用来获取一个协程执行的结果：

1
2
3

async def read_data(db):
data = await db.fetch("SELECT ...")
...

await 与 yield from 近似，会暂停 read_data 函数的执行直到可等待对象 db.fetch 完成并返回结果。await 使用 yield from 实现，但是多了一个验证参数的步骤。await 后只能跟一个 可等待对象（awaitable），可以是以下选项之一：

1. 原生协程函数返回的原生协程对象；
2. 被 types.coroutine() 装饰的函数中返回的生成式协程对象；
3. 一个拥有 __await__ 方法的对象，且该方法需要返回一个迭代器；
4. 使用 CPython C API 定义的带有 tp_as_async.am_await 函数的对象，该函数返回一个迭代器（类似 __await__ 方法）。

关于第三点一些延伸内容：任何 yield from 调用链都会以 yield 收尾，这是 Futures 执行的必要条件。由于协程本质上是一个特殊的生成器，因此每个 await 都会被 await 调用链上的某个 yield 挂起（详情请参考 PEP 3156）。为了在协程上实现这种行为，一个名为 __await__ 的新魔术方法被添加进来。例如，在 asyncio 中， 要想在 await 语句中使用 Future，唯一要做的就是在 asyncio.Future 类中添加 __await__ = __iter__。后续章节中，称带有 __await__ 方法的对象为类 Future 对象。如果 __await__ 返回迭代器之外的东西，会抛出 TypeError 异常。

在原生协程外部使用 await 会抛出 SyntaxError 异常（就像在一般函数外调用 yield 一样）。

不在 await 关键字后使用可等待对象会抛出 TypeError 异常。

更新运算符优先级

await 关键字被定义为：

1
2

power ::= await ["**" u_expr]
await ::= ["await"] primary

其中「primary」代表语言中最主要的操作，其语法为：

1

primary ::= atom | attributerf | subscription | slicing | call

如需理解上述表达式含义可参考 引用 12 和 语法更新。

与 yield 和 yield from 不同，大多数情况下 await 表达式不需要被圆括号包裹。此外，yield from 允许将任何表达式作为参数，甚至可以 yield from a() + b()，它会被解析为 yield from (a() + b())。这看起来很反常识就像一个 BUG 一样，因为一般来说，算数操作不会产生可等待对象。为了避免此类问题在 await 表达式中再次出现，await 的优先级被设定为低于 [], (), . 但高于 ``**。

具体优先级如下（从上到下，从低到高）：

使用 await 关键字的示例

有效调用：

无效调用：

异步上下文管理器与 async with

注：关于上下文管理器的内容可以参考：WeeklyPEP-2-PEP343-with 语句-overview

所谓异步上下文管理器，是一种能够在进入或退出上下文时调用异步代码的上下文管理器。为了实现它，本规范单独为异步上下文提出了一个新协议，此协议由两个新的魔术方法组成：__aenter__ 和 __aexit__。它们都必须返回一个可等待对象。

异步上下文管理器的示例：

1
2
3
4
5
6

class AsyncContextManager:
async def __aenter__(self):
await log("entering context")

async def __aexit__(self, exc_type, exc, tb):
await log("exiting context")

新语法

本规范规定的异步上下文管理器声明方式如下：

1
2

async with EXPR as VAR:
BLOCK

语义上等同于：

1
2
3
4
5
6
7
8
9
10
11
12

mgr = (EXPR)
aexit = type(mgr).__aexit__
aenter = type(mgr).__aenter__

VAR = await aenter(mgr)
try:
BLOCK
except:
if not await aexit(mgr, *sys.exc_info()):
raise
else:
await aexit(mgr, None, None, None)

与普通的 with 语句一样，可以在单个 async with 语句中指定多个上下文管理器。

不能将没有实现 __aenter__ 和 __aexit__ 的普通上下文管理器传递给 async with。在 async def 函数之外使用 async with 会抛出 SyntaxError 异常。

示例

通过异步上下文管理器可以很方便的在协程中实现数据库事务管理器：

1
2
3
4
5
6

async def commit(session, data):
...
async with session.transaction():
...
await session.update(data)
...

也可以很简洁的使用锁：

1
2

async with lock:
...

代替之前的：

1
2

with (yield from lock):
...

异步迭代器和 async for

所谓异步迭代器，是一种可以在 iter 和 next 方法中调用异步代码的迭代器。要想实现它：

1. 指定对象必须实现一个返回异步迭代器对象的 __aiter__ 方法（如果是通过 CPython C API 定义则需要定义 tp_as_async.am_aiter slot 代替 __aiter__）；
2. 异步迭代器对象必须实现一个返回可等待对象的 __anext__ 方法（如果是通过 CPython C API 定义则需要定义 tp_as_async.am_anext slot 代替 __anext__）；
3. 为了使迭代过程不会无限进行下去，__anext__ 必须在适当的时候抛出 StopAsyncIteration 异常。

异步迭代器示例：

1
2
3
4
5
6
7
8
9
10
11
12
13

class AsyncIterable:
def __aiter__(self):
return self

async def __anext__(self):
data = await self.fetch_data()
if data:
return data
else:
raise StopAsyncIteration

async def fetch_data(self):
...

新语法

1
2
3
4

async for TARGET in ITER:
BLOCK
else:
BLOCK2

语义上等同于：

1
2
3
4
5
6
7
8
9
10
11
12
13

iter = (ITER)
iter = type(iter).__aiter__(iter)
running = True

while running:
try:
TARGET = await type(iter).__anext__(iter)
except StopAsyncIteration:
runnint = False
else:
BLOCK
else:
BLOCK2

在 async for 后使用未实现 __aiter__ 方法的常规迭可迭代对象会抛出 TypeError 异常，在 async def 外使用 async for 会抛出 SyntaxError 异常。

与常规 for 语句一样，async for 也有一个可选的 else 字句。

示例 1

通过异步迭代器可以在迭代过程中异步缓冲数据：

1
2

async for data in cursor:
...

其中，cursor 是一个异步迭代器，每迭代 N 次就会从数据库中预取 N 行数据。

下面的代码实现了异步迭代协议：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class Cursor:
def __init__(self):
self.buffer = collections.deque()

async def _prefetch(self):
...

def __aiter__(self):
return self

async def __anext__(self):
if not self.buffer:
self.buffer = await self._prefetch()
if not self.buffer:
raise StopAsyncIteration
return self.buffer.popleft()

然后 Cursor 类可以像这样被使用：

1
2

async for row in Cursor():
print(row)

等同于下面这段代码：

1
2
3
4
5
6
7
8

i = Cursor().__aiter__()
while True:
try:
row = await i.__anext__()
except StopAsyncIteration:
break:
else:
print(row)

示例 2

下面的示例是一个通用的工具类，它能够将常规迭代器转换为异步迭代器。虽然这不是一个会经常使用的操作，但是这个示例代码说明了常规迭代器和异步迭代器之间的关系：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class AsyncIteratorWrapper:
def __init__(self, obj):
self._it = iter(obj)

def __aiter__(self):
return self

async def __anext__(self):
try:
value = next(self._it)
expect StopIteration:
raise StopAsyncIteration
return value

async for letter in AsyncIteratorWrapper("abc"):
print(letter)

为什么需要 StopAsyncIteration

为什么需要 StopAsyncIteration 也就是为什么不继续使用 StopIteration。协程的本质是生成器，所以在 PEP 479 之前，下面的两段代码没有本质上的不同：

1
2
3

def g1():
yield from fut
return "spam"

和

1
2
3

def g2():
yield from fut
raise StopIteration("spam")

由于 PEP 479 被接受并且在协程中默认启用，下面的示例代码将会使用 RuntimeError 包裹 StopIteration：

1
2
3

async def a1():
await fut
raise StopIteration("spam")

因此通知外部代码迭代结束的唯一方案就是抛出一个 StopIteration 以外的异常，也正是因为这样才需要新增一个内置的 StopAsyncIteration 异常。此外，根据 PEP 479 中的定义，所有在协程中抛出的 StopIteration 异常都会被封装在 RuntimeError 中。

协程对象

与生成器的不同之处

本小节仅适用于带有 CO_COROUTINE 的原生协程，即通过 async def 语法定义的协程。asyncio 中现有的生成器式协程的行为保持不变。

为了确保协程与生成器作为不同的概念处理需要付出很大的努力：

1. 原生协程对象没有实现 __iter__ 和 __next__ 方法。因此，它不能通过 iter()，list()，tuple() 或其他内置方法迭代，同样不能在 for .. in 中使用。若要强行在原生协程中实现 __iter__ 或 __next__ 会抛出 TypeError 异常；
2. 不能使用 yield from 加原生协程返回正常的生成器，这个行为会抛出 TypeError 异常；
3. 可以使用 yield from 加原生协程返回生成器式协程（在 asyncio 代码中必须使用 @asyncio.coroutine）；
4. inspect.isgenerator() 和 inspect.isgeneratorfunction() 在接收原生协对象和原生协程方法时需要返回 False。

协程对象的内置方法

在底层实现上，协程继承自生成器共享实现代码。所以，协程类似生成器拥有 throw()，send() 和 close() 方法，StopIteration 和 GeneratorExit 在协程中也起相同的作用（尽管 PEP 479 默认在协程中启用）。协程的 throw() 和 send() 方法被用来将值或异常传递给类 Future 对象。

更多细节请看 PEP 342，PEP 380 和 Python 文档相关章节。

用于调试的特性

注：asyncio.coroutine 在 Python 3.8 之后被标记为废弃，并在 Python 3.11 正式删除。
注：被标记为废弃的是 asyncio.coroutine 而不是 types.coroutine
注：这一小节的内容我看完之后有点犯迷糊，不知道他在表述什么事情。

新手容易犯的一个错误是忘记可以在协程中使用 yield from：

1
2
3
4

@asyncio.coroutine
def useful():
# 如果没有 yield from 语句，这段代码将不会起作用
asyncio.sleep(1)

为了调试这类错误，asyncio 中有一种特殊的调试模式，其中 @coroutine 装饰器使用一个特殊的对象包装所有传递进来的函数，这个对象的析构函数会记录警告日志。每当被包装的生成器被 GC 进行垃圾回收时，就会产生一条详细的日志信息，其中包含该装饰器确切的定义位置、被回收位置的堆栈跟踪等信息。封装对象还提供了一个方便的 __repr__ 函数，一种包含有关生成器的详细信息。

问题是如何启动这些调试功能。调试功能在生产环境下应该是不可用的，所以 @coroutine 装饰器根据操作系统环境变量 PYTHONSYNCIODEBUG 来判断是否起作用。这样就可以在运行 asyncio 程序时使用 asyncio 自带的函数。EventLoop.set_debug（一种不用的调试工具）对 @coroutine 装饰器的行为没有影响。

为了使协程就成为与生成器不同的原生概念：

1. 如果协程未被 await 直接调用会抛出 RuntimeWarning 异常；
2. 还建议在 sys 模块中添加两个新函数：set_coroutine_wrapper 和 get_coroutine_wrapper。它们的作用是在 asyncio 或其他框架中启用高级调试功能（例如显示创建协程的具体位置，以及更详细的垃圾回收堆栈跟踪）。

新内置函数

1. types.coroutine(gen)：点击 types.coroutine() 了解更多；
2. inspect.iscoroutine(obj)：如果 obj 是原生协程对象，返回 True；
3. inspect.iscoroutinefunction(obj)：如果 obj 是原生协程函数，返回 Ture；
4. inspect.isawaitable(obj)：如果 obj 是可等待对象，返回 True；
5. inspect.getcoroutinestate(coro)：返回原生协程对象的当前状态（inspect.getfgeneratorstate(gen) 的逆向函数）；
6. inspect.getfgeneratorstate(gen)：返回本地协程独享的局部变量与其值的映射（inspect.getcoroutinestate(coro) 的逆向函数）；
7. sys.set_coroutine_wrapper(wrapper)：允许拦截原生协程的创建，在原生协程创建时调用 wrapper。wrapper 可以是「一个接受一个参数（一个协程对象）的可调用对象」或是 None。如果是 None 则会重置之前定义的 wrapper，如果调用多次，新的 wrpaaer 将取代之前的。该函数是线程绑定的；
8. sys.get_coroutine_wrapper()：返回通过 sys.set_coroutine_wrapper 设置的 wrapper，如果没设置则返回 None。该函数是线程绑定的。

新的抽象基类

为了更好的与现有框架（如 Tornado，参考 引用 13）和编译器（如 Cython，参考 引用 16）集成，新增了两个抽象基类：

1. collections.abc.Awaitable：为类 Future 对象创建的基类，实现了 __await__ 方法；
2. collection.abc.Coroutine：为协程对象创建的基类，实现了 send(value)，throw(type, exc, tb)，close 和 __await__() 方法。

注意，带有 CO_ITERABLE_COROUTINE 标志的生成器式协程没有实现 __await__ 方法，因此不是 collections.abc.Coroutine 或 collections.abc.Awaitable 基类的实例：

1
2
3
4
5
6
7
8

@types.coroutine
def gencoro():
yield

assert not isinstance(gencoro(), collections.abc.Coroutine)

# 应该如何识别：
assert inspect.isawaitable(gencoro())

为了能更简单地测试指定对象是否支持异步迭代，又引入了另外两个基类：

1. collections.abc.AsyncIterable：测试是否存在 __aiter__ 方法；
2. collections.abs.AsyncIterator：测试是否存在 __aiter__ 和 __anext__ 方法。

术语表

原生协程函数

Navite coroutine function，通过 async def 定义的协程函数，点击 原生协程声明语法 了解更多。

原生协程

Navite coroutine，从原生协程函数返回的内容，点击 [await 表达式](#await 表达式) 了解更多。

生成器式协程函数

Generator-based coroutine function，基于生成器语法的协程，更常见的示例是使用 @asyncio.coroutine 定义的函数。

生成器式协程

Generator-based coroutine，通过生成器式协程函数返回的内容。

协程

Coroutine，原生协程或生成器式协程。

协程对象

Coroutine object，原生协程对象或生成器式协程对象。

类 Future 对象

Future-like object，拥有 __await__ 方法的对象或拥有 tp_as_async->am_await 函数的 C Object，且该函数或方法返回一个迭代器。可以在协程中作为 await 表达式的参数。在协程中 await 类 Future 对象时，协程会被推迟直到类 Future 对象的 __await__ 完成并且返回结果，点击 [await 表达式](#await 表达式) 了解更多。

可等待对象

Awaitable，类 Future 对象或协程对象。点击 [await 表达式](#await 表达式) 了解更多。

异步上下文管理器

Asynchronous context manager，拥有 __aenter__ 和 __aexit__ 方法的对象，可以搭配 async with 使用，点击 [异步上下文管理器与 async with](#异步上下文管理器与 async await) 了解更多。

异步可迭代对象

Asynchronous iterable，拥有 __aiter__ 方法的对象，该方法返回一个异步迭代器对象。可以搭配 async for 一起使用，点击 [异步迭代器和 async for](#异步迭代器和 async for) 了解更多。

异步迭代器

Asynchronos iterator，拥有 __anext__ 方法的对象，点击 [异步迭代器和 async for](#异步迭代器和 async for) 了解更多。

过渡计划

tokenizer.c 文件是 CPython 源码中的一个文件，主要负责实现 Python 解释器中的词法分析器。

为了解决 async 和 await 的向后兼容性问题，需要对 tokenizer.c 进行如下修改：

1. 识别 async def NAME 标记组合；
2. 在对 async def 块进行词法分析时，会将 async NAME 标记替换为 ASYNC，将 await NAME 标记替换为 AWAIT；
3. 在对 def 块进行词法分析时，会保持 async 和 await NAME 不变。

这种实现方式能够让新语法（只能在 async 函数中使用）与现有代码无缝结合。一个既包含 async def 又包含 async 属性的示例：

1
2
3
4
5
6

class Spam:
async = 42

# 协程函数能够被执行并且打印 42
async def ham():
print(getattr(Spam, "async"))

向后兼容性

为了兼容新语法，需要确保在现有的内置模块中不存在与 async 和 await 关键字冲突的命名，且新的原生协程需要兼容之前存在的生成器式协程。

asyncio

注：在本 PEP 实施之前，asyncio 库中已经存在了一个名为 async 的函数。

asyncio 模块进行了调整和测试，使现有协程方案与新语法保持兼容，保证 100% 向后兼容，即现有代码能够在新版本中正常运行。

进行调整的主要有：

1. 使 @asyncio.coroutine 装饰器使用新的 types.coroutine() 函数；
2. 向 asyncio.Future 类添加 __await__ = __iter__；
3. 将 ensure_future() 作为 async() 函数的别名，废弃 asyncio 中的 async() 函数。

asyncio 迁移策略

yield from 原生协程对象不能返回普通的生成器（点击 与生成器的不同之处 了解更多），因此建议在开始使用新语法之前，确保所有生成器式协程都使用 @asyncio.coroutine 进行装饰。

CPython 代码库中的 async/await

在 CPython 中没有使用 await。

async 关键字主要是被 asyncio 模块占用。为了解决这个问题，需要将 asyncio 模块中的 async() 函数重命名为 ensure_future()（点击 asyncio 了解更多）。

async 关键字的另一个占用场景是 Lib/xml/dom/xmlbuilder.py 中为 DocumentLS 类定义的 async = False 属性。没有针对这一属性的文档或测试文件，CPython 中的其他地方也没有使用这个属性。现在它被一个 getter 取代，调用 getter 会引发一个 DeprecationWarning 异常并通过异常信息建议使用 async_ 属性代替此属性。 除此以外，CPython 代码库中没有其他的 async 属性被记录或使用。

语法更新

语法的变化相当小：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

decorated: decorators (classdef | funcdef | async_funcdef)
async_funcdef: ASYNC funcdef

compound_stmt: (if_stmt | while_stmt | for_stmt | try_stmt | with_stmt
| funcdef | classdef | decorated | async_stmt)

async_stmt: ASYNC (funcdef | with_stmt | for_stmt)

power: atom_expr ['**' factor]
atom_expr: [AWAIT] atom tarilter*

# 这段代码定义了 Python 中异步语法的各个组成部分，
# 包括异步函数定义、异步语句以及与异步操作相关的表达式。 
# 这些语法元素共同构成了 Python 异步编程的基础。
# 来自 Google Gemini 1.5 Pro

废弃计划

注：根据原文，本来计划在 Python 3.5 或 3.6 中废弃 async 和 await，并在 3.7 中过渡到一个更合适的关键字，但从当下来看这个计划应该是没有实施。

决策过程

PEP 3152

Gregory Ewing 提出的 PEP 3152 提供了另一种机制来实现协程（或者称为 cofunctions），其中一些关键的要素：

1. 用于声明 cofunction 的新关键字 codef。Cofunction 总是一个生成器，即使没有 cocall 表达式在其内部。类比 async def；
2. 用于调用 cofunction 的新关键字 cocall。只能够被用在 cofunction 内部。类比 await；
3. Cofunction 只能通过 cocall 关键字调用；
4. cocall 语法需要在其后方使用圆括号；
5. cocall f(*args, **kwargs) 在语义上等同于 yield from f.__cocall__(*args, **kwds)。

相关语法定义：

1
2
3

atom: cocall | <existing alternatives for atom>
cocall: 'cocall' atom cotrailer* '(' [arglist] ')'
cotrailer: '[' subscriptlist ']' | '.' NAME

与本提案的不同之处：

1. 没有与 __cocall__ 一致的方法。__cocall__ 方法会被 cocall 表达式会调用并将其结果传递给 yield from，虽然 __await__ 方法与 __cocall__ 类似，但 __await__ 只用于定义类 Future 对象。
2. 在语法中，await 的定义几乎与 yield from 相同（后来强制规定 await 只能出现在 async def 中）。但 await 可以很简洁地使用 await future 的方式调用，而 cocall 总是需要圆括号辅助；
3. 要使 asyncio 与 PEP 3152 兼容，需要重构 @asyncio.coroutine 装饰器，来将所有函数封装在一个带有 __cocal__ 方法的对象中，或在生成器上实现 __cocall__。要在生成器式协程中调用 cofunctions，需要使用内置的 costart(cofunc, *args, **kwargs)；
4. 因为 cofunction 必须使用 cocall 关键字调用 ，因此自动避免在生成器式协程中忘记使用 yield from 的常见错误。本提案是使用其他方法来解决这一问题的，点击 用于调试的特性 了解更多。
5. 使用 cocall 调用 cofunction 的一个缺点是，如果决定实现协程生成器（使用 yield 或 async yield 表达式的协程），就不需要 cocall 关键字来调用。因此最终会使得协程拥有 __cocall__ 而没有 __call__，协程生成器拥有 __call__ 而没有 __cocall__。
6. 在 PEP 3152 中， 没有类似 async for 和 async with 的设计。
7. 括号语法会带来很多问题：

下面这段代码：

1
2
3

await fut
await function_returning_future()
await asyncio.gather(coro1(arg1, arg2), coro2(arg1, arg2))

需要这样表达：

1
2
3

cocall fut()
cocall (function_returning_future())
cocall asyncio.gather(costart(coro1, arg1, arg2), costar(coro2, arg1, arg2))

协程生成器

通过 async for 关键字可以实现一种协程生成器的概念，即一个带有 yield 或 yield from 的协程。为了避免与一般的生成器混淆，可能需要在 yield 关键字前加上 async 关键字，而 async yield from 会抛出 StopAsyncIteration 异常。

虽然协程生成器的概念可能实现，但是不应该在本提案中讨论。这是一个高阶的概念，会使当前生成器的实现发生巨大的变动，应该权衡利弊，仔细考虑。这个问题应该由一个单独的 PEP 进行讨论。

为什么选择 async 和 await 关键字

在众多编程语言中，async/await 已经不是一个新鲜的概念了：

1. C# 很久以前就是使用它们，请看 引用 5；
2. ECMAScript 7 中也提议键入 async/await，在 Traceur 项目也是，请看 引用 2 和 引用 9；
3. Facebook’s Hack/HHVM，请看 引用 6；
4. Googles Dart 语言，请看 引用 7；
5. Scala，请看 引用 8；
6. 提议在 C++ 添加 async/await，请看 引用 10；
7. 还有很多其他语言…

这是一个巨大的优势，因为这些语言的使用者已经有了使用 async/await 的经验，而这使得在一个项目中使用多种语言（例如在 Python 中使用 ECMAScript 7）变得更加容易。

为什么 __aiter__ 返回的不是可等待对象

PEP 492 在 CPython 3.5.0 被接受，并且新增了 __aiter__ 方法，该方法返回一个解析为异步迭代器的可等待对象。

在 3.5.2 中（PEP 492 被临时接受），__aiter__ 协议被更新为直接返回异步迭代器。

这么做的目的是在 Python 中实现异步生成器，点击 引用 19 和 引用 20 了解更多。

async 关键字的重要性

虽然可以只实现 await 表达式，并且将至少拥有一个 await 的函数视为协程，但这样做会增加 API 设计、代码重构和长期支持的难度。

假设 Python 只有 await 关键字：

1
2
3
4
5
6
7

def useful():
...
await log(...)
...

def important():
await useful()

如果对 useful() 函数进行重构，删除其内部所有 await 表达式，它就会变成一个普通 Python 函数，所有依赖于它的代码（例如 important()）都会产生异常。要想解决这个问题，必须引入类似 @asyncio.coroutine 的装饰器。

为什么使用 async def

直接使用 async name(): pass 可能比 async def name(): pass 更有吸引力，因为这种方式输入的字符更少。但它打破了 async def、async with 和 async for 之间的一致性，其中 async 都是修饰符，表示语句是异步的。此外，它与现有语法更契合。

为什么不使用 await for 和 await with

async 是一个形容词，因此更适合作为修饰词与其他关键字搭配。await for/with 看起来更像是等待 for 或 with 语句执行完成。

为什么使用 async def 而不是 def async

async 关键字是一个语句的修饰符。在其他编程语言中常见的 static、public、unsafe 等关键字是一个很形象的类比。async for 是异步的 for 语句，async with 是异步的 with 语句，async def 是异步函数。

将 async 放在其他关键字后面很可能会引起混淆，例如 for async item in iterator 可以理解为从 iterator 中遍历异步的 item。

将 async 放在 def、with 和 for 前面，还能使语言语法更加简单。同时，async def 也能让使用者更方便地区分协程与普通函数。

为什么不导入 __future__

from __future__ import feature 形式的导入被称为 future 语句。 它们会被 Python 编译器当作特例，通过包含 future 语句来允许新的 Python 特性在该特性成为语言标准之前发布的模块中使用。

过渡计划 章节介绍了词法分析器做了哪些修改使其仅在 async def 块才中将 async 和await 作为关键字处理。因此，async def 发挥了模块级编译器声明（类似 from __future__ import async_await）的作用。

为什么异步魔术方法都用 a 开头

一个备选方案是使用 async 前缀，但是为了让新的魔术方法和原有魔术方法保持尽可能高的相似性，最终选择了方法名更短的方案。

为什么不复用现有魔术方法

存在一个异步迭代器和异步上下文管理器的备选方案，提议在声明中添加 async 关键字来复用现有的魔术方法：

1
2
3
4

class CM:
# 代替 __aenter__
async def __enter__(self):
...

这个方案有以下缺点：

1. 不能创建一个既可以在 with 中使用，又可以在 async with 中使用的对象；
2. 会破坏兼容性，因为在版本低于 3.4 的 Python 代码中没有规定禁止从 __enter__ 或 __exit__ 中返回类 Future 对象；
3. 让原生协程简洁无歧义是本提案主要目的之一，因此将异步协议用的魔术方法做了区分处理。

为什么复用 for 和 with 语句

无论是现有的生成器式协程还是本提案提出的原生协程都更希望使用者能够明显地看到代码可能阻塞的位置。让现有的 for 和 with 语句识别异步迭代器和异步上下文管理器会不可避免地引入隐式阻塞点，从而导致代码变得更难理解。

异步推导式

可以提供异步推导式，但是这个语法不在本提案的讨论范围内。

注：PEP 530 定义了异步推导式，可以在 3.6 之后的版本使用。

异步 lambda 函数

可以提供异步 lambda 函数，但这个语法不在本提案的讨论范围内。

注：目前 Python 还没有解锁异步 lambda。

性能影响

整体影响

本提案不会对 Pyhton 本身的性能产生明显影响。下面是 Python 官方基准测试 的输出结果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

python perf.py -r -b default ../cpython/python.exe ../cpython-aw/python.exe

[skipped]

Report on Darwin ysmac 14.3.0 Darwin Kernel Version 14.3.0:
Mon Mar 23 11:59:05 PDT 2015; root:xnu-2782.20.48~5/RELEASE_X86_64
x86_64 i386

Total CPU cores: 8

### etree_iterparse ###
Min: 0.365359 -> 0.349168: 1.05x faster
Avg: 0.396924 -> 0.379735: 1.05x faster
Significant (t=9.71)
Stddev: 0.01225 -> 0.01277: 1.0423x larger

The following not significant results are hidden, use -v to show them:
django_v2, 2to3, etree_generate, etree_parse, etree_process, fastpickle,
fastunpickle, json_dump_v2, json_load, nbody, regex_v8, tornado_http.

词法分析器的影响

使用修改后的词法分析起解析 Python 文件没有明显的速度减慢：解析一个 12MB 的文件（Lib/test/test_binop.py 重复 1000 次）所需时间（与之前）相同。

async/await 的影响

下面的微型基准测试用于确定异步函数和生成器之间的性能差异：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

import sys
import time

def binary(n):
if n <= 0:
return 1
l = yield from binary(n - 1)
r = yield from binary(n - 1)
return l + 1 + r

async def abinary(n):
if n < 0:
return 1
l = await abinary(n - 1)
    r = await abinary(n - 1)
    return l + 1 + r

def timeit(func, depth, repate):
t0 = time.time()
for _ in range(repeat):
o = func(depth)
try:
while True:
o.send(None)
except StopIteration:
pass
t1 = time.time()
print('{}({}) * {}: total {:.3f}s'.format(func.__name__, depth, repeat, t1-t0))

结果是没有观察到明显的性能差异：

1
2
3
4
5
6
7
8

binary(19) * 30: total 53.321s
abinary(19) * 30: total 55.073s

binary(19) * 30: total 53.361s
abinary(19) * 30: total 51.360s

binary(19) * 30: total 49.438s
abinary(19) * 30: total 51.047s

注 depth = 19 以为着 1048575 次调用。

实施

可以通过 引用 15 追踪具体实施过程，它在 2015-5-11 提交。

引用

1. https://docs.python.org/3/library/asyncio-task.html#asyncio.coroutine
2. http://wiki.ecmascript.org/doku.php?id=strawman:async_functions
3. https://github.com/1st1/cpython/tree/await
4. https://hg.python.org/benchmarks
5. https://msdn.microsoft.com/en-us/library/hh191443.aspx
6. http://docs.hhvm.com/manual/en/hack.async.php
7. https://www.dartlang.org/articles/await-async/
8. http://docs.scala-lang.org/sips/pending/async.html
9. https://github.com/google/traceur-compiler/wiki/LanguageFeatures#async-functions-experimental
10. http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3722.pdf
11. https://docs.python.org/3/reference/expressions.html#generator-iterator-methods
12. https://docs.python.org/3/reference/expressions.html#primaries
13. https://mail.python.org/pipermail/python-dev/2015-May/139851.html
14. https://mail.python.org/pipermail/python-dev/2015-May/139844.html
15. http://bugs.python.org/issue24017
16. https://github.com/python/asyncio/issues/233
17. https://hg.python.org/cpython/rev/7a0a1a4ac639
18. http://bugs.python.org/issue24400
19. http://bugs.python.org/issue27243
20. https://docs.python.org/3/reference/datamodel.html#async-iterators

参考

1. PEP 492 – Coroutines with async and await syntax

本文的主体内容大部分来自对 PEP 318 原文的翻译，剩余部分是本人对原文的理解，在整理过程中我没有刻意地区分二者，这两部分被糅杂在一起形成了本文。因此请不要带着「本文的内容是百分百正确」的想法阅读。如果文中的某些内容让你产生疑惑，你可以给我留言与我讨论或者对比 PEP 318 的原文加以确认。

注：PEP 318 创建于 2003-06-05，Python 2.4

警告和摘要

本文档的主要目的是描述装饰器语法和做出相关决策过程。它既不试图涵盖全部潜在的替代语法，也不试图详尽地罗列出每种语法的优缺点。

当前（Python 2.4 之前）转换一个函数或方法（例如将它们定义为一个类方法或静态方法）的方案很笨拙，并且可能会导致降低代码的可读性。理想情况下，这类转换应该与函数或方法的定义同步进行。本 PEP 为函数或方法实现这类转换引入了全新的语法。

动机

当前（Python 2.4 之前）实现一个函数或方法转换的方案是将转换定义在函数声明的后面。 对于一些大型函数来说，这样做会让函数行为的关键部分与函数外部内容形成割裂感，例如：

1
2
3
4
5
6
7
8
9

def foo(self):
# perform method operation
pass
foo = classmethod(foo)

def bar(cls):
   pass
bar = synchronized(lock)(foo)
bar = classmethod(bar)

这种方案不仅使得那些长函数的可读性变差，还会使得一个单一的概念存在多次声明，很不 pythonic。一个解决此问题的方案是让函数转换贴近函数自身的声明。新语法的意图就是将装饰器放在函数声明中以替代现有方案：

1
2
3
4

@classmethod
@synchronized(lock)
def bar(cls):
pass

以这种形式修改类是完全可行的，尽管这样做的受益并没有那么明显。当然，任何可以使用类装饰器完成的事情都可以使用元类完成。但是使用元类是一种高阶的方案，所以「能以一种更简洁明了的方式对类进行简单修改」是有吸引力的。Python 2.4 中仅添加了函数/方法装饰器。

PEP 3129 建议从 Python 2.6 开始添加类装饰器。

做决定为什么这么难

在 Python 2.2 之后就有两个装饰器（classmethod() 和 staticmethod()）可以被使用。差不多从这时起，大家便认为 Python 最终会在语言层面为它们添加语法上的支持。也许你会好奇，为什么达成最终的共识如此困难（从 Python 2.2 到 Python 2.4）。函数装饰器最佳实现方案相关的讨论在 comp.lang.python 和 python-dev 邮件列表中一直不断，主要的分歧集中在以下几个问题上：

1. 声明位置：几乎所有人都同意，在函数主体声明之后进行转换是不理想的，但具体应该放在哪里并没有形成共识。
2. 语法：Python 是一个语法十分简明的编程语言，为了保持这种简明（无论是体现在直觉上还是具体实现上）它对什么可以做和什么不能做都有相当严格的限制。没有一种特别合适的方法能够让第一次接触这个概念的使用者在看到这种语法时就能快速理解这个语法代表了什么。似乎最好的方案就是能防止初学者对这种语法产生错误的第一印象。
3. 对概念不熟悉：对于那些对代数（甚至基础算数）有一定了解或至少使用过一种其他编程语言的人来说，Python 中大部分语法和概念都是符合直觉的。但是在使用 Python 装饰器之前，很少有人对「装饰器」这个概念有了解，也没有一个较好的类比对象来帮助人们快速的理解。

语法往往比其他任何事情都容易引起更多的争论，[PEP 308] 中与三元运算符语法相关的讨论是另一个例子。

背景

人们普遍认为，以当前的状态，为装饰器提供语法支持是可取的。Guido 也在第十届 Python 大会的 DevDay 主题演讲中提到了对装饰器的语法支持，尽管 他后来说 这只是他在那里半开玩笑地提出的几个拓展之一。在会议结束不久之后，Michael Hudson 在 python-dev 上发布了这个 主题，并将最初的方括号语法归因于 Gareth McCaughan 在 comp.lang.python 上的 早期提案。

类装饰器似乎会顺理成章的成为下一个目标，因为类的定义和函数的定义在语法上是相似的，但 Guido 任然保持怀疑，因此类装饰器几乎可以确认不会在 Python 2.4 中出现。

关于装饰器这个名字

有很多人抱怨为这个特性选择「装饰器」这个名字。其中最主要的原因是这个名字与 GoF 书（设计模式：可复用面向对象软件的基础）中所阐述的概念并不一致。选择「装饰器」这个名字更多的是由于它在编译器领域的使用——语法树被遍历和注释。很可能会出现一个更好的名字（目前看来并没有）。

设计目标

注：译者猜测在设计时还没有明确装饰器这个概念所以原文使用 wrapper 来表示被设计的主体（也就是装饰器）。

新语法应该：

1. 能够适应任何使用场景，包括使用者定义的可调用对象和内置的 classmethod() 以及 staticmethod()。这项需求同时意味着必须能够向 wrapper constructor 传递参数；
2. 允许在一个定义中使用多个 wrappers；
3. 能够明显的表现出它的作用，至少要做到明显，并且初学者在编写自己的代码时可以放心的忽略它；
4. 是一种经过讲解后很容易就记住的语法；
5. 拥有较好的拓展性；
6. 容易使用，在需要使用的地方可以频繁的使用；
7. 不能削弱代码的可读性，让函数的定义保持简明；
8. 不会不必要地增加辅助工具（例如语言敏感的编辑器或其他解析器工具）的复杂性；
9. 允许将来的编译器为装饰器进行优化，由于 Python 的 JIT 编译器有希望在某个时间实现，这就需要装饰器的语法出现在函数声明之前；
10. 从函数声明的尾部移动到头部。

Andrew Kuchling 在他的博客（已经无法访问）中有一些关于动机和用例的讨论的链接，特别值得注意的是 Jim Huginin 的用例列表。

当前语法

在 Python 2.4a2 中实现的函数装饰器的语法是：

1
2
3
4

@dec2
@dec1
def func(arg1, arg2, ...):
pass

这相当于：

1
2
3

def func(arg1, arg2, ...)
pass
func = dec2(dec1(func))

没有对 func 的多次赋值，装饰器就在函数声明的周围，@ 符号能够提醒使用者：这里有一些新特性在起作用。

从上到下逐个起作用的逻辑源自数学中函数应用的通常顺序。在数学中，结构是 (g o f)(x) 的函数会被转换为为 g(f(x))。在 Python 中，@g @f def foo() 会被翻译为 foo=g(f(foo))。

装饰器语句所能接受的内容是有限的（任何表达式都不起作用）。Guido 喜欢这样，因为更符合直觉。

当前语法还允许装饰器声明调用一个返回装饰器的函数：

1
2
3

@decomaker(argA, argB, ...)
def func(arg1, arg2, ...):
pass

这相当于：

1

func = decomaker(argA, argB, ...)(func)

这个语法生效的逻辑是将 @ 符号后面的内容视作一个表达式（语法上被限制为：只能是一个函数），并且无论该表达式返回什么都会被调用。

语法方案讨论

目前已经提出了大量不同的语法，与其试图逐一讨论这些语法，不如将「语法讨论」分成几个方面。试图对每种可能的语法进行讨论是一种疯狂的行为，并且会产生一个非常臃肿的 PEP。

装饰器位置

第一个值得讨论的语法问题是：装饰器的位置。下面的代码示例中会使用 Python 2.4a2 中的最终确定的 @ 符号作为装饰器符号。

def 语句上面

1
2
3
4
5
6
7
8

@clasmethod
def foo(arg1, arg2):
pass

@accepts(int, int)
@returns(float)
def bar(low, high):
pass

人们对这种方案有一些反对意见，其中最主要的是：这是（当时） Python 中第一例某行代码会对下一行代码产生影响的案例。在 2.4a3 版本中要求每行一个装饰器（在 2.4a2 版本中，可以在同一行指定多个装饰器），而 2.4final 的最终决定是每行一个装饰器。也有人抱怨说这种语法会是的在使用多个装饰器时变得笨重。不过有人指出，在一个函数上使用大量装饰器的可能性很小，因此这不是一个大问题。

这种方案的优点是装饰器位于函数声明外部，这使得人们能够直观地理解装饰器会在定义函数时执行。另一个优点是，在函数定义上添加前缀符合在代码本身之前了解代码语义变化的要求。使用者可以正确并快速地理解代码的语义，而不必在阅读代码时反复查看上下文。

Gudio 也更偏向于将装饰器定义在 def 的上一行，因为长的参数列表意味着装饰器可能被忽略。

def 和 函数名之间或函数名和参数列表之间

1
2
3
4
5
6
7
8
9
10
11

def @classmethod foo(arg1, arg2):
pass

def @accept(int, int),@returns(float) bar(low, high):
pass

def foo @classmethod (arg1, arg2):
pass

def bar @accept(int, int),@return(float) (low, high):
pass

这个方案也一些反对意见。首先，它很容易破坏源代码的「可重命名性」，你不再能通过搜索 def foo( 并找到函数定义。第二个更严重的反对意见是，在s使用多个装饰器的情况下语法会显得及其笨重。

函数声明尾部的 : 之前

1
2
3
4
5

def foo(arg1, arg2) @classmethod:
pass

def bar(low, high) @accepts(int, int),@returns(float):
pass

Gudio 总结了反对这个方案的几种论点（其中很多也适用于前一种形式）：

1. 它在签名之后隐藏了关键信息（例如，它是一个静态方法），这很容易被遗漏；
2. 很容易遗忘长参数和长装饰器列表之间的过渡；
3. 使用剪切和粘贴来重用装饰器列表变得很麻烦，因为它在一行的中间开始和结束；

与 docstring 当前所在位置相同

1
2
3
4
5
6
7
8

def foo(arg1, arg2):
@classmethod
pass

def bar(low, high):
@accepts(int, int)
@returns(float)
pass

这种形式的主要缺点是，它需要“窥视”函数内部才能确定装饰器。此外这些位于函数内部的内容，在运行时也不会执行。Gudio 认为 docstring 不是一个很好的反例，并且使用 docstring 来放置装饰器很有可能会使得最终不得不把文档字符串移动到函数声明外部。

创建一个新的代码块

1
2
3
4
5
6
7
8
9
10

decorate:
classmethod
def foo(arg1, arg2):
pass

decorate:
accepts(int, int)
returns(float)
def bar(low, high):
pass

这种形式会导致使用装饰器函数和没使用装饰器的函数的缩进不一致，另外被装饰的函数的声明需要写在第三层缩进。

语法形式

@decorator

1
2
3
4
5
6
7
8

@classmethod
def foo(arg1, arg2):
pass

@accepts(int,int)
@returns(float)
def bar(low,high):
    pass

反对这种语法的主要理由是 @ 符号从未在 Python 中使用过（但是在 IPython 和 Leo 中都有使用），并且 @ 符号没有意义。另外一种反对意见是，这种方案浪费了一种从未使用的字符（一个有限的集合），这些字符应该被用在更重要的场合。

|decorator

1
2
3
4
5
6
7
8

|classmethod
def foo(arg1,arg2):
    pass

|accepts(int,int)
|returns(float)
def bar(low,high):
    pass

这是 @decorator 的变体，它的优点是不会破坏 IPython 和 Leo，主要缺点是符号 | 看起来既像大写的 I 又像小写的 l。

列表语法

1
2
3
4
5
6
7

[classmethod]
def foo(arg1,arg2):
    pass

[accepts(int,int), returns(float)]
def bar(low,high):
    pass

列表语法最重要的缺点是它在 Python 中是有具体含义的，其次它也不能很好地表明该表达式是一个装饰器。

使用其他符号的列表语法

1
2
3
4
5
6
7

<classmethod>
def foo(arg1,arg2):
    pass

<accepts(int,int), returns(float)>
def bar(low,high):
    pass

这些替代方案都没有获得太多支持。使用双方括号的替代方案只是为了表明这是一个装饰器不是一个列表，并没有使解析变得更容易。尖括号的替代方案也存在解析问题，因为 < 和 > 都有独立的含义，对于装饰器来说 > 可能是一个大于号而不是装饰器定义的关闭符号。

decorate()

decorate() 的方案是不实现新的语法，而是实现一个能够使用内省来控制其后面紧跟的函数的内置函数。Jp Calderone 和 Philip Eby 都实现了这样的函数。Gudio 非常坚决地反对这样（不使用新的语法）做，这种方案带来了极大的不确定性。

新的关键字（和块）

这个想法是 comp.lang.python 的共识替代方案，在下面的 [社区共识](# 社区共识) 中有更多关于这一点的内容。Robert Brewer 写了一份详细的 J2 提案文件（无法访问），概述了支持这种形式的论点。初始问题是：

1. 需要一个新的关键字，因此需要一个 from __future__ import decorators 语句。
2. 关键词的选择是有争议的。然而， using 作为共识选择出现，并在提案和实现中使用。
3. 关键字/块形式产生的东西看起来像一个正常的代码块，但不是。尝试在此块中使用语句将导致语法错误，这可能会使使用者感到困惑。

几天后，Guido 基于 两个主要理由 拒绝了这项提议。

其他形式

在 维基页面 上还有很多其他的变体和提案。

为什么使用 @

在 Java 的历史中，@ 最初在 Javadoc comments 中使用被作为标记，后来在 Java 1.5 中用于 annotations，类似于 Python 装饰器。在此之前，@ 从未在 Python 中用作标记，这样的代码不能被早期的 Python 版本解析，可能会导致微妙的语义错误。这也意味着什么是装饰器，什么不是的模糊性被消除了。也就是说，@ 仍然是一个相当随意的选择。有些人建议使用 |。

后记

在原文中还有两部分分别描述了最终实施的过程和一些示例，这里我就不展示了，感兴趣的可以自行翻阅原文。

参考

1. PEP 318 – Decorators for Functions and Methods
2. PEP 20 – The Zen of Python

1. Django 笔记-1-从请求到响应
2. Django 笔记-2-源码理解-urls 篇

前言

最近春节假期在家闲着无聊，就顺着之前阅读 Django Url 模块的劲头开始读起了 Django 的源码和文档。在阅读 Django 文档 的过程中，我第一次发现 Django 文档实际的组织方式，于是便有了这篇文章。

脉络梳理

我们打开 Django 文档时一般看到的都是 根目录，在根目录下 Django 很贴心地使用副标题分割出了 16 个话题，并在相应的话题下面对话题所包含的内容进行展开和索引。这很好，当我对 Django 中某个部分（模块）产生疑惑的时候我都能够通过这个页面快速定位到对应的页面。我一度认为 Django 的文档就是通过话题进行组织的，但在我上次想要通读 Django 文档时，我从页面右侧我老早就发现但是从未点击的目录按钮进入到了 Django 文档真实的组织架构页面：目录页。

根据 目录页 可以看出 Django 文档实际被分为了 9 部分（忽略索引和词汇表），分别是：

1. 开始 | intro：通过一个简单的教程帮助初学者快速掌握 Django 开发的能力。
2. 使用 Django | topics：重点，将 Django 中较为关键部分的概念以主题的形式进行介绍。
3. 操作指南 | howto：一些常用流程的整理，个人觉得没啥用，这些大都能通过搜索引擎找到更加细致的回答。
4. Django FAQ | faq：一些常见问题的解答，其中关于如何 寻求帮助 和 如何贡献代码 的部分可以根据需要阅读一下。
5. API 参考 | ref：重点，将 Django 中较为关键部分的接口设计以主题的形式进行介绍。
6. 元文件和杂记 | misc：不要被标题迷惑，里面存放的是 Django 的设计理念，内容不多可以读一下。
7. 术语 | glossary：没啥用，总结的并不全面。
8. 发行说明 | releases：重点，Django 的发版日志，用于了解不同 Django 版本之间的区别。
9. Django 内部 | internals：重点，如果你是期望更加深入的了解、讨论或参与 Django，这里里面的章节就都适合读一读。

竖线前是章节的中文翻译，竖线后是对应的 url path。

根目录 实际上是将 目录页 中的大部分内容通过话题的形式进行重新组合的产物。

阅读方式

首次使用

适合场景：第一次了解 Django，想要快速掌握 Django 的使用方法。

这时候可以阅读 开始 部分，里面的教程几乎是每个 Django 入门者的必经之路。

搜索阅读

适合场景：遇到一些比较生僻的概念，直接丢到搜索引擎没办法快速理解。

这时候就可以尝试将这个概念丢到 Django 文档右上角的搜索框中，它会为你列出在文档中所有出现过这个概念的地方。

有两个需要注意的点：

1. 只建议搜索概念性的问题，搜索词尽可能是一个单词；
2. 建议先使用英语搜索，找到搜索结果后再切换到中文（如果没有英文阅读方法）。

概念阅读

适合场景：希望能够准确掌握 Django 中某个概念 50% 以上的内容。

这时候可以通过 根目录 配合目录页的 使用 Django 和 API 参考 阅读相关的内容。

这样做能够使你快速从零开始了解一个 Django 概念，并掌握其 50% 以上的内容（如何使用），剩下的部分（具体代码实现）则需要阅读 Django 源码来补齐。

通读

适用场景：希望对 Django 有一个全面了解，进一步掌握 Django。

这时候可以以根目录中 模型层 以下的主题为索引，从目录页的 使用 Django 和 API 参考 找到相应的章节，先读 使用 Django 中的概念讲解，再读 API 参考 中的接口设计。

关于翻译

Django 文档虽然有较为全面的中文翻译，但是从我阅读的体验来看绝大多数应该是机翻，而且因为文档中有大量的引用格式，导致在汉化的过程中会存在解析失败的情况，所以有能力的最好还是直接阅读英文版。实在不行我也建议中英文混合阅读，可以中文英文各开一个页面，也可以使用能够保留英文原文的翻译插件。

Django 社区

在 Django 内部 | internals 中有对 Django 社区的全面介绍，这里只简单介绍几个常用的：

1. Github 源码：没有 Issue；
2. Django 论坛： 可以提问或者宣传自己的 Django 项目；
3. Django 邮件列表：Django 有几个官方的邮件列表，感兴趣的话可以去文档里翻找一下；
4. Django Issues：Django 独立的 issue 提交平台，可以在这里提交或搜索你遇到的 bug；

注：上面的几个社区平台基本全是英文的，所以需要一定的英语阅读方法；

参考

1. Django 文档-4.2-中文

1. Django 笔记-1-从请求到响应

前言

注：本文使用 Django 版本：4.2.x

最近在处理公司接口端（基于 DRF）业务逻辑的时候想要通过 DRF 的 DefaultRouter 定制化一个类似 Swagger 的 API 页面展示，但是在编写路由解析方法的时候却犯了难。之前我能只理解了如何使用 Django urls 模块中的方法生成满足业务需求的路由，但是我还真没研究过怎么收集现有路由，并进行遍历和反向解析，于是便有了此次源码阅读。

本文以 Django 初始化和请求流程为主线，研究在这个过程中 Django 的 urls 模块做了哪些工作，并不是详细讲解 urls 模块下的全部方法。

流程梳理

本章以最常用的 python manage.py runserve 为例，梳理 Django 初始化和请求流程。这里为了阅读体验简化了步骤，想了解更完整的请求流程可搭配 Django 笔记-1-从请求到响应 进行阅读：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

python manage.py runserver
    ↓
django.core.management.commands.runserver.Command.handle
    ↓
runserver.Command.run(**options)
    ↓
runserver.Command.inner_run
    ↓  handler=runserver.Command.get_handler()
↓                     ↓
↓  django.core.wsgi.get_wsgi_application() → django.core.handlers.wsgi.WSGIHandler()
django.core.servers.basehttp.run(..., wsgi_handler=handler, ...)
    ↓
django.core.servers.basehttp.WSGIServer.serve_forever()
↓ ← request 请求进入
  .....
  ↓
django.core.servers.basehttp.WSGIRequestHandler.handle_one_request()
↓
django.core.servers.basehttp.ServerHandler.run(self.server.get_app())
↓
self.server.get_app()()
↓
django.core.handlers.wsgi.WSGIHandler()()
↓
django.core.handlers.wsgi.WSGIHandler.__call__
    ↓
django.core.handlers.wsgi.WSGIHandler.get_response(request)
    ↓
django.core.handlers.wsgi.WSGIHandler._middleware_chain(request)
    ↓ 
django.core.handlers.wsgi.WSGIHandler._get_response
    ↓
django.core.handlers.wsgi.WSGIHandler.resolve_request
    ↓
django.urls.resolvers.URLResolver(settings.ROOT_URLCONF).resolve(request.path_info)
    ↓ return (callback, callback_args, callback_kwargs) from URLResolver.resolve(request.path_info)
   ...
    ↓
response = callback(request, ...)

可以看到最后最关键的部分是调用了 django.urls.resolvers.URLResolver(settings.ROOT_URLCONF).resolve(request.path_info) 这样的一个方法，而这一个链式调用是由 django.core.handlers.wsgi.WSGIHandler.resolve_request 产生的，下面我们就以 resolve_request 方法为入口详细分析整个 urls 模块的调用链。

resolve_request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# django.core.handlers.base.BaseHandler（WSGIHandler 的父类）
def resolve_request(self, request):  
# 一般来说 request 是没有 urlconf 的所以走的是 else
    if hasattr(request, 'urlconf'):
        urlconf = request.urlconf  
        set_urlconf(urlconf)  
        resolver = get_resolver(urlconf)  
    else:  
        resolver = get_resolver()  
    resolver_match = resolver.resolve(request.path_info)  
    request.resolver_match = resolver_match  
    return resolver_match

# django.urls.get_resolver
def get_resolver(urlconf=None):  
    if urlconf is None:  
        urlconf = settings.ROOT_URLCONF  
    return _get_cached_resolver(urlconf)

# django.urls._get_cached_resolver
@functools.lru_cache(maxsize=None)  
def _get_cached_resolver(urlconf=None):  
    return URLResolver(RegexPattern(r'^/'), urlconf)

# 通过这三个方法的链式调用我们能够得知最终在 resolve_request 使用的 resolver 是
# URLResolver(RegexPattern(r'^/'), settings.ROOT_URLCONF)
# 从函数调用上我们还可以发现，Django 使用 functools.lru_cache 将整个 resolver 的结果缓存下来了

settings.ROOT_URLCONF

Django 文档对于 settings.ROOT_URLCONF 的定义是：

ROOT_URLCONF
默认：未定义

一个字符串，代表你的根 URLconf 的完整 Python 导入路径，例如 “mydjangoapps.urls”。可以通过在传入的 HttpRequest 对象上设置属性 urlconf 来覆盖每个请求。详情请参见 Django 如何处理一个请求。

一般情况下就是我们使用 django-admin startproject <projectname> 启动项目后在 <projectname> 目录下的 urls.py 模块，这里为了方便讲解我们模拟这样一个项目：

1
2
3
4
5
6
7
8
9
10
11

testapp\
apps.py
views.py
urls.py
testproject\
__init__.py
asgi.py
settings.py
urls.py
wsgi.py
manage.py

其中几个重要文件的内容分别为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

#testapp.views
from django.http.response import HttpResponse

def test(request):
return HttpResponse("test")


#testapp.urls
from .views import test  
from django.urls import re_path  
  
app_name = "testapp"  
urlpatterns = [  
    re_path(r'^test-api/', test, name="testapi"),  
]

#testproject.urls
from django.contrib import admin  
from django.urls import path, re_path, include  
  
urlpatterns = [  
    path('admin/', admin.site.urls),
    re_path(r'^test2/', test, name="test2"),  
    re_path('test/', include("testapp.urls", namespace="test")),
]

path, re_path, include

通过观察 testproject.urls 不难看出在 Django 项目下注册路由主要是通过 django.urls 模块下的 path，re_path 和 include 三个方法，我们先观察一下这三个方法的定义：

1
2
3
4
5
6
7
8
9
10
11

# django.urls.conf.py
from functools import partial

def include(arg, namespace=None):
pass

def _path(route, view, kwargs=None, name=None, Pattern=None):
pass

path = partial(_path, Pattern=RoutePattern)
re_path = partial(_path, Pattern=RegexPattern)

将定义中使用 partial 的部分替换后可得

1
2
3
4

path = _path(..., Pattern=RoutePattern)
re_path = _path(..., Pattern=RegexPattern)

include(arg, namespace=None)

re_path(‘test/‘, include(“testapp.urls”, namespace=”testapp”))

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

# django.urls.conf
from importlib import import_module

# include("testapp.urls", namespace="test")
def include(arg, namespace=None):
# arg = "testapp.urls"
# namespace = "test"
    app_name = None
    if isinstance(arg, tuple):
    # 如果 arg 是元组则解包成 路由模块 和 应用名称
        try:  
            urlconf_module, app_name = arg  
        except ValueError:  
            if namespace:  
                raise ImproperlyConfigured(...)  
            raise ImproperlyConfigured(...)  
    else:
    # 否则 路由模块 就是 arg
        urlconf_module = arg  

    if isinstance(urlconf_module, str):  
    # 如果 urlconf_module 是字符串尝试导入
        urlconf_module = import_module(urlconf_module)  

    # 从 路由模块 中获取 路由模式 和 应用名称
    patterns = getattr(urlconf_module, "urlpatterns", urlconf_module)  
    app_name = getattr(urlconf_module, "app_name", app_name)  

    if namespace and not app_name:  
        raise ImproperlyConfigured(...)  

# 如果没有 namespace 那么将 app_name 设置为 namespace
    namespace = namespace or app_name 

# [re_path(r'^test-api/', test, name="testapi")]
# 检查 路由模式 中的 匹配项 是否存在问题
    if isinstance(patterns, (list, tuple)):  
        for url_pattern in patterns:  
            pattern = getattr(url_pattern, "pattern", None)  
            if isinstance(pattern, LocalePrefixPattern):  
            # 这里为什么对 LocalePrefixPattern 报错我不是很理解一下是 AI 给出的回答：
            # 在 include 中不允许使用 i18n_patterns
            # 是因为 Django 的国际化和本地化系统（i18n）的设计限制
            # i18n_patterns 是用于在 URL 中添加语言前缀的便捷方法
            # 但由于其特性，它只能在主 URL 配置中使用
            # 这种限制是为了确保URL配置的一致性和可维护性。
            # 如果允许在包含的URL配置中使用i18n_patterns，
            # 可能会导致混乱和不一致的URL结构，从而增加了维护和调试的复杂性。
# 因此，为了遵循最佳实践并确保代码的清晰性，
# Django限制了i18n_patterns的使用范围，只允许在主URL配置中使用。
                raise ImproperlyConfigured(...)

    # 可以看到 include 方法最终是将传入的内容解析成了一个三元元组
    # 分别是 路由模块、应用名称和命名空间
# 返回 (<testapp.urls>, "testapp", "test")
    return (urlconf_module, app_name, namespace)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# django.urls.conf
# admin.site.urls 具体的对应关系可以去 django.contrib.admin.sites.AdminSite 查看
# path('admin/', admin.site.urls) 
# _path('admin/', (self.get_urls(), "admin", self.name), Pattern=RoutePattern)

# re_path('test2/', test)
# _path('test2/', test, Pattern=RegexPattern)

# re_path('test/', (<testapp.urls>, "testapp", "test"))
# _path('test/', (<testapp.urls>, "testapp", "test"), Pattern=RegexPattern)
def _path(route, view, kwargs=None, name=None, Pattern=None):  
    from django.views import View
  
    if kwargs is not None and not isinstance(kwargs, dict):  
        raise TypeError(...)
    if isinstance(view, (list, tuple)):
    # 如果 view 是数组或元组，使用 RegexPattern 实例化匹配规则并返回 URLResolver 解析器
        pattern = Pattern(route, is_endpoint=False)  
        urlconf_module, app_name, namespace = view  
        return URLResolver(  
            pattern,  
            urlconf_module,  
            kwargs,  
            app_name=app_name,  
            namespace=namespace,  
        )
    elif callable(view):  
    # 如果 view 是可调用对象，使用 RoutePattern 实例化匹配规则并返回 URLPattern 匹配器
        pattern = Pattern(route, name=name, is_endpoint=True)  
        return URLPattern(pattern, view, kwargs, name)  
    elif isinstance(view, View):  
        view_cls_name = view.__class__.__name__  
        raise TypeError(...)  
    else:  
        raise TypeError(...)

RoutePattern 与 RegexPattern

RoutePattern 与 RegexPattern 最后都会被转换为正则匹配，只是 RoutePattern 在定义的时候可以使用特殊的语法定义参数变量，而 RegexPattern 则需要使用正则匹配去表达这些内容，例如 RoutePattern('foo/<int:pk>') 会被转换为 RegexPattern('^foo\\/(?P<pk>[0-9]+)')。感兴趣的可以看一下 django.urls.resolvers._route_to_regex 方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# django.urls.resolvers.py
class LocaleRegexDescriptor:
# LocaleRegexDescriptor 是一个描述器，可以查看 参考文章3 进行学习
# 这个描述器的功能还是比较简单的大概理解就是：
# 初始化时设置一个变量名称为 attr 的属性名称
# 将调用实例中名字和变量 attr 相同的属性复制给 pattern
# 将调用实例的 regx 属性设置为调用实例的 _compile(pattern) 的返回值
# 看文字一大串好像很难理解
# **其实就是把传给 RoutePattern 或 RegexPattern 的匹配字符串变成一个正则对象**
# 之所以搞这么多步骤主要是为了在调用 __get__ 方法的时候设置一些国际化相关的内容
    def __init__(self, attr):  
        self.attr = attr  

    def __get__(self, instance, cls=None):  
    if instance is None:  
            return self  
        pattern = getattr(instance, self.attr)  
        if isinstance(pattern, str):  
            instance.__dict__["regex"] = instance._compile(pattern)  
            return instance.__dict__["regex"]  
        language_code = get_language()  
        if language_code not in instance._regex_dict:  
            instance._regex_dict[language_code] = instance._compile(str(pattern))  
        return instance._regex_dict[language_code]

class RoutePattern(CheckURLMixin):  
    regex = LocaleRegexDescriptor("_route")  
  
    def __init__(self, route, name=None, is_endpoint=False): 
    # 一般来说 route 就是调用 path 或 re_path 时传入的那个用于做路由匹配的字符串
    # path('admin/', admin.site.urls)  中的 admin/
        self._route = route  
        self._regex_dict = {}  
        self._is_endpoint = is_endpoint  
        self.name = name
        self.converters = _route_to_regex(str(route), is_endpoint)[1]

def match(self, path):
# 在解析是被调用的匹配方法，很重要但是没什么难懂的地方
    match = self.regex.search(path)  
    if match:  
        kwargs = match.groupdict()  
        for key, value in kwargs.items():  
            converter = self.converters[key]  
            try:  
                kwargs[key] = converter.to_python(value)  
            except ValueError:  
                return None  
        return path[match.end() :], (), kwargs  
    return None

def _compile(self, route):  
    return re.compile(_route_to_regex(route, self._is_endpoint)[0])

class RegexPattern(CheckURLMixin):  
    regex = LocaleRegexDescriptor("_regex")  
  
    def __init__(self, regex, name=None, is_endpoint=False):
    # 同上，只是不叫 route 叫 regx
    # re_path('test/', (<testapp.urls>, "testapp", "test")) 中的 test/
        self._regex = regex  
        self._regex_dict = {}  
        self._is_endpoint = is_endpoint  
        self.name = name  
        self.converters = {}

def match(self, path):
# 在解析是被调用的匹配方法，很重要但是没什么难懂的地方
    match = (  
        self.regex.fullmatch(path)  
        if self._is_endpoint and self.regex.pattern.endswith("$")  
        else self.regex.search(path)  
    )  
    if match:  
        kwargs = match.groupdict()  
        args = () if kwargs else match.groups()  
        kwargs = {k: v for k, v in kwargs.items() if v is not None}  
        return path[match.end() :], args, kwargs  
    return None

def _compile(self, regex):  
try:  
return re.compile(regex)  
except re.error as e:  
raise ImproperlyConfigured(...) from e

URLPattern 与 URLResolver

URLPattern 与 URLResolver 是不同模式路由匹配方案，URLPattern 用于定义简单路由基本上可以理解为一个萝卜一个坑，一个 URLPattern 只负责一个视图的匹配，而 URLResolver 则是通过命名空间和应用名称将一组路由（这一组路由中也可能只有一个路由）汇集到一起用于匹配。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# django.urls.resolvers.py
class ResolverMatch:
# 用于路由匹配解析结果的类，主要的方法是 __getitem__ 方法
# 最后会使用 __gititem__ 进行解包操作
def __init__(self, func, args, kwargs, url_name=None, app_names=None, namespaces=None, route=None, ...):
self.func = func
self.args = args
self.kwargs = kwargs
...

def __getitem__(self, index):  
    return (self.func, self.args, self.kwargs)[index]

class URLPattern:
    def __init__(self, pattern, callback, default_args=None, name=None):  
        self.pattern = pattern  
        self.callback = callback  # the view  
        self.default_args = default_args or {}  
        self.name = name
        ...
        
    def resolve(self, path):  
    match = self.pattern.match(path)  
    if match:
        new_path, args, captured_kwargs = match  
        kwargs = {**captured_kwargs, **self.default_args}  
        return ResolverMatch(  
            self.callback,  
            args,  
            kwargs,  
            self.pattern.name,  
            route=str(self.pattern),  
            captured_kwargs=captured_kwargs,  
            extra_kwargs=self.default_args,  
        )

class URLResolver:  
    def __init__(  
        self, pattern, urlconf_name, default_kwargs=None, app_name=None, namespace=None  
    ):  
        self.pattern = pattern  
        self.urlconf_name = urlconf_name  
        self.callback = None  
        self.default_kwargs = default_kwargs or {}  
        self.namespace = namespace  
        self.app_name = app_name  
        self._reverse_dict = {}  
        self._namespace_dict = {}  
        self._app_dict = {}  
        self._callback_strs = set()  
        self._populated = False  
        self._local = Local()

def resolve(self, path):  
# URLResolver.resolve 方法是一个比较绕的执行流程
# 感兴趣的话可以将前面得到的结果拿过来然后自己模拟输入一些路径来尝试匹配
# 例如 _path('test/', (<testapp.urls>, "testapp", "test"), Pattern=RegexPattern).resolve(<request_path>)
    path = str(path)
    tried = []  
    match = self.pattern.match(path)  
    if match:  
        new_path, args, kwargs = match  
        for pattern in self.url_patterns:  
            try:  
                sub_match = pattern.resolve(new_path)
            except Resolver404 as e:  
                self._extend_tried(tried, pattern, e.args[0].get("tried"))  
            else:  
                if sub_match:  
                    sub_match_dict = {**kwargs, **self.default_kwargs}  
                    sub_match_dict.update(sub_match.kwargs)  
                    sub_match_args = sub_match.args  
                    if not sub_match_dict:  
                        sub_match_args = args + sub_match.args  
                    current_route = (  
                        ""  
                        if isinstance(pattern, URLPattern)  
                        else str(pattern.pattern)  
                    )  
                    self._extend_tried(tried, pattern, sub_match.tried)  
                    return ResolverMatch(
                        sub_match.func,  
                        sub_match_args,  
                        sub_match_dict,  
                        sub_match.url_name,  
                        [self.app_name] + sub_match.app_names,  
                        [self.namespace] + sub_match.namespaces,  
                        self._join_route(current_route, sub_match.route),  
                        tried,  
                        captured_kwargs=sub_match.captured_kwargs,  
                        extra_kwargs={  
                            **self.default_kwargs,  
                            **sub_match.extra_kwargs,  
                        },  
                    )  
                tried.append([pattern])  
        raise Resolver404({"tried": tried, "path": new_path})  
    raise Resolver404({"path": path})

调用出栈

伴随着 URLPattern 与 URLResolver 被理解，我们可以沿着目录开始一层一层的将调用结果出栈，最终返回到 resolve_request 的最后三行：

1
2
3
4
5
6
7
8
9
10
11
12
13

# django.core.handler.base.BaseHandler.resolve_request
resolver_match = resolver.resolve(request.path_info)  
request.resolver_match = resolver_match
# 这里返回的就是一个 ResolverMatch 对象
return resolver_match

# django.core.handler.base.BaseHandler._get_response
# 这里通过解包调用 ResolverMatch 对象的 __getitem__ 方法
callback, callback_args, callback_kwargs = self.resolve_request(request)
...
# 最终经过一系列过程大概会执行一个类似这样的方法
# 其中 callback 就是根据 request 信息，通过 url 匹配获取到的视图方法
response = callback(request, ...)

1
2
3
4
5
6
7
8
9

path('admin/', admin.site.urls),
re_path(r'^test2/', test, name="test2"),  
re_path('test/', include("testapp.urls", namespace="test")),
               re_path(r'^test-api/', test, name="testapi"),  
我们的 urlpatterns 类似上面这样，这里我们可以想象一下：假设有一个 /test2/ 请求进入会怎么进行：
1. 首先是走到 _get_cached_resolver(urlconf=None) 返回的 URLResolver(RegexPattern(r'^/'), urlconf)
2. URLResolver(RegexPattern(r'^/')） 将 /test2/ 中的 / 拿走，剩余 test2/ 继续匹配
3. 匹配到 test2/ 最终执行 test 方法
4. 将匹配结果返回，最终 django.core.handler.base.BaseHandler._get_response 调用 test 方法

参考

1. Django 文档
2. Django 4.2.x 源码
3. Python 文档-描述器

原文：Kraken Technologies: How we organise our very large Python monolith
作者：David Seddon from Kraken Technologies
翻译：RyomaHan | 小白
提示：本文是原作者以第一人称书写，翻译时未做更改

TLDR(AI-Claude)

本文来自一位 Python 开发者对一个庞大的 Python 项目的代码组织结构的总结。

该项目包含近 3万个 Python 文件,由全球 400 多名开发者共同维护。为了应对代码日益增长的复杂性,项目采用了分层架构的设计。即将代码库划分为多个层级,并限制不同层级之间的依赖关系,依赖只能从上层流向下层。

文章详细介绍了该项目的分层结构,以及如何利用 Import Linter 工具来强制执行分层规则。通过追踪被忽略的非法 import 语句数量,可以衡量分层结构实现的进度。

分层架构确实能够有效降低大型项目的复杂度,方便独立开发。但也存在一些缺点,比如容易在高层产生过多代码,完全实施分层需要花费时间等。总体来说,尽早引入分层架构,能够减少后期的重构工作量,是管理大型 Python 项目的一个有效方式。

本文通过一个真实的大规模 Python 项目案例,生动地介绍了分层架构的实施过程、优势和不足,对于管理大型项目很有借鉴作用。

前言

大家好，我是来自 Kraken Technologies 的 Python 开发者， David。我在的 Kraken 工作是维护一个Python 应用，根据最新统计它拥有 27637 个模块的 。是的，你没看错，这个项目拥有近 28K 独立的 Python 文件（不包括测试代码）。我与全球其他 400 名开发人员一同维护这个庞然大物，不断地为它合并新的代码。任何人只需要在 Github 上获得一位同事的批准，就能修改代码文件，并启动软件的部署，该软件在 17 家不同的能源和公用事业公司运行着，拥有数百万的客户群体。

看到上面的描述，你大概率会下意识地认为这个项目的代码肯定无比的混乱。坦白讲，我也会这么想。但事实是，至少在我工作的领域，大量的开发人员可以在一个大型的 Python 项目上高效地工作。实现这个目标的要素有很多，其中许多要素来自文化与规则而非技术，在本篇博文中，我想着重讲一下我们是如何通过优化代码组织结构来实现这一目标的。

分层架构

如果你已经负责维护某个应用的代码仓库一段时间，肯定会感受到随着时间的推移代码复杂度越来越高。在不断开发与维护的过程中，应用中各部分的逻辑代码混合在一起，独立地分析应用中的某个模块变得越来越困难。这也是我们早期维护代码仓库时遇到的问题，经过研究后我们决定采用分层架构（即将代码库划分成多个组件（也就是层级，后面不再注释），并限制各组件间的引用关系）来应对这一问题。

分层（Layering）是一种较为常见的软件架构模式，在这种模式下不同的组件（即层级，后面不在重复注释）会被以（概念上）栈的形式组织起来。在这个栈中，下层组件不能依赖（引入）其上层组件。

例如，在上图中，C 可以依赖 B 和 A，但不能依赖 D。

分层架构的应用很宽泛，你可以自由地定义组件。例如：你可以将多个可独立部署的服务视作多个组件，也可以直接将项目中不同部分的源码文件视作不同的组件。

依赖关系的定义也很宽泛。通常，只要两个组件间存在直接交叉（即使只发生在概念层级上），我们就认为它们之间存在依赖关系。间接交叉（例如通过配置传递）通常不被视为依赖关系。

如何在 Python 项目中应用分层架构

分层架构在 Python 项目中的最佳实践是：将 Python 模块作为分层依据，将导入语句视为依赖依据。

以如下项目仓库目录举例：

1
2
3
4
5
6
7
8

myproject
__init__.py
payments/
__init__.py
api.py
vendor.py
products.py
shopping_cart.py

目录中模块之间的嵌套关系是分层的最佳依据。假设，我们决定按照一下顺序进行分层：

1
2
3
4

# 依赖关系向下流动（即上层可以依赖下层）
shopping_cart
payments
products

为了满足上述架构的要求，我们需要禁止 payments 中的模块从 shopping_cart 模块中引入内容，但可以从 products 模块中引入内容（参考图 1）。

分层也可以嵌套，因此我们可以在 payments 模块中继续分层，例如：

1
2

api
vendor

设置多少分层以及以什么顺序进行排列没有唯一正确的答案，需要我们不断的在实践中总结。但是合理的运用分层架构确实能够有效地降低项目结构的复杂度，使其能够更易于理解和修改。

我们是如何在 Kraken 的项目中实践分层架构的

在我编写这边文章的时候，已经有 17 家不同的能源和公共事业相关的企业购买了 Kraken 的许可证。我们在内部称呼这些企业为 client，并为每一家企业都运行了一个独立的实例。也正因如此，Kraken 的不同实例间形成了一种「同根不同枝」的特点。通俗地讲就是不同实例间的很多行为其实是共享的，但是每个 client 也都有属于自己的定制代码，以满足他们特定的需求。从地域层面来讲也如此，在英国运行的所有 client 之间存在一定的共性（他们属于同类的能源行业），而日本的 Octopus Energy 则不共享这些的共性。

随着 Kraken 平台的成长，我们也在不断地优化着我们的分成架构，来帮助我们更好地满足不同客户的需求。目前的分层的顶层结构大致如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 依赖关系向下流动（即上层可以依赖下层）
kraken/
    __init__.py
    
    client/
        __init__.py
        oede/
        oegb/
        oejp/
        ...
    
    territories/
        __init__.py
        deu/
        gbr/
        jpn/
        ...
    
    core/

client 组件在结构的顶部。每一个 client 在该层都有一个专属的子包（例如，oede 对应 Octopus Energy Germany）。在此之下的是 territories 组件，用于满足不用国家所需的特定行为，同样为不同地区设置了不同的子包。最底层是 core 组件，包含了所用 client 都会用到的通用代码。我们还制定了一个特别的规则：client 组件下的子包必须是独立的（即不能被其他 client 引用），territories 组件下的子包也是如此。

将 Kraken 以这种分层结构构建之后，我们可以在有限的区域内（例如一个组件的子包）便捷地进行代码的更新和维护。由于 client 组件位于结构的顶部，因此不会有任何其他组件会直接依赖于它，这样我们就能更方便地更改特定 client 有关的内容，而且不必但因会影响到其他 client 的行为。同样，只更改 territories 组件内的一个子包也不会影响到其他的子包。这样，我们就可以快速、独立地进行跨团队开发，尤其是当我们进行的更改只影响少量 Kraken 实例的时候。

通过 Import Linter 确保项目中的分层实现

虽然引入了分层结构，但我们很快发现，仅仅在理论上论述分层是不够的。开发人员经常会不小心进行分层间的违规引入。我们需要以某种方式确保分层结构的理论能够在代码结构中被遵循，为了达到此目的我们在项目中引入了第三方库 Import Linter。

Import Linter 是一款开源工具，用于检查项目中的引用逻辑是否遵循了指定的结构。首先，我们需要在一个 INI 文件中定义一个描述目标需求的配置，类似这样：

1
2
3
4
5
6
7
8

[importlinter:contract:top-level]

name = Top level layers
type = layers
layers =
    kraken.clients
    kraken.territories
    Kraken.core

我们还可以使用另外两个配置文件强制不同的 clients、territories 之间相互独立。类似这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 文件 1
[importlinter:contract:client-independence]
name = Client independence
type = independence
layers =
    kraken.clients.oede
    kraken.clients.oegb
    kraken.clients.oejp
    ...

# 文件 2
[importlinter:contract:territory-independence]
name = Territory independence
type = independence
layers =
    kraken.territories.deu
    kraken.territories.gbr
    kraken.territories.jpn
    ...

然后，你可以在命令行运行 lint-import，它会告诉你项目中是否有任何导入行为违反了我们配置中的要求。我们会在每次拉取代码的时候运行此功能，因此如果有人使用了不合规的导入，检查就会失败，代码也就不会被合并。

上面展示的并不是我们项目全部的配置文件。团队成员可以在应用程序的更深处添加自己的分层，例如：kranken.ritories.jpn 本身就是分层。我们目前拥有超过 40 个配置文件用于规定我们的分层结构。

消除技术债

我们没有办法在确定是由分层架构的第一时间就使整个项目符合架构需求。因此，我们使用了 Import Linter 中的一项特性，该功能允许您在检查非法导入之前忽略对某些导入的检查。

1
2
3
4
5
6
7
8
9
10
11
12

[importlinter:contract:my-layers-contract]
name = My contract
type = layers
layers =
    kraken.clients
    kraken.territories
    kraken.core
ignore_imports =
    kraken.core.customers ->
    kraken.territories.gbr.customers.views
    kraken.territories.jpn.payments -> kraken.utils.urls
    (and so on...)

此后，我们使用项目构建时被 Import Linter 忽略的导入语句的数量作为跟踪技术债完成度的指标。这样，我们就能观察到随着时间的推移技术债的情况是否有所改善，以及改善的速度如何。

上图是我们过去一年多的时间里被我们忽略的有问题的引入语句数量的变化。我会定期分享这张图，想大家展示我们最新的工作进度，并鼓励我们的开发者努力做到完全遵守分层结构的约定。我们对其他几个技术债也使用了这种燃尽图的方法去展示。

没有银弹，谈谈分层架构的缺点

复杂现实

现实世界无比的复杂，依赖关系遍布在项目的各个角落。在采用分层架构后，你会经常遇到想要打破现有层级关系的情况，会经常在不经意间从低层级的组件中调用高层级的组件。

幸运的是，总有办法解决这类问题，那就是所谓的 控制反转（Ioc），在 Python 中你可以很容易地做到这一点，只是需要转换一下思维方式。不过使用这个方法会增加「局部复杂性」，但为了让项目整体变得更加简单，这点代价还是值得的。

结构中高层代码过多

在分层结构中，层数越高的组件天然地越容易更改。正因如此，我们特地简化了修改特定 clinents 或 territories 的代码流程。另一方面，core 是一切其他代码的基础，修改它就成为了一件高成本、高风险的事情。

高成本、高风险的底层代码修改行为让我们望而却步，促使我们编写更多针对特定客户或地区的高层级代码。最终的结果就是，高层的代码比我们想象中要多的多的多。我们仍在学习如何解决这个问题。

目前为止我们仍未完全完成

还记得之前提到过的被设置在 Import Linter 特殊配置文件中被忽略的 import 吗？多年过去了，它仍未被全部解决，根据统计还有最少 15 个。最后的这几个 import 也是最顽固、最难以被优化的。

我们需要付出很多的时间才能重构完一个现有项目，所以，越早分层需要面对的麻烦就越少。

总结

Kraken 的分层结构使我们在如此庞大的代码体量下仍旧保持着健康的开发和维护，而且操作难度相对较小，特别是在考虑到它的规模的情况下。如果不对数以万计的模块之间的依赖关系加以限制，我们的项目仓库很可能会像揉乱的线团一样复杂。但是我们选择的代码架构顺利的帮助我们在单一的 Python 代码库中进行大量工作。看似不可能，但这就是事实。

如果你正在开发一个大型的 Python 项目，或者哪怕是一个相对较小的项目，不发试试分层结构，还是那句话：越早分层需要面对的麻烦就越少。

最近公司的一个新项目上马，我被安排来做项目初始化，前端初始化的时候使用了 Vue3 + Tailwind CSS + NaiveUI，在搞基础布局的主题变化时出现了本次插曲。

基础背景

• 我使用的 AI 工具是安装在自己 Slack 频道的 Claude App；
• 我对 Tailwind CSS 的实现原理一无所知，我只知道简单的使用方法。

具体问题

按照设计，Web PC 端的左侧边栏有一排导航按钮，这些导航按钮在 light 模式下应该是白底，在 dark 模式下应该是 Naive UI 的默认底色。按照需求描述，只需要使用 Tailwind CSS 来实现「仅在 light 模式下修改指定按钮背景色为白色」就行了。

可坑爹的是 Tailwind CSS 只提供了 dark:bg-white 的写法而没有类似 light:bg-white 的写法，按照正常写法可以使用 class="bg-white dark:bg-[#需要的颜色]" 来处理。但是我不希望这样写，因为 dark 模式下 UI 按钮组件默认的底色就是我所需的，所以我没理由再去强调 dark 模式下的底色是什么，我只需要使用类似 light:!bg-white 的写法来强制覆盖 light 模式下 UI 按钮组件的底色就行。

开始踩坑

于是我开始了无休止的 AI 辅助编程：

直接提问

注：这一步我的诉求是让 AI 帮忙直接生成解决方案。

我最开始的思路是直接将问题描述清楚，让 AI 帮忙生成解决方案，于是：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

ryomahan  [5:26 PM]

Tailwind CSS 有没有类似 light:bg-white 的写法

ClaudeAPP  [5:26 PM]

在 Tailwind CSS 中,确实有类似 light:bg-white 这样的写法。这叫做 variant。Tailwind CSS 支持几种 variant:- responsive:用于响应式设计,如 sm:bg-white 表示在小屏幕上使用 bg-white 类  
- hover/focus/active:用于鼠标交互状态,如 hover:bg-white 表示鼠标悬停时使用 bg-white 类  
- dark:用于暗色模式,如 dark:bg-white 表示在暗色模式下使用 bg-white 类  
- light:用于亮色模式,如 light:bg-white 表示在亮色模式下使用 bg-white 类所以,如果你想在亮色模式下应用 bg-white 类,可以写成:

html
<div class="light:bg-white bg-gray-800">...</div>

这个 div 在亮色模式下会有 bg-white 类,在暗色模式下会有 bg-gray-800 类。除此之外,Tailwind CSS 还有很多其他的 variant,可以在官方文档中找到:[https://tailwindcss.com/docs/variants](https://tailwindcss.com/docs/variants)希望这个解释可以帮助你!有任何其他问题 feel free 问我。

马后炮：其实这里已经将问题的核心点出来了，即 Tailwind CSS 实现类似 dark: 的写法是通过一种叫做 variant 的概念来实现的，Tailwind CSS 本身提供了一些基础写法，并且给出了文档。

我当时着急直接得到解决方案，便以为 <div class="light:bg-white bg-gray-800">...</div> 就是我想要的答案，但是拿到项目代码中测试发现不管用。于是便开始了下一次问答，而无视了这条答案中最重要的那句话：在 Tailwind CSS 中,确实有类似 light:bg-white 这样的写法。这叫做 variant。

在直接提问这个思路下我又尝试问过如下几个问题：

• Tailwind CSS 中与 dark:bg-whtie 对立的表达是什么
• Tailwind CSS 怎样才能使得 bg-white 仅对 light theme 有效对 dark mode 无效
• tailwind css how to make style invalid in drak mode

得到的答案都不是我想要的东西，于是我开始转换思路。

从原理提问

注：这一步我的诉求是让 AI 帮忙直接生成解决方案。

经过直接提问发现无法得到我想要的答案，于是我开始尝试从实现原理层面进行引导，让 AI 帮忙生成解决方案，我尝试过如下提问：

• 如何创建类似 dark:* 的自定义形式
• Tailwind CSS 如何自定义实现类似 dark:* 的效果
• Tailwind CSS 如何自定义实现类似 dark:* 的功能，例如 custom:*
• Tailwind CSS 如何自定义实现类似 dark:* 的功能实现 light:* 使得其后面跟随的 style 仅在 light mode 生效
• Tailwind CSS 中如何实现类似 dark:bg-white 的效果使得 bg-white 仅在 light mode 生效

经过这几次提问之后我发现其中多个答案都在配置文件中提到了 variants 这项配置，于是：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

ryomahan  [7:09 PM]

variants 是什么

ClaudeAPP  [7:09 PM]

variants 是 Tailwind CSS 一个很强大的功能。它允许你为某些类定义不同的变体(variants),然后在使用这些类时,可以通过如 dark: 前缀来选择使用哪个变体。比如说,对于背景颜色 bg-blue 这个类,你可以定义两个变体:

js
variants: {
  backgroundColor: ['responsive', 'dark']
} 

这定义了 responsive 和 dark 两个变体。然后在使用时,可以这样写:
- bg-blue - 选择默认的变体  
- dark:bg-blue - 选择 dark 变体  
- responsive:bg-blue - 选择 responsive 变体所以通过 variants,一个类可以有多种样式,你可以根据需要选择使用哪个变体。variants 常见的使用场景有:- 定义 light/dark 模式下的样式  
- 定义不同 breakpoint 下的响应式样式  
- 定义不同互动状态(hover/focus/active)下的样式  
- ...可以说,variants 是 Tailwind CSS 实现高度可定制和条件化样式的基石功能之一。掌握好了 variants,可以极大提高在 Tailwind 中写 CSS 的能力。总之,variants 是一个非常强大而又重要的 Tailwind CSS 功能,值得深入学习和使用。

马后炮：这个回答其实已经讲了很多有用的信息了。

我还是执着于让 AI 直接给我生成方案，所以我粗略看了一下之后又进行了如下提问：

• 如何为默认变体提供 alias 到 light
• 在 Tailwind CSS 中如何使用 variants 使得 light:bg-white
• 在 Tailwind CSS 中如何使用 variants 使得 light:bg-white 等同于 bg-white
• 在 Tailwind CSS 中如何使用 variants 使得 <div class="bg-white"> 等同于 <div class="light:bg-white">
• 如何应用到全部 style 上（因为上一个回答我感觉有点靠谱所以又追问这个问题）
• 没用（因为我发现它的上个回答并没有生效所以我希望它能够自动修改，结果新生成的内容依旧是没用的）
• Tailwind CSS variants 的作用是什么（这里我觉得还需要再理解一下实现原理）
• dark class mode 是如何生效的
• 如何自定义一套 .light 类使得样式仅在 light 模式下生效（不死心，还想再尝试一下）
• lightMode 对应的 class 类是什么（这是针对上个问题的追问）
• 没有效果（哈哈，生成的内容依旧是无效的）
• 必须叫 lightMode 吗（针对上个问题的追问）
• Tailwind css 如何自定义 dark mode class name（因为上面的回答都无效所以我又开了一个新的会话继续提问）
• 没用（依旧没用）
• 按照你的描述修改了配置文件后并不能生效（还是没用）
• 使用上面的配置文件，在 .light class 下 dark:bg-white 没有生效（这里我把我使用的配置文件贴上去了，因为内容太长就不复制过来了）
• 使用 Tailwind CSS 时如何使得 bg-white 可以仅在 light mode 生效在 dark mode 不生效（又开了一个新的会话，这已经是第二天了，昨天晚上感觉这是个坑所以就去忙别的了）

其实这一步的所有提问基本都是在做无用功，因为我太执着于直接获取解决方案而忽略了解决问题的正确流程，我把 AI 想象的过于强大了。

从原理理解

注：这一步我的诉求是让 AI 帮忙解释这一类功能的实现原理，在从原理引导 AI 帮忙生成解决方案。

经过了漫长的无效提问后我开始反思，我在处理问题的过程中太执着于让 AI 直接帮忙生成解决方案了，于是我又转换思路：先让 AI 帮忙阐述实现原理，再从原理入手生成解决方案。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

ryomahan  [9:40 AM]
Tailwind CSS dark mode 实现原理

ClaudeAPP  [9:40 AM]

Tailwind CSS 的 dark mode 实现原理主要有以下几点:1. 定义 dark 模式的颜色变量。Tailwind 在 colors.js 文件中定义了 dark 模式下的颜色变量,例如:

js
colors: {
  // ...
  gray: {
    900: '#202225',
    800: '#2f303d',
    700: '#353646',
    // ...
  }
} 

这些颜色变量会在 build 过程中生成对应的 utility。2. 定义 prefers-color-scheme 相关的 variants。在 variants.js 中定义了:

js
variants: {
  // ...
  prefersColorScheme: ['dark']
}

这表示 dark mode 下会生成 .dark 等 class。3. 在 build 过程中生成 dark mode 的样式。在 build 过程的 variants 阶段,会根据 prefers-color-scheme 的 variants 生成 .dark 等 class,并使用 dark mode 的颜色变量填充这些 class。4. 在 HTML 中使用 prefers-color-scheme media query 加载相应的样式。例如:

html
<link rel="stylesheet" href="tailwind.css">
<link rel="stylesheet" media="prefers-color-scheme: dark" href="tailwind.dark.css">

tailwind.dark.css 是 dark mode 的样式,会在 prefers-color-scheme: dark 条件下被加载。5. 可选:使用 JavaScript 切换模式。可以使用 matchMedia 检测 prefers-color-scheme 的变化,并动态加载样式来实现模式切换。所以总体来说,Tailwind 通过定义 variants、颜色变量和生成不同模式的样式文件来实现 dark mode。hope this helps!

马后炮：回过头来看，这个回答完全没有参考价值，甚至不如前面提到 variants 的那几个回答有价值，所以说 AI 的生成式回答的随机性还是比较坑的。

然后我问了：

• Tailwind CSS 如何表达 .abc .bg-white
• Tailwind CSS 如何匹配父 class
• Tailwind CSS 如何实现父 class 选择器

这里我是想：在当前项目中所谓的主题模式是通过控制 Layout 根 DOM 的 class name 来实现的，当 class 是 dark 时为 dark mode，是 light 时为 light mode。所以只需匹配父类就能够实现我想要的东西。事实证明这个思路确实是没问题的，但是并不是通过简单的 class 实现的。

最终在 Tailwind CSS 的官方文档的引导下我发出了如下提问：

• Tailwind CSS plugin addVariant 如何使用
• 我希望使用 addVariant 实现 class="light:bg-white" 能够转换为如下 CSS .light .light:bg-white { background: #fff }
• 如何让它更加泛化，使得无论 light: 后面跟什么都能转换为对应的 Tailwind CSS
• 我希望最终实现的效果与 dark:* 类似，当有 .light 的父类 css class 时触发 light:*
• 仅保留 .light 就可以了，其他的删掉

经过这四连问之后，我以为找到了解决这个问题的正确途径，因为这几个问题最终得到的结果虽然不能生效但是看上去像是那么回事，于是我整理了之前的问题继续发问：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

ryomahan  [9:58 AM]

在 Tailwind CSS 中使用 addVariant 实现如下效果使得 `class="light:*"` 能够与 `class="dark:*"` 类似在有 .light 父 css class 时生效

ClaudeAPP  [9:58 AM]

你可以这样使用 Tailwind 的 addVariant 功能来实现这个效果:

js
addVariant('light', ({ modifySelectors, separator }) => {
  modifySelectors(({ className }) => {
    return `.light ${className}`
  })
})

这段代码会添加一个 light 变体,使得任何使用 light: 作为前缀的类都会在 .light 父元素下生效。例如:

html
<div class="light">
  <p class="light:bg-blue-500">...</p>
</div>

这个 p 元素会具有 bg-blue-500 这个类,因为 light:bg-blue-500 在 .light 元素下生效了。如果没有 .light 父元素,light: 类就不会生效,和 Tailwind 的 dark: 变体一致。所以这给你实现了和 dark: 类似的机制,来根据父元素开启某些样式。Hope this helps! Let me know if you have any other questions. (edited)

这是 AI 给我的方案中距离正确答案最近的一次 ，但是仍旧无效，我又在这个问题的基础上尝试了十几轮的询问，得到的答案都是无效的。

自我救赎

在经历昨天下午两个小时外加今天上午两个小时的 AI 问询无果后，我悟了：就当从来没有 AI，早些时候我怎么解决问题现在还怎么解决，于是：

1. 我在一些前端群里发求助信息，与人交流；
2. 同时我开始下载 Tailwind CSS 源码开始审查源码看源码是如何实现 dark mode 的。

整个流程大概持续了十分钟左右的时间，我解决了这个问题，其实如果不去群里发求助信息一上来就看源码的话应该三两分钟就能解决问题。

完整搜索路径：先在 Tailwind CSS 中全局搜索 dark，看了一些结果发现都不是，好多都是测试用例或者其他无关文件中的。于是将搜索范围调整到 src 目录，大概视察了一下后定位在了一个叫 darkVariants 的变量上，跳转到指定文件后果然就是 dark mode 的定义原文，原文如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

darkVariants: ({ config, addVariant }) => {
  let [mode, className = '.dark'] = [].concat(config('darkMode', 'media'))

  if (mode === false) {
    mode = 'media'
    log.warn('darkmode-false', [
      'The `darkMode` option in your Tailwind CSS configuration is set to `false`, which now behaves the same as `media`.',
      'Change `darkMode` to `media` or remove it entirely.',
      'https://tailwindcss.com/docs/upgrade-guide#remove-dark-mode-configuration',
    ])
  }

  if (mode === 'class') {
    addVariant('dark', `:is(${className} &)`)
  } else if (mode === 'media') {
    addVariant('dark', '@media (prefers-color-scheme: dark)')
  }
}