开发 - 贡献

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

开发

如果您已经克隆了 fastapi 仓库 并希望深入研究代码，这里有一些设置环境的指南。

虚拟环境

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

安装依赖

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

pipuv

$ pip install -r requirements.txt

---> 100%

如果您有 uv

$ uv pip install -r requirements.txt

---> 100%

它将安装所有依赖项以及您本地环境中的本地 FastAPI。

使用本地的 FastAPI

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

如果您更新了本地的 FastAPI 源代码，当您再次运行该 Python 文件时，它将使用您刚刚编辑的最新版 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 提供文档服务。

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

提示

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

进入语言目录，对于主要的英文文档，它位于 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 中有一些额外的工具/脚本用于处理翻译。

提示

您无需查看 ./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 端口的文档不会发生冲突。

翻译

注意

翻译更新

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

到目前为止，我们邀请社区成员通过拉取请求（pull request）来翻译页面，这些请求随后会由至少两名母语者进行审查。虽然这帮助我们将 FastAPI 带给了更多的用户，但我们也遇到了一些挑战——一些语言只有少数翻译页面，另一些则已经过时且难以长期维护。为了改善这一点，我们正在开发自动化工具 🤖 以更有效地管理翻译。准备就绪后，文档将进行机器翻译，并在发布前仍由至少两名母语者进行审查 ✅。这将使我们能够保持翻译的及时更新，同时减轻维护者的审查负担。

现在有什么变化

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

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

• 🌐 未来，我们只支持那些有至少三名活跃的母语者可供审查和维护翻译的语言。

这一转变将帮助我们保持翻译的一致性和及时性，同时更好地支持我们的贡献者 🙌。感谢所有迄今为止做出贡献的人——你们的帮助是无价的！💖

非常感谢您对翻译的帮助！没有社区的帮助，这一切都无法完成。🌎 🚀

以下是帮助翻译的步骤。

提示和指南

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

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

提示

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

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

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

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

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

已有语言

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

对于西班牙语，两位字母代码是 es。所以，西班牙语翻译的目录位于 docs/。

提示

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

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

// Use the command "live" and pass the language code as a CLI argument
$ 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

提示

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

进入该语言的目录，对于西班牙语翻译，它位于 docs/

$ cd docs/

然后在该目录中运行 mkdocs

$ mkdocs serve --dev-addr 127.0.0.1:8008

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

您会看到每种语言都有所有的页面。但有些页面没有翻译，并且顶部有一个关于缺少翻译的信息框。

现在假设您想为 功能特性 这一节添加翻译。

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

docs/en/docs/features.md

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

docs/docs/features.md

提示

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

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

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

不要翻译这些页面

🚨 不要翻译

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

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

请求新语言

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

如果该语言还没有相关的讨论，您可以从请求新语言开始。为此，您可以按照以下步骤操作

• 按照模板创建一个新的讨论。
• 让几位母语者在该讨论中发表评论，并承诺帮助审查该语言的翻译。

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

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

当有新的翻译时，例如文档更新或有新章节时，同一个讨论中会有评论，附上需要审查的新翻译链接。

新语言

注意

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

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

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

// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang la

Successfully initialized: docs/la

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

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

INHERIT: ../en/mkdocs.yml

提示

您也可以手动创建那个文件并填入这些内容。

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

您可以继续按照前面“已有语言”的说明进行操作。

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

预览结果

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

完成后，您还可以测试所有内容，使其看起来和在线版本一样，包括所有其他语言。

为此，首先构建所有文档

// Use the command "build-all", this will take a bit
$ python ./scripts/docs.py build-all

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

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

然后您可以用 serve 命令来提供服务

// Use the command "serve" after running "build-all"
$ 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 文档的代码块中，翻译注释（# a comment），但其余部分保持不变。

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

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

• 您可以翻译像 /// warning 这样的信息框，例如翻译成 /// warning | Achtung。但不要更改紧跟在 /// 之后的单词，它决定了信息框的颜色。

• 不要更改指向图片、代码文件、Markdown 文档的链接中的路径。

• 然而，当一个 Markdown 文档被翻译后，指向其标题的链接中的 #hash-parts 可能会改变。如果可能，请更新这些链接。

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