fastapi-project-structure

用途

FastAPI Project Structure 是一套面向 FastAPI 应用的标准目录布局与模块组织规范，用于帮助开发者以一致、可维护的方式组织项目代码。它定义了从应用入口、路由、数据模型到业务逻辑、依赖注入和数据库迁移的完整目录结构。

标准目录布局

资料给出的标准结构如下：

project/
  app/
    __init__.py
    main.py              # FastAPI app instance and lifespan
    config.py            # Settings via pydantic-settings
    api/
      __init__.py
      v1/
        __init__.py
        router.py        # Aggregates all v1 routers
        endpoints/
          __init__.py
          users.py
          items.py
    models/
      __init__.py
      user.py            # SQLAlchemy / ORM models
      item.py
    schemas/
      __init__.py
      user.py            # Pydantic request/response schemas
      item.py
    deps/
      __init__.py
      database.py        # DB session dependency
      auth.py            # Auth dependencies
    services/
      __init__.py
      user_service.py    # Business logic
      item_service.py
    db/
      __init__.py
      session.py         # Engine and session factory
      base.py            # Declarative base
  tests/
    __init__.py
    conftest.py
    test_users.py
    test_items.py
  alembic/               # Database migrations
    versions/
    env.py
  alembic.ini
  pyproject.toml

主要能力与关键约定

应用入口 app/main.py

作为应用入口点，负责创建 FastAPI 实例并管理生命周期。示例代码使用 contextlib.asynccontextmanager 定义 lifespan，在启动时创建表、初始化连接，在关闭时释放连接（await engine.dispose()）。随后创建 FastAPI(title="My API", version="1.0.0", lifespan=lifespan) 并通过 app.include_router(api_router, prefix="/api/v1") 挂载路由。

路由聚合 app/api/v1/router.py

用于聚合各资源路由。示例中从 app.api.v1.endpoints 导入 users、items，创建 api_router = APIRouter()，并分别以 /users、/items 前缀和对应 tags 注册。

models 与 schemas 的区分

models/：ORM 模型（SQLAlchemy），代表数据库表。
schemas/：Pydantic 模型，代表 API 请求/响应结构。

规范要求两者保持分离，且绝不在端点中直接返回 ORM 模型。

依赖注入 app/deps/

用于放置可复用依赖。示例给出 app/deps/database.py 中的 get_db 异步生成器依赖，通过 async_session_maker() 提供 AsyncSession。

业务逻辑 app/services/

要求端点保持轻量，将逻辑移入 service 函数。示例 app/services/user_service.py 中的 get_user_by_id 接收 AsyncSession 与 user_id，返回 User | None。

配置 app/config.py

使用 pydantic_settings.BaseSettings 定义 Settings，包含 database_url、secret_key、debug（默认 False），并通过 model_config = {"env_file": ".env"} 从 .env 读取配置，最后实例化 settings = Settings()。

规则

每个资源一个路由文件（如 users.py、items.py）。
绝不在端点函数中放置业务逻辑，应使用 services。
API 始终版本化（/api/v1/、/api/v2/）。
所有共享状态（数据库会话、认证、配置）使用 Depends()。
Pydantic schema 与 ORM 模型分目录存放。

适用场景

适用于使用 FastAPI 构建后端 API 的项目，尤其是需要清晰分层、便于团队协作与长期维护的中大型应用。目录中包含 tests 与 alembic 迁移目录，也适合需要测试与数据库迁移管理的项目。

限制

资料未提供该规范的安装命令、依赖版本要求、收费或授权信息，也未说明其适用的 FastAPI 或 Python 版本范围，这些内容暂未提供。