FastAPI 项目开发与文档贡献指南

FastAPI 项目开发与文档贡献指南

fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi

环境搭建与开发流程

虚拟环境配置

在开始 FastAPI 开发前，强烈建议创建一个独立的 Python 虚拟环境。虚拟环境能隔离项目依赖，避免与其他项目产生冲突。创建虚拟环境后，激活它并安装项目依赖：

pip install -r requirements.txt

这个命令会安装 FastAPI 及其所有开发依赖项，包括测试框架、文档生成工具等。

本地开发模式

FastAPI 项目采用"可编辑安装"模式（通过 -e 选项），这意味着：

1. 你对源代码的修改会立即生效
2. 无需每次修改后重新安装
3. 可以直接运行示例代码测试你的修改

这种模式通过在 requirements.txt 中指定 -e . 实现，是 Python 开发中的常见实践。

代码质量保障

代码格式化

项目提供了自动化代码格式化脚本：

bash scripts/format.sh

这个脚本会：

• 自动格式化 Python 代码（使用 Black）
• 排序导入语句（使用 isort）
• 保持代码风格一致性

测试覆盖率

FastAPI 采用严格的测试策略：

bash scripts/test-cov-html.sh

执行后会生成 HTML 格式的覆盖率报告，位于 ./htmlcov/ 目录。打开 index.html 可以：

• 查看哪些代码被测试覆盖
• 发现未被测试的代码区域
• 交互式探索测试细节

文档系统详解

文档实时预览

FastAPI 文档系统基于 MkDocs 构建，支持实时预览：

python ./scripts/docs.py live

或者手动方式：

cd docs/en/
mkdocs serve --dev-addr 127.0.0.1:8008

文档系统特点：

• 自动重载：修改文档后浏览器自动刷新
• 端口 8008：避免与示例应用端口(8000)冲突
• 结构化内容：文档与代码示例分离

文档与测试的联动

FastAPI 采用文档驱动开发模式：

1. 文档中的代码示例都是可运行的完整应用
2. 这些示例存放在 ./docs_src/ 目录
3. 测试框架会验证文档中的每个示例
4. 确保文档与代码保持同步

这种设计带来了多重好处：

• 文档永远不会过时
• 示例代码保证可用
• 测试覆盖了文档描述的所有功能

多语言翻译指南

翻译工作流程

1. 选择目标语言：确定语言的 ISO 639-1 代码（如西班牙语是 es）
2. 复制英文文档：从 docs/en/docs/ 复制到对应语言目录
3. 翻译内容：保持代码块不变，仅翻译文本部分
4. 实时预览：使用 python ./scripts/docs.py live [语言代码] 查看效果

翻译注意事项

• 不要翻译：

  • 代码块中的代码（仅翻译注释）
  • 以 /// 开头的特殊标记（仅翻译 | 后的内容）
  • 内联代码（`...` 包裹的内容）
  • 图片路径和文档链接

• 需要翻译：

  • 普通段落文本
  • 代码块中的注释
  • 警告框等提示性文字
  • 章节标题

新增语言支持

为新语言创建翻译目录：

python ./scripts/docs.py new-lang [语言代码]

这会生成：

1. docs/[语言代码]/mkdocs.yml 配置文件
2. 初始的 index.md 文件
3. 基础目录结构

最佳实践建议

1. 小步提交：每次提交只翻译一个页面，便于审查
2. 保持一致性：遵循现有翻译风格
3. 协作审查：参与已有翻译的审查工作
4. 关注讨论：加入对应语言的翻译讨论组

通过遵循这些指南，你可以高效地为 FastAPI 项目做出贡献，无论是代码开发还是文档翻译，都能确保工作质量与项目标准一致。

fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi