开发 - 贡献¶

首先，你可能想了解一些基本的帮助 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 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;">信息</span>:     Uvicorn正在运行于 http://127.0.0.1:8000 (按CTRL+C退出)

由于 Uvicorn 默认使用端口 `8000`，因此端口 `8008` 上的文档不会发生冲突。 ### 翻译非常感谢您的翻译帮助！没有社区的帮助，这项工作无法完成。🌎 🚀 以下是帮助翻译的步骤。 #### 提示和指南 * 检查您所用语言的现有拉取请求。您可以通过标签过滤拉取请求。例如，对于西班牙语，标签是 `lang-es`。 * 审查这些拉取请求，请求更改或批准它们。对于我不懂的语言，我会等待其他几个人审查翻译后再合并。 /// tip 您可以在现有拉取请求中添加带有更改建议的评论。查看有关添加拉取请求审查以批准或请求更改的文档。 /// * 检查是否有 GitHub 讨论来协调您所用语言的翻译。您可以订阅它，当有新的拉取请求需要审查时，讨论中会自动添加一条评论。 * 如果您翻译页面，请为每个翻译的页面添加一个单独的拉取请求。这将使其他人更容易审查。 * 要检查您想要翻译的语言的两位字母代码，您可以使用表格 ISO 639-1 代码列表。 #### 现有语言假设您想为已经有部分页面翻译的语言（如西班牙语）翻译一个页面。对于西班牙语，两位字母代码是 `es`。因此，西班牙语翻译的目录位于 `docs/es/`。 /// tip 主（“官方”）语言是英语，位于 `docs/en/`。 /// 现在运行西班牙语文档的实时服务器：

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

<span style="color: green;">[INFO]</span> 正在提供服务 http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> 开始监视更改
<span style="color: green;">[INFO]</span> 开始检测更改

/// tip 或者，您可以手动执行脚本所做的相同步骤。进入语言目录，对于西班牙语翻译，它在 `docs/es/`：

$ cd docs/es/

然后在那个目录中运行 `mkdocs`：

$ mkdocs serve --dev-addr 8008

/// 现在您可以转到 http://127.0.0.1:8008 并实时查看您的更改。您会看到每种语言都有所有页面。但有些页面尚未翻译，顶部有一个关于缺失翻译的信息框。现在假设您想为 [Features](features.md){.internal-link target=_blank} 部分添加翻译。 * 复制文件：

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` 其中一些文件更新非常频繁，翻译总是会落后，或者它们包含英语源文件的主要内容等。 #### 新语言假设您想为尚未翻译的语言（甚至没有部分页面）添加翻译。假设您想为克里奥尔语添加翻译，而文档中尚未有克里奥尔语。根据上面的链接，克里奥尔语的代码是 `ht`。下一步是运行脚本来生成新的翻译目录：

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

成功初始化: docs/ht

现在你可以在代码编辑器中查看新创建的目录 `docs/ht/`。该命令创建了一个文件 `docs/ht/mkdocs.yml`，其中包含一个简单的配置，继承自 `en` 版本的所有内容：

INHERIT: ../en/mkdocs.yml

/// tip 你也可以手动创建这个文件并填入这些内容。 /// 该命令还为首页创建了一个虚拟文件 `docs/ht/index.md`，你可以从翻译这个文件开始。你可以继续按照之前的“现有语言”的指示进行该过程。你可以用这两个文件 `docs/ht/mkdocs.yml` 和 `docs/ht/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: 这是一个非常简单的服务器。对于开发，请使用 mkdocs serve 代替。
这里仅用于预览已经构建好的翻译站点。
确保你首先运行了 build-all 命令。
Serving at: http://127.0.0.1:8008

#### 翻译特定提示和指南 * 仅翻译 Markdown 文档（`.md`）。不要翻译 `./docs_src` 中的代码示例。 * 在 Markdown 文档的代码块中，翻译注释（`# 注释`），但保持其余部分不变。 * 不要更改任何包含在 "``"（内联代码）中的内容。 * 在以 `///` 开头的行中，仅翻译 ` "... 文本 ..."` 部分。保持其余部分不变。 * 你可以翻译信息框，例如 `/// warning` 可以翻译为 `/// warning | Achtung`。但不要更改 `///` 后面的单词，它决定了信息框的颜色。 * 不要更改链接中指向图片、代码文件、Markdown 文档的路径。 * 然而，当一个 Markdown 文档被翻译时，链接中指向其标题的 `#hash-parts` 可能会改变。如果可能，请更新这些链接。 * 使用正则表达式 `#[^# ]` 在翻译后的文档中搜索此类链接。 * 在你翻译的语言中，搜索所有已经翻译的文档中的 `your-translated-document.md`。例如，VS Code 有一个选项“编辑” -> “在文件中查找”。 * 在翻译文档时，不要“预翻译”指向未翻译文档标题的 `#hash-parts`。