FastAPI项目模板 及 快速开发范式

1. 核心原则

• 简洁至上：避免过度设计。优先选择简单直接的方案。
• 一致性：团队成员遵循相同的规范，降低沟通和维护成本。
• 自动化：利用工具自动完成格式化、检查等重复性工作。

---

2. 虚拟环境与依赖管理

目标：隔离项目依赖，保证环境一致性。

规范：

• 工具：使用 Python 内置的 venv 模块。

  • 创建虚拟环境：在项目根目录执行 python -m venv venv。.gitignore 文件应包含 venv/ 目录。
  • 激活环境：
    • macOS/Linux: source venv/bin/activate
    • Windows: .\venv\Scripts\activate

• 依赖管理：

  • 使用 pip 和 requirements.txt 文件。
  • 安装依赖：pip install -r requirements.txt
  • 更新依赖文件：完成开发或添加新包后，运行 pip freeze > requirements.txt 更新依赖列表。或手动修改依赖列表。
  • (可选) 开发依赖：可以创建一个 requirements-dev.txt 文件，存放仅在开发时使用的工具（如 pytest, black），并将其 include 到主 requirements.txt 中或分开安装。

---

3. 项目结构

目标：清晰、模块化，便于快速定位代码。

推荐一个可扩展的结构：

your_project_name/
├── src/                      # 主要应用代码
│   ├── __init__.py
│   ├── main.py               # FastAPI 应用实例、全局配置、根路由
│   ├── routers/              # 业务逻辑路由
│   │   ├── __init__.py
│   │   ├── users.py          # 用户相关的路由
│   │   └── items.py          # 物品相关的路由
│   ├── services/             # 业务逻辑层 (当业务复杂时，将复杂逻辑拆分到此处)
│   │   ├── __init__.py
│   │   ├── users.py
│   │   └── items.py
│   ├── models/               # 数据模型 (如 Pydantic 模型)
│   │   ├── __init__.py
│   │   └── user.py           # 用户数据模型
│   ├── db/                   # 数据库相关配置与连接
│   │   ├── __init__.py
│   │   └── database.py
│   └── utils/                # 常用工具函数
│       ├── __init__.py
│       └── tools.py
│
├── tests/                    # 测试代码
│   ├── __init__.py
│   └── test_users.py         # 用户模块的测试
│
├── .gitignore                # Git 忽略文件
├── README.md                 # 项目说明文档
├── requirements.txt          # 项目依赖列表
├── Dockerfile                # Docker 配置文件
├── .env.example              # 环境变量文件模板
└── .env                      # 环境变量文件 (不提交到Git)

说明:

• main.py: 只做最核心的初始化和包含各个 router。
• .env: 存放环境变量，如数据库连接信息、密钥等。
• .env.example: 示例环境变量文件，用于创建 .env 文件。
• Dockerfile: Dockerfile 文件，用于构建镜像。
• requirements.txt: 项目依赖文件，用于安装依赖。
• README.md: 项目说明文档。
• routers: 路由模块，存放各个接口的实现。
• models: 模型模块，存放数据库模型定义。
• utils: 工具模块，存放工具函数。

---

4. 命名规范

目标：遵循 PEP 8，保持代码风格统一。

• 文件和目录：使用小写蛇形命名法 (snake_case)，例如 user_router.py。
• 变量和函数：使用小写蛇形命名法，例如 get_user_by_id, db_session。
• 类和 Pydantic 模型：使用大驼峰命名法 (PascalCase)，例如 UserCreate, ItemSchema。
• 常量：使用全大写蛇形命名法，例如 DATABASE_URL, API_PREFIX。
• FastAPI 路由函数：建议以 动作_资源 的方式命名，例如 read_users, create_item。

---

5. 编码习惯与最佳实践

• 代码格式化：

  • 强制使用 black。black 是一个无妥协的代码格式化工具，能消除所有关于格式的争论。
  • 使用 isort 对 import 语句进行排序。
  • 在 CI/CD 或 Git pre-commit hook 中加入自动格式化检查。

• 代码质量检查 (Linter)：

  • 使用 flake8 或更现代的 ruff 进行代码风格和潜在错误的检查。

• FastAPI 实践：

  • 善用依赖注入 (Depends)：将数据库会话、用户认证等逻辑通过 Depends 注入到路由函数中，实现逻辑复用和解耦。
  • 当router逻辑繁重时，考虑分离功能：如果路由逻辑过于复杂，考虑将复杂逻辑提取到单独的函数中，放置在service层，并调用。
  • 异步优先：对于 I/O 密集型操作（如数据库查询、外部 API 请求），始终使用 async def 和 await。
  • 统一日志输出：使用 uvcrion 的 from uvicorn.server import logger 来捕获特定异常，并返回统一格式的错误响应。例子：logger.error(f"Error: {e}")
  • 配置管理：使用 os.getenv("ENV_VAR_NAME", "default_value") 从配置文件和环境变量中加载配置。

• 类型提示 (Type Hinting)：

  • 强制要求：为所有函数参数和返回值添加类型提示。这是 FastAPI 的核心特性之一，能提供强大的编辑器支持和自动文档生成。

---

6. 版本控制 (Git)

• 分支模型：

  • main (或 master) 分支：用于部署的稳定版本。只接受来自 develop 的合并。
  • develop 分支：用于集成各个功能开发的分支。
  • faet/xxx 分支：从 develop 创建，用于开发新功能。开发完成后合并回 develop。
  • fix/xxx 分支：用于修复 main 分支上的紧急 bug。
  • dev/xxx 分支：从 develop 创建，用于开发新功能。开发完成后合并回 develop。

• Commit Message：

  • 约定格式：推荐使用 "Conventional Commits" 规范。
    • feat: add new user registration endpoint (新功能)
    • fix: correct password hashing algorithm (修复 Bug)
    • docs: update README with setup instructions (文档)
    • style: format code with black (格式化)
    • refactor: restructure database session handling (重构)
    • test: add tests for user creation (测试)
  • 这样做的好处是提交历史清晰，便于追溯和自动生成更新日志。

---

7. 测试

• 框架：使用 pytest。
• 工具：结合 FastAPI 的 TestClient 和 HTTPX 来发送模拟请求。
• 要求：核心业务逻辑和重要的 API 端点必须有单元测试或集成测试覆盖。
• 数据库：测试时应使用一个独立的测试数据库，并在每次测试前后清理数据。

---

总结

这份范式旨在为小型 FastAPI 团队提供一个简单、易于上手的起点。最重要的不是规则本身，而是团队达成共识并持续遵守。随着项目和团队的发展，可以随时对这些规范进行调整和补充。

工具链建议:

• 虚拟环境: venv
• 依赖管理: pip + requirements.txt
• 代码格式化: black, isort
• 代码检查: ruff (推荐) 或 flake8
• 测试: pytest
• 版本控制: Git