开发 - 贡献指南

首先，您可能想了解帮助 FastAPI 及获取帮助的基本方式。

开发

如果您已经克隆了 fastapi 代码库并希望深入代码，以下是一些设置环境的指南。

虚拟环境

按照说明为 fastapi 的内部代码创建并激活一个虚拟环境。

使用 pip 安装依赖

激活环境后，安装所需的包：

$ pip install -r requirements.txt

---> 100%

这将在您的本地环境中安装所有依赖项和本地 FastAPI。

使用您的本地 FastAPI

如果您创建一个导入并使用 FastAPI 的 Python 文件，并使用本地环境中的 Python 运行它，它将使用您克隆的本地 FastAPI 源代码。

当您再次运行该 Python 文件时，如果您更新了本地 FastAPI 源代码，它将使用您刚刚编辑的最新版本的 FastAPI。

这样，您无需“安装”本地版本即可测试每个更改。

技术细节

只有在使用此包含的 requirements.txt 安装时才会发生这种情况，而不是直接运行 pip install fastapi。

这是因为在 requirements.txt 文件中，本地版本的 FastAPI 被标记为以“可编辑”模式安装，使用了 -e 选项。

格式化代码

您可以运行一个脚本来格式化并清理所有代码：

$ bash scripts/format.sh

它还会自动排序所有导入。

测试

您可以本地运行一个脚本来测试所有代码并生成 HTML 格式的覆盖率报告：

$ bash scripts/test-cov-html.sh

此命令会生成一个目录 ./htmlcov/，如果您在浏览器中打开文件 ./htmlcov/index.html，可以交互式地探索测试覆盖的代码区域，并注意是否有任何区域缺失。

文档

首先，请确保您按照上述说明设置了环境，这将安装所有必需的依赖项。

文档实时预览

在本地开发期间，有一个脚本可以构建站点并检查任何更改，支持实时重载：

$ python ./scripts/docs.py live

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

它将在 http://127.0.0.1:8008 上提供文档服务。

这样，您可以编辑文档/源文件并实时查看更改。

Tip

或者，您可以手动执行该脚本执行的相同步骤。

进入语言目录，对于英文主文档，位于 docs/en/：

$ cd docs/en/

然后在该目录中运行 mkdocs：

$ mkdocs serve --dev-addr 127.0.0.1:8008

Typer CLI (可选)

这里的说明向您展示了如何直接使用 python 程序运行 ./scripts/docs.py 中的脚本。

但您也可以使用 Typer CLI，安装完成后，您将在终端中获得命令的自动补全功能。

如果您安装了 Typer CLI，可以使用以下命令安装自动补全：

$ typer --install-completion

zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.

文档结构

文档使用 MkDocs。

并且有额外的工具/脚本位于 ./scripts/docs.py 中处理翻译。

Tip

您不需要查看 ./scripts/docs.py 中的代码，只需在命令行中使用它。

所有文档都以 Markdown 格式位于 ./docs/en/ 目录中。

许多教程包含代码块。

在大多数情况下，这些代码块是实际完整的应用程序，可以直接运行。

实际上，这些代码块不是写在 Markdown 中的，它们是位于 ./docs_src/ 目录中的 Python 文件。

在生成站点时，这些 Python 文件被包含/注入到文档中。

文档测试

大多数测试实际上针对文档中的示例源文件运行。

这有助于确保：

• 文档是最新的。
• 文档示例可以直接运行。
• 大部分功能由文档覆盖，并通过测试覆盖率确保。

同时运行应用和文档

如果您运行示例，例如：

$ fastapi dev tutorial001.py

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

由于 Uvicorn 默认使用端口 8000，端口 8008 上的文档不会冲突。

翻译

注意

关于翻译的更新

我们正在更新处理文档翻译的方式。

到目前为止，我们邀请社区成员通过拉取请求翻译页面，然后由至少两名母语人士审核。虽然这有助于将 FastAPI 带给更多用户，但我们也遇到了一些挑战 - 有些语言只有少数页面被翻译，其他语言的翻译则已过时且难以维护。 为了改进这一点，我们正在开发自动化工具 🤖 以更有效地管理翻译。准备就绪后，文档将由机器翻译，并在发布前仍由至少两名母语人士审核 ✅。这将使我们能够保持翻译的最新性，同时减少维护者的审核负担。

现在的变化：

• 🚫 我们不再接受社区提交的新翻译 PR。

• ⏳ 现有的开放 PR 将被审核，如果在未来 3 周内（自 2025 年 7 月 11 日起）完成，仍然可以合并。

• 🌐 将来，我们只支持至少有三位活跃母语人士可用以审核和维护翻译的语言。

这一转变将帮助我们保持翻译更加一致和及时，同时更好地支持我们的贡献者 🙌。感谢所有迄今为止做出贡献的人——您的帮助非常宝贵！💖

翻译方面的帮助非常受欢迎！而且这离不开社区的帮助。🌎 🚀

以下是帮助翻译的步骤。

提示和指南

• 检查当前针对您语言的现有拉取请求。您可以通过语言标签过滤拉取请求。例如，对于西班牙语，标签是 lang-es。

• 审核这些拉取请求，请求更改或批准它们。对于我不会说的语言，我会等待其他几个人审核翻译后再合并。

Tip

您可以向现有拉取请求添加更改建议的评论。

查看关于添加拉取请求审核以批准或请求更改的文档。

• 检查是否有GitHub 讨论来协调您语言的翻译。您可以订阅它，当有新的拉取请求需要审核时，会自动在讨论中添加评论。

• 如果您翻译页面，请为每个翻译的页面提交一个单独的拉取请求。这将使其他人更容易审核。

• 要检查您要翻译的语言的 2 字母代码，可以使用表格 ISO 639-1 代码列表。

现有语言

假设您想为一个已经有部分页面翻译的语言（如西班牙语）翻译一个页面。

对于西班牙语，2 字母代码是 es。因此，西班牙语翻译的目录位于 docs/es/。

Tip

主要（“官方”）语言是英语，位于 docs/en/。

现在为西班牙语文档运行实时服务器：

// 使用命令 "live" 并将语言代码作为 CLI 参数传递
$ python ./scripts/docs.py live es

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

Tip

或者，您可以手动执行该脚本执行的相同步骤。

进入语言目录，对于西班牙语翻译，位于 docs/es/：

$ cd docs/es/

然后在该目录中运行 mkdocs：

$ mkdocs serve --dev-addr 127.0.0.1:8008

现在您可以转到 http://127.0.0.1:8008 并实时查看您的更改。

您将看到每种语言都有所有页面。但有些页面未翻译，顶部有一个关于缺失翻译的信息框。

现在假设您想为 特性 部分添加翻译。

• 复制位于以下位置的文件：

docs/en/docs/features.md

• 将其粘贴到您要翻译的语言的完全相同的位置，例如：

docs/es/docs/features.md

Tip

请注意，路径和文件名中唯一的变化是语言代码，从 en 变为 es。

如果您转到浏览器，您将看到文档现在显示您的新部分（顶部的信息框消失了）。🎉

现在您可以翻译所有内容，并在保存文件时查看效果。

不要翻译这些页面

🚨 不要翻译：

• reference/ 下的文件
• release-notes.md
• fastapi-people.md
• external-links.md
• newsletter.md
• management-tasks.md
• management.md
• contributing.md

其中一些文件更新非常频繁，翻译总是会落后，或者它们包含来自英文源文件的主要内容等。

请求新语言

假设您想请求翻译一种尚未翻译的语言，甚至没有一些页面。例如，拉丁语。

如果没有该语言的讨论，您可以先请求新语言。为此，您可以按照以下步骤操作：

• 按照模板创建一个新的讨论。
• 找几位母语人士在讨论中评论并承诺帮助审核该语言的翻译。

一旦讨论中有几个人，FastAPI 团队可以评估并将其设为官方翻译。

然后文档将使用 AI 自动翻译，母语人士团队可以审核翻译，并帮助调整 AI 提示。

一旦有新的翻译，例如文档更新或新部分，将在同一讨论中发表评论，并提供要审核的新翻译链接。

新语言

Note

这些步骤将由 FastAPI 团队执行。

检查上面的链接（ISO 639-1 代码列表），您可以看到拉丁语的 2 字母代码是 la。

现在您可以为新语言创建一个新目录，运行以下脚本：

// 使用命令 new-lang，将语言代码作为 CLI 参数传递
$ python ./scripts/docs.py new-lang la

Successfully initialized: docs/la

现在您可以在代码编辑器中检查新创建的目录 docs/la/。

该命令创建了一个文件 docs/la/mkdocs.yml，其中包含一个简单的配置，该配置继承了 en 版本的所有内容：

INHERIT: ../en/mkdocs.yml

Tip

您也可以手动创建具有这些内容的文件。

该命令还为主页创建了一个虚拟文件 docs/la/index.md，您可以从翻译该文件开始。

您可以继续按照“现有语言”的先前说明进行该过程。

您可以使用这两个文件 docs/la/mkdocs.yml 和 docs/la/index.md 提交第一个拉取请求。🎉

预览结果

如前所述，您可以使用 ./scripts/docs.py 的 live 命令预览结果（或使用 mkdocs serve）。

完成后，您还可以测试所有内容，就像在线查看一样，包括所有其他语言。

为此，首先构建所有文档：

// 使用命令 "build-all"，这需要一点时间
$ python ./scripts/docs.py build-all

Building docs for: en
Building docs for: es
Successfully built docs for: es

这会为每种语言构建所有独立的 MkDocs 站点，将它们组合起来，并在 ./site/ 生成最终输出。

然后您可以使用 serve 命令提供该输出：

// 运行 "build-all" 后使用命令 "serve"
$ python ./scripts/docs.py serve

Warning: this is a very simple server. For development, use mkdocs serve instead.
This is here only to preview a site with translations already built.
Make sure you run the build-all command first.
Serving at: http://127.0.0.1:8008

翻译特定提示和指南

• 仅翻译 Markdown 文档 (.md)。不要翻译 ./docs_src 中的代码示例。

• 在 Markdown 文档中的代码块内，翻译注释 (# 注释)，但其余部分保持不变。

• 不要更改任何用“``”括起来的内容（内联代码）。

• 在以 /// 开头的行中，仅翻译 | 之后的文本部分。其余部分保持不变。

• 您可以翻译信息框，例如将 /// warning 翻译为 /// warning | 注意。但不要更改紧接在 /// 之后的单词，它决定了信息框的颜色。

• 不要更改指向图像、代码文件、Markdown 文档的路径。

• 但是，当 Markdown 文档被翻译时，指向其标题的链接中的 #hash-parts 可能会更改。如果可能，请更新这些链接。

  • 使用正则表达式 #[^# ] 在翻译的文档中搜索此类链接。
  • 在已翻译成您语言的所有文档中搜索 your-translated-document.md。例如，VS Code 有一个选项“编辑”->“在文件中查找”。
  • 翻译文档时，不要“预翻译”指向未翻译文档中标题的 #hash-parts。