在设计 FastAPI 项目结构时,需要根据项目规模(小型/中型/大型)、项目类型(纯API/全栈应用/微服务)和团队协作需求灵活调整。
以下是针对不同场景的实践指南和示例:
核心设计原则
- 模块化:按功能拆分代码(路由、模型、服务分离)。
- 可扩展性:预留扩展点(如插件机制)。
- 环境隔离:区分开发、测试、生产配置。
- 文档友好:利用 FastAPI 的 OpenAPI 自动生成能力。
项目结构参考模板
小型项目(单一功能,1-2人开发)
my_project/ ├── main.py # 入口文件(路由、逻辑、配置集中管理) ├── requirements.txt └── README.md
适用场景:快速原型、临时工具开发。
中型项目(模块化,团队协作)
my_app/ ├── api/ # 路由层 │ ├── endpoints/ # 按业务拆分路由 │ │ ├── users.py │ │ └── items.py │ └── routers.py # 路由聚合 │ ├── core/ # 核心配置 │ ├── config.py # 环境变量管理 │ └── security.py # 认证逻辑 │ ├── models/ # 数据模型 │ ├── schemas.py # Pydantic模型 │ └── database.py # 数据库连接 │ ├── services/ # 业务逻辑层 │ └── user_service.py │ ├── tests/ # 测试代码 │ ├── test_users.py │ └── conftest.py # pytest fixtures │ ├── static/ # 静态文件(可选) ├── templates/ # 模板引擎(可选) │ ├── main.py # 应用入口 └── requirements.txt
适用场景:标准业务系统(如电商后台、CMS)。
大型项目(微服务架构)
project/ ├── auth_service/ # 独立认证服务 │ └── (结构同中型项目) │ ├── order_service/ # 订单服务 │ └── (结构同中型项目) │ ├── payment_service/ # 支付服务 │ └── (结构同中型项目) │ ├── gateway/ # API网关 │ ├── routes/ │ └── middleware/ # 限流/认证中间件 │ └── shared/ # 公共依赖 ├── common_models/ # 共享数据模型 └── utils/ # 工具类库
适用场景:分布式系统、跨团队协作。
关键组件详解
路由设计(api/ 目录)
- 按业务垂直拆分:每个功能模块独立文件(py,products.py)
- 路由聚合示例:
# api/routers.py from fastapi import APIRouter from .endpoints import users, items router = APIRouter() router.include_router(users.router, prefix="/users", tags=["users"]) router.include_router(items.router, prefix="/items", tags=["items"])
依赖管理(core/ 目录)
全局依赖注入:
# core/dependencies.py from fastapi import Depends def get_db(): db = SessionLocal() try: yield db finally: db.close() # 在路由中使用 @router.get("/{user_id}") async def read_user(user_id: int, db: Session = Depends(get_db)): return db.query(User).filter(User.id == user_id).first()
配置管理(core/config.py)
环境敏感配置分离:
# core/config.py from pydantic import BaseSettings class Settings(BaseSettings): app_name: str = "My API" database_url: str = "sqlite:///./test.db" secret_key: str class Config: env_file = ".env" settings = Settings()
不同项目类型的结构调整
纯API服务
重点组件:
- 强化schemas(数据校验)
- 添加client_sdk/(生成调用SDK)
- 完善docs/(API文档)
全栈应用(含前端页面)
新增目录:
templates/ # Jinja2模板 static/ ├── css/ ├── js/ └── images/
数据密集型服务
扩展结构:
data/ ├── migrations/ # 数据库迁移脚本 └── analytics/ # 数据分析脚本
自动化与工具集成
项目脚手架(Cookiecutter模板)
pip install cookiecutter cookiecutter https://github.com/tiangolo/full-stack-fastapi-postgresql
代码质量工具
# pyproject.toml [tool.black] line-length = 88 [tool.isort] profile = "black" [tool.mypy] strict = true
CI/CD 配置
# .github/workflows/test.yml name: Test on: [push] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Run tests run: | pip install -r requirements.txt pytest -v
演进式设计建议
- 初始阶段:从简单结构开始,避免过度设计
- 规模扩展时:
- 当单个文件超过 500 行时拆分模块
- 出现重复代码时抽象公共组件
- 团队协作时:
- 强制类型提示(mypy)
- 统一路由命名规范(如全小写+下划线)
经典反模式
- 面条式代码:所有逻辑堆砌在py
- 循环依赖:models导入 services 同时 services 又导入 models
- 配置硬编码:数据库密码直接写在代码中
- 忽略测试目录:tests/未与业务代码同步更新
总结
- 小型项目:保持简单,集中管理
- 中型项目:严格分层,模块化拆分
- 大型系统:服务拆分,共享公共库
- 通用法则:高内聚低耦合,目录即文档
根据实际需求动态调整结构,始终以 可维护性 和 团队效率 为核心目标。