开发 - 贡献¶
首先，你可能想看看 帮助 FastAPI 并获取帮助 的基本方式。
开发¶
如果你已经克隆了 fastapi 仓库 并希望深入研究代码，以下是设置开发环境的一些指南。
安装需求¶
创建一个虚拟环境，并使用 uv 安装所需的包。
$ uv sync --extra all
---> 100%
这将在你的本地环境中安装所有依赖项以及你的本地 FastAPI。
使用本地 FastAPI¶
如果你创建了一个导入并使用 FastAPI 的 Python 文件，并使用本地环境中的 Python 运行它，它将使用你克隆的本地 FastAPI 源代码。
当你再次运行该 Python 文件时，如果你更新了本地 FastAPI 源代码，它将使用你刚刚编辑的新版本 FastAPI。
这样，你不必为了测试每一次修改而“安装”你的本地版本。
技术细节
这种情况仅在你使用 uv sync --extra all 而非直接运行 pip install fastapi 时发生。
这是因为 uv sync --extra all 默认以“可编辑”模式安装本地版本的 FastAPI。
格式化代码¶
有一个脚本可以运行，它会格式化并清理你所有的代码。
$ 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 Requests）是由 LLM（大语言模型）完成的，并由 FastAPI 团队与各语言母语者社区共同设计的提示词进行引导。
各语言的 LLM 提示词¶
每种语言都有一个目录：https://github.com/fastapi/fastapi/tree/master/docs，在其中你可以看到一个 llm-prompt.md 文件，里面包含了针对该语言的特定提示词。
例如，西班牙语的提示词位于：docs/llm-prompt.md。
如果你发现你的语言中有错误，可以在该语言对应的文件中对提示词提出建议，并要求在更改后重新生成特定的页面。
审查翻译 PR¶
我们不要求母语者对翻译工作流自动生成的 PR 进行批准。但是，你仍然可以审查它们并建议对该语言的 LLM 提示词进行改进，以使未来的翻译更好。
你可以检查目前针对你语言的 现有的合并请求。你可以通过该语言的标签过滤 PR。例如，对于西班牙语，标签是 lang-es。
你也可以审查已经合并的翻译 PR。为此，请前往 已关闭的合并请求 并按你的语言标签进行过滤。例如，对于西班牙语，你可以使用 lang-es。
在审查合并请求时，最好不要在同一个 PR 中提出修改建议，因为它是 LLM 生成的，无法确保小的单独修改能复制到其他类似部分，或者在再次翻译相同内容时能被保留。
不要在翻译 PR 中添加建议，而是通过一个新的 PR 对该语言的 LLM 提示词文件提出建议。例如，对于西班牙语，LLM 提示词文件位于：docs/llm-prompt.md。
提示
查看关于 添加合并请求审查 的文档，以批准或请求更改。
带有针对特定语言 LLM 提示词建议的 PR 需要至少一名母语者的批准。非常感谢你的帮助！
订阅你的语言通知¶
检查是否有 GitHub Discussion 来协调你语言的翻译工作。你可以订阅它，当有新的合并请求需要审查时，会自动在讨论中添加一条评论。
要查看你想要翻译的语言的 2 字母代码，你可以使用 ISO 639-1 代码列表 表格。
申请新语言¶
假设你想要申请翻译一种尚未翻译（甚至连部分页面都没有）的语言。例如，拉丁语。
- 第一步是你需要找到另外 2 个人，愿意和你一起审查该语言的翻译 PR。
- 一旦至少有 3 个人愿意承诺帮助维护该语言，你就可以继续下一步。
- 按照模板创建一个新的讨论。
- 标记其他 2 个将帮助该语言的人，并请他们确认会提供帮助。
一旦讨论中有几个人，FastAPI 团队就可以对其进行评估，并将其确定为官方翻译。
然后文档将使用 LLM 自动翻译，母语者团队可以审查翻译并帮助调整 LLM 提示词。
一旦有了新的翻译（例如文档已更新或有新章节），同一讨论中会有一条带有新翻译链接的评论供审查。
自动化代码与人工智能¶
鼓励你使用所有想要的工具来完成工作并尽可能高效地贡献，包括 AI (LLM) 工具等。尽管如此，贡献应当包含有意义的人类干预、判断、背景等。
如果在 PR 中投入的 人力（例如编写 LLM 提示词）少于 我们 审查它所需投入的精力，请 不要 提交该 PR。
换个角度想：我们自己已经可以编写 LLM 提示词或运行自动化工具了，这比审查外部提交的 PR 更快。
关闭自动化与 AI 生成的 PR¶
如果我们发现看似 AI 生成或以类似方式自动化的 PR，我们将标记并关闭它们。
这同样适用于评论和描述，请不要直接复制粘贴 LLM 生成的内容。
人力资源拒绝服务攻击¶
使用自动化工具和 AI 提交 PR 或评论，迫使我们必须仔细审查和处理，这相当于对我们的人力资源进行了 拒绝服务攻击 (DoS)。
提交者只需投入极少的工作（一个 LLM 提示词），却会在我们这边产生大量的工作量（仔细审查代码）。
请不要这样做。
我们将不得不封禁那些向我们发送垃圾信息、反复提交自动化 PR 或评论的账户。
明智地使用工具¶
正如本叔叔所说：
拥有强大的力量工具，就意味着承担巨大的责任。
避免无意中造成伤害。
你手头有很棒的工具，请明智地使用它们以有效地提供帮助。