FastAPI 目录拆分最佳实践

FastAPI 目录拆分最佳实践

your_project/                  # 项目根目录
├── .env                       # 环境变量（开发环境用，不提交Git）
├── .env.prod                  # 生产环境变量模板（提交Git，填占位符）
├── .gitignore                 # Git忽略文件（venv、.env、__pycache__等）
├── README.md                  # 项目说明（安装、启动、接口文档等）
├── requirements.txt           # 依赖包列表（或用pyproject.toml+poetry）
├── pyproject.toml             # 项目元信息（推荐用Poetry/Pipenv管理依赖）
├── main.py                    # 项目入口（启动服务、注册核心组件）
├── core/                      # 核心配置（全局通用、不依赖其他模块）
│   ├── __init__.py
│   ├── config.py              # 配置中心（读取环境变量、统一配置）
│   ├── exceptions.py          # 全局异常定义（自定义错误类）
│   ├── middlewares.py         # 全局中间件（日志、跨域、认证等）
│   ├── dependencies.py        # 全局依赖（如登录验证、数据库连接）
│   └── logger.py              # 日志配置（自定义日志格式、输出）
├── api/                       # 接口层（仅负责路由注册和请求/响应处理）
│   ├── __init__.py
│   ├── api_v1/                # API v1版本（支持多版本共存）
│   │   ├── __init__.py
│   │   ├── endpoints/         # 按业务模块拆分路由
│   │   │   ├── __init__.py
│   │   │   ├── user.py        # 用户相关接口（/api/v1/users/*）
│   │   │   └── item.py        # 商品相关接口（/api/v1/items/*）
│   │   └── router.py          # v1版本路由汇总（注册所有endpoints）
│   └── deps/                  # 接口层专属依赖（如某模块的权限校验）
│       ├── __init__.py
│       └── user_deps.py       # 用户接口的依赖（如“必须是管理员”）
├── app/                       # 业务逻辑层（核心业务，与接口解耦）
│   ├── __init__.py
│   ├── crud/                  # 数据操作（Create/Read/Update/Delete）
│   │   ├── __init__.py
│   │   ├── base.py            # 基础CRUD（通用增删改查，复用）
│   │   ├── crud_user.py       # 用户数据操作
│   │   └── crud_item.py       # 商品数据操作
│   ├── models/                # 数据模型（数据库模型、ORM映射）
│   │   ├── __init__.py
│   │   ├── base.py            # 基础模型（如带id、create_time的基类）
│   │   ├── user.py            # 用户数据库模型
│   │   └── item.py            # 商品数据库模型
│   ├── schemas/               # 数据校验/序列化（Pydantic模型）
│   │   ├── __init__.py
│   │   ├── base.py            # 基础Schema（如分页参数、响应基类）
│   │   ├── user.py            # 用户的请求/响应Schema（如登录请求、用户信息响应）
│   │   └── item.py            # 商品的请求/响应Schema
│   └── services/              # 业务服务（复杂逻辑封装，跨CRUD调用）
│       ├── __init__.py
│       ├── user_service.py    # 用户业务（如“注册+发送欢迎邮件”）
│       └── item_service.py    # 商品业务（如“创建商品+扣库存”）
├── utils/                     # 工具函数（通用工具，无业务逻辑）
│   ├── __init__.py
│   ├── auth.py                # 认证工具（JWT生成/验证、密码加密）
│   ├── email.py               # 邮件工具（发送邮件）
│   └── common.py              # 通用工具（如时间格式化、数据转换）
├── db/                        # 数据库连接层（与数据库交互的基础）
│   ├── __init__.py
│   ├── session.py             # 数据库会话（创建SQLAlchemy Session）
│   └── base.py                # 数据库基础（如引擎配置、Base类）
└── tests/                     # 测试用例（按模块拆分，保证代码质量）
    ├── __init__.py
    ├── conftest.py            # 测试配置（如测试数据库连接、夹具）
    ├── test_api/              # 接口测试
    │   ├── test_user_api.py
    │   └── test_item_api.py
    └── test_app/              # 业务逻辑测试
        ├── test_crud_user.py
        └── test_user_service.py