chenpanliang
3a5cc50d02
添加项目基础结构，包括： - 核心模块(src/main.py) - 路由模块(users/items) - 数据库配置和模型 - 日志工具 - 测试用例 - 项目文档和依赖配置
7.6 KiB
7.6 KiB
FastAPI项目模板 及 快速开发范式
1. 核心原则
- 简洁至上：避免过度设计。优先选择简单直接的方案。
- 一致性：团队成员遵循相同的规范，降低沟通和维护成本。
- 自动化：利用工具自动完成格式化、检查等重复性工作。
2. 虚拟环境与依赖管理
目标：隔离项目依赖，保证环境一致性。
规范：
-
工具：使用 Python 内置的
venv模块。- 创建虚拟环境：在项目根目录执行
python -m venv venv。.gitignore文件应包含venv/目录。 - 激活环境：
- macOS/Linux:
source venv/bin/activate - Windows:
.\venv\Scripts\activate
- macOS/Linux:
- 创建虚拟环境：在项目根目录执行
-
依赖管理：
- 使用
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(测试)
- 这样做的好处是提交历史清晰，便于追溯和自动生成更新日志。
- 约定格式：推荐使用 "Conventional Commits" 规范。
7. 测试
- 框架：使用
pytest。 - 工具：结合 FastAPI 的
TestClient和HTTPX来发送模拟请求。 - 要求：核心业务逻辑和重要的 API 端点必须有单元测试或集成测试覆盖。
- 数据库：测试时应使用一个独立的测试数据库，并在每次测试前后清理数据。
总结
这份范式旨在为小型 FastAPI 团队提供一个简单、易于上手的起点。最重要的不是规则本身，而是团队达成共识并持续遵守。随着项目和团队的发展，可以随时对这些规范进行调整和补充。
工具链建议:
- 虚拟环境:
venv - 依赖管理:
pip+requirements.txt - 代码格式化:
black,isort - 代码检查:
ruff(推荐) 或flake8 - 测试:
pytest - 版本控制:
Git