### FastAPI 框架项目目录结构最佳实践 为了确保项目的可扩展性、易维护性和高效协作，遵循良好的项目结构至关重要。对于 FastAPI 应用程序而言，合理的目录布局不仅有助于团队成员快速理解代码架构，还能简化后续的功能迭代和技术债务管理。 #### 基本项目结构概述 一个典型的 FastAPI 项目应具备清晰的层次划分，通常包括以下几个主要部分： - **app/**: 存放应用程序的核心组件。 - **config/**: 配置文件及相关设置。 - **models/** 或者 **domain/**: 定义数据模型或领域对象[^5]。 - **routers/**: 路由定义及其对应的处理逻辑。 - **services/**: 实现业务服务层接口。 - **utils/**: 放置通用工具函数和辅助方法。 - **tests/**: 单元测试与集成测试案例集。 - **alembic/** (如果使用 SQLAlchemy): 数据库迁移脚本。 - **static/** 和 **templates/**: 如果涉及前端资源，则放置静态文件和模板页面。 具体到各个子目录下的内容安排上，建议按照功能模块进行分类整理，使得每一级目录都能专注于特定的任务范围之内。例如，在 `routers` 文件夹内可以根据不同的 API 功能区分为多个独立的小型路由器；而在 `services` 中则依据具体的业务流程创建相应的服务类。 #### 示例项目结构 以下是基于上述指导原则的一个理想化 FastAPI 项目结构实例： ``` my_fastapi_app/ ├── app/ │ ├── __init__.py │ ├── main.py # 主入口文件 │ └── dependencies.py # 全局依赖注入配置 ├── config/ │ └── settings.py # 环境变量及其他全局配置项 ├── models/ │ └── user.py # 用户实体定义 ├── routers/ │ ├── auth_router.py # 认证相关路由 │ └── item_router.py # 商品操作路由 ├── services/ │ ├── authentication_service.py # 登录注册等功能的服务实现 │ └── item_service.py # 对商品的操作封装成服务 ├── utils/ │ └── helper_functions.py # 辅助性的公共函数集合 ├── tests/ │ ├── test_auth.py # 测试认证功能 │ └── conftest.py # Pytest 的 fixture 设置 └── alembic/ # 若采用SQLAlchemy作为ORM框架时使用的数据库版本控制系统 ``` 这种结构能够有效地分离关注点，使每个部分都只负责自己的工作而不干涉其他部件的工作，从而提高了整个系统的稳定性和灵活性[^3]。 ```python from fastapi import FastAPI, Depends from .dependencies import get_query_token, get_db_session from .routers import items, users def create_application() -> FastAPI: application = FastAPI(dependencies=[Depends(get_query_token)]) application.include_router(items.router) application.include_router(users.router) return application ```