FastAPI项目结构设计：从混乱到优雅的工程化实践
当你第一次接触FastAPI时，可能会被它的简洁和高效所吸引。但很快，一个现实问题摆在面前：如何组织代码？是把所有逻辑塞进一个main.py文件，还是模仿Flask的蓝图结构？作为经历过这个阶段的开发者，我想分享一套经过实战检验的项目结构设计，它能让你从第一天就写出易于维护的代码。
1. 为什么项目结构如此重要
在小型项目中，你可能觉得文件放在哪里并不重要。但随着功能增加，混乱的目录结构会变成维护的噩梦。我曾接手过一个项目，所有路由、模型和工具函数都堆在同一个文件里，添加新功能就像在雷区行走——你永远不知道修改某行代码会引发什么连锁反应。
好的项目结构应该实现以下几个目标：
- 可维护性：六个月后，你或团队成员能快速找到相关代码
- 可扩展性：新增功能时不需要重构现有结构
- 可测试性：能够轻松为各组件编写单元测试
- 团队协作：多人开发时减少代码冲突
# 反面教材：把所有东西塞进一个文件 # main.py from fastapi import FastAPI from sqlalchemy import create_engine from pydantic import BaseModel import jwt import bcrypt app = FastAPI() engine = create_engine("sqlite:///./test.db") class User(BaseModel): username: str email: str @app.post("/users") def create_user(user: User): # 验证逻辑、数据库操作、业务逻辑全混在一起 pass2. 分层架构设计详解
经过多个项目的迭代，我总结出一套核心分层架构，适用于从小型API到中大型服务。让我们从顶层开始，逐层解析每个目录的职责。
2.1 项目根目录：入口与配置
项目根目录应该保持简洁，只包含最必要的文件和目录。典型的结构如下：
your_project/ ├── .env ├── .gitignore ├── README.md ├── pyproject.toml # 推荐使用Poetry管理依赖 ├── main.py # 唯一入口 ├── core/ # 核心配置 ├── api/ # 接口层 ├── app/ # 业务逻辑层 ├── utils/ # 工具函数 ├── db/ # 数据库层 └── tests/ # 测试代码提示：使用
pyproject.toml替代传统的requirements.txt，它能更好地管理依赖关系和虚拟环境。
main.py应该保持精简，只做三件事：
- 创建FastAPI实例
- 注册中间件和路由
- 启动服务
# main.py 示例 from fastapi import FastAPI from core.config import settings from core.middlewares import register_middlewares from api.v1.router import api_router app = FastAPI(title=settings.PROJECT_NAME) register_middlewares(app) app.include_router(api_router, prefix=settings.API_PREFIX) if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=settings.PORT)2.2 核心配置层（core/）
core/目录存放全局通用的配置和组件，这些内容不依赖其他业务模块：
core/ ├── __init__.py ├── config.py # 配置中心 ├── exceptions.py # 自定义异常 ├── middlewares.py # 全局中间件 ├── dependencies.py # 全局依赖项 └── logger.py # 日志配置config.py使用Pydantic的BaseSettings管理配置，支持从环境变量读取：
# core/config.py from pydantic_settings import BaseSettings class Settings(BaseSettings): PROJECT_NAME: str = "My API" DEBUG: bool = False DATABASE_URL: str = "postgresql://user:pass@localhost/db" class Config: env_file = ".env" settings = Settings()2.3 接口层（api/）的设计哲学
接口层只负责HTTP相关的处理，不应该包含任何业务逻辑。我推荐按版本和业务模块组织：
api/ ├── __init__.py └── v1/ ├── __init__.py ├── endpoints/ │ ├── auth.py │ ├── users.py │ └── items.py ├── dependencies/ # 接口层专属依赖 └── router.py # 聚合所有路由每个endpoint文件应该保持简洁：
# api/v1/endpoints/users.py from fastapi import APIRouter, Depends from app.schemas.user import UserCreate, UserOut from app.services.user import create_user from api.v1.dependencies.auth import get_current_user router = APIRouter(prefix="/users", tags=["Users"]) @router.post("/", response_model=UserOut) async def register_user( user_in: UserCreate ): """注册新用户""" return await create_user(user_in) @router.get("/me", response_model=UserOut) async def get_me( current_user: UserOut = Depends(get_current_user) ): """获取当前用户信息""" return current_user2.4 业务逻辑层（app/）的精细拆分
这是最复杂的部分，也是项目的核心。我采用DDD（领域驱动设计）的思想，将业务逻辑分为四个子层：
app/ ├── __init__.py ├── models/ # SQLAlchemy模型 ├── schemas/ # Pydantic模型 ├── repositories/ # 数据访问层 ├── services/ # 业务服务 └── tasks/ # 异步任务关键区别点：
| 目录 | 职责 | 使用技术 |
|---|---|---|
| models/ | 定义数据库表结构 | SQLAlchemy |
| schemas/ | 定义API输入输出格式 | Pydantic |
| repositories/ | 数据库基本操作 | SQLAlchemy |
| services/ | 组合多个repository操作 | 纯Python |
# app/services/user.py from app.repositories.user import UserRepository from app.schemas.user import UserCreate, UserOut from utils.password import hash_password class UserService: def __init__(self, user_repo: UserRepository): self.user_repo = user_repo async def create_user(self, user_in: UserCreate) -> UserOut: """创建用户业务逻辑""" hashed_password = hash_password(user_in.password) user_dict = user_in.dict(exclude={"password"}) user_dict["hashed_password"] = hashed_password user = await self.user_repo.create(user_dict) return UserOut.from_orm(user)3. 进阶架构模式
当项目规模增长到一定阶段，基础分层可能不再够用。以下是两种常见的扩展模式。
3.1 模块化架构
对于涉及多个独立领域的大型项目，可以按业务模块组织：
project/ ├── core/ ├── modules/ │ ├── auth/ │ │ ├── api.py │ │ ├── models.py │ │ ├── schemas.py │ │ └── service.py │ └── billing/ │ ├── api.py │ ├── models.py │ └── service.py └── shared/ ├── db/ └── utils/每个模块自成一体，通过shared/目录共享数据库连接等基础设施。
3.2 清洁架构
受Robert Martin的"清洁架构"启发，可以进一步解耦依赖：
project/ ├── core/ ├── interfaces/ │ ├── repositories/ │ └── services/ ├── infrastructure/ │ ├── db/ │ └── cache/ ├── domain/ │ ├── entities/ │ └── value_objects/ └── presentation/ ├── api/ └── cli/这种架构更适合复杂领域逻辑的项目，但会引入一定的复杂性。
4. 实战技巧与常见陷阱
在实施上述架构时，有几个关键点需要注意：
4.1 依赖注入的正确使用
FastAPI的Depends是管理依赖的利器，但容易被滥用：
# 好的做法：明确依赖层级 def get_db(): db = SessionLocal() try: yield db finally: db.close() def get_user_repo(db: Session = Depends(get_db)): return UserRepository(db) def get_user_service(repo: UserRepository = Depends(get_user_repo)): return UserService(repo) @router.post("/users") async def create_user( user_in: UserCreate, service: UserService = Depends(get_user_service) ): return await service.create_user(user_in)4.2 测试策略
良好的结构应该便于测试：
# tests/test_services/test_user.py @pytest.mark.asyncio async def test_create_user(user_repo: UserRepository): service = UserService(user_repo) user_in = UserCreate(email="test@test.com", password="secret") user = await service.create_user(user_in) assert user.email == user_in.email assert user.id is not None4.3 性能考量
虽然分层带来了清晰性，但可能增加函数调用开销。对于性能关键路径，可以考虑：
- 将简单操作直接放在路由层
- 使用
lru_cache缓存纯函数结果 - 避免在多层间传递大型对象
5. 从理论到实践：一个电商项目的演进
让我们通过一个电商API的演进，看看这套架构如何应对需求变化。
5.1 初始阶段：用户和商品
ecommerce/ ├── api/ │ └── v1/ │ ├── users.py │ └── products.py ├── app/ │ ├── models/ │ │ ├── user.py │ │ └── product.py │ ├── schemas/ │ └── services/ └── db/5.2 增加订单功能
ecommerce/ ├── api/ │ └── v1/ │ ├── users.py │ ├── products.py │ └── orders.py # 新增 ├── app/ │ ├── models/ │ │ └── order.py # 新增 │ ├── schemas/ │ │ └── order.py # 新增 │ └── services/ │ └── order.py # 新增 └── db/5.3 引入支付系统
ecommerce/ ├── modules/ │ ├── payment/ # 新模块 │ │ ├── api.py │ │ ├── models.py │ │ └── service.py └── shared/ ├── db/ └── utils/这种渐进式的演进方式，确保项目结构始终与业务复杂度匹配。
