【fastapi】项目目录架构设计

原创已于 2025-07-22 09:12:28 修改 · 638 阅读

4 ·

CC 4.0 BY-SA版权

文章标签：

#fastapi

于 2025-02-12 10:12:50 首次发布

一. 前言

FastAPI可能更倾向于使用模块化的方式，比如按功能划分目录。

二. 【fastapi】架构示例

1.适用于中大型项目的

myfastapi/
├── .env                    # 环境变量文件
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── requirements.txt        # 或使用 poetry/pipenv
├── README.md
│
├── src/                    # 项目主目录
│   ├── main.py             # 应用入口文件
│   │
│   ├── core/               # 核心配置
│   │   ├── config.py       # 配置加载
│   │   └── security.py     # 安全相关（如 JWT）
│   │
│   ├── api/                # API 路由
│   │   ├── v1/             # API 版本控制
│   │   │   ├── endpoints/
│   │   │   │   ├── auth.py
│   │   │   │   ├── users.py
│   │   │   │   └── items.py
│   │   │   └── routers.py  # 路由聚合
│   │   └── deps.py         # 路由依赖项
│   │
│   ├── models/             # 数据库模型
│   │   └── models.py
│   │
│   ├── schemas/            # Pydantic 模型
│   │   ├── auth.py
│   │   ├── user.py
│   │   └── item.py
│   │
│   ├── services/           # 业务逻辑
│   │   ├── auth_service.py
│   │   ├── user_service.py
│   │   └── item_service.py
│   │
│   ├── db/                 # 数据库相关
│   │   ├── session.py      # 数据库会话管理
│   │   ├── repositories/   # 数据库操作层（可选）
│   │   └── migrations/     # Alembic 迁移脚本
│   │
│   ├── utils/              # 工具类
│   │   ├── email.py
│   │   └── logger.py
│   │
│   ├── tests/              # 测试用例
│   │   ├── conftest.py
│   │   ├── test_auth.py
│   │   ├── test_users.py
│   │   └── test_items.py
│   │
│   ├── static/             # 静态文件
│   └── templates/          # Jinja2 模板（如果需要）
│
└── alembic.ini             # Alembic 配置

核心文件说明：

main.py - 应用入口

from fastapi import FastAPI
from src.core.config import settings
from src.api.v1.routers import api_router

app = FastAPI(title=settings.PROJECT_NAME)
app.include_router(api_router, prefix="/api/v1")

config.py - 配置管理

from pydantic import BaseSettings

class Settings(BaseSettings):
    PROJECT_NAME: str = "My FastAPI"
    DATABASE_URL: str
    
    class Config:
        env_file = ".env"

路由示例 (users.py)

from fastapi import APIRouter, Depends
from src.services.user_service import UserService

router = APIRouter()

@router.get("/users/{user_id}")
async def get_user(
    user_id: int,
    service: UserService = Depends()
):
    return service.get_user(user_id)

服务层示例 (user_service.py)

class UserService:
    def __init__(self, db_session: AsyncSession = Depends(get_db)):
        self.db = db_session

    async def get_user(self, user_id: int):
        # 业务逻辑实现
        return ...

2. 小型项目简化版

myapp/
├── main.py
├── config.py
├── routers/
│   ├── items.py
│   └── users.py
├── models/
├── schemas/
└── db.py

3. 企业级项目扩展：

添加 celery_tasks/ 目录处理异步任务
增加 client/ 目录存放第三方服务客户端
创建 middlewares/ 目录自定义中间件
添加 healthcheck/ 健康检查端点
使用 domain/ 目录实现领域驱动设计

关键注意事项：

数据库迁移：

使用 Alembic 进行数据库版本控制
迁移脚本应放在 db/migrations/versions

测试建议：

使用 pytest 编写测试用例
添加集成测试和单元测试
使用 TestClient 进行 API 测试

部署友好：

添加 Prometheus 监控端点
实现完善的日志记录
添加 API 限流机制

安全实践：

使用 CORSMiddleware 处理跨域
实施 JWT 或 OAuth2 认证
输入验证使用 Pydantic 模型

异步支持：

数据库驱动选择 async 版本（如 asyncpg）
使用 httpx 进行异步 HTTP 请求
注意 async/await 的合理使用

项目架构遵循了关注点分离原则，符合现代 API 开发的最佳实践，能够很好地支持项目从开发到部署的全生命周期管理。实际项目中可以根据具体需求适当增减模块。

以上就是关于【fastapi】项目目录架构设计的基本介绍，后面会有详细的文章在进行讲解分析，希望对你有所帮助！