# 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`