chenpanliang
3a5cc50d02
添加项目基础结构，包括： - 核心模块(src/main.py) - 路由模块(users/items) - 数据库配置和模型 - 日志工具 - 测试用例 - 项目文档和依赖配置
171 lines
7.6 KiB
Markdown
171 lines
7.6 KiB
Markdown
# 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` |