fastapi-templates

FastAPI 项目模板

可用于生产环境的 FastAPI 项目结构，包含异步模式、依赖注入、中间件以及构建高性能 API 的最佳实践。

何时使用本技能

• 从零开始创建新的 FastAPI 项目
• 使用 Python 实现异步 REST API
• 构建高性能 Web 服务和微服务
• 创建使用 PostgreSQL、MongoDB 的异步应用
• 搭建具有合理结构和测试的 API 项目

核心概念

1. 项目结构

推荐布局：

app/
├── api/                    # API routes
│   ├── v1/
│   │   ├── endpoints/
│   │   │   ├── users.py
│   │   │   ├── auth.py
│   │   │   └── items.py
│   │   └── router.py
│   └── dependencies.py     # Shared dependencies
├── core/                   # Core configuration
│   ├── config.py
│   ├── security.py
│   └── database.py
├── models/                 # Database models
│   ├── user.py
│   └── item.py
├── schemas/                # Pydantic schemas
│   ├── user.py
│   └── item.py
├── services/               # Business logic
│   ├── user_service.py
│   └── auth_service.py
├── repositories/           # Data access
│   ├── user_repository.py
│   └── item_repository.py
└── main.py                 # Application entry

2. 依赖注入

FastAPI 使用 Depends 的内置 DI 系统：

• 数据库会话管理
• 身份认证/授权
• 共享业务逻辑
• 配置注入

3. 异步模式

正确使用 async/await：

• 异步路由处理函数
• 异步数据库操作
• 异步后台任务
• 异步中间件

详细示例与模式

详细章节（以 ## Implementation Patterns 开头）位于 references/details.md。当上述导航摘要不够用时，请阅读该文件。

测试

# tests/conftest.py
import pytest
import asyncio
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

from app.main import app
from app.core.database import get_db, Base

TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"

@pytest.fixture(scope="session")
def event_loop():
    loop = asyncio.get_event_loop_policy().new_event_loop()
    yield loop
    loop.close()

@pytest.fixture
async def db_session():
    engine = create_async_engine(TEST_DATABASE_URL, echo=True)
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)

    AsyncSessionLocal = sessionmaker(
        engine, class_=AsyncSession, expire_on_commit=False
    )

    async with AsyncSessionLocal() as session:
        yield session

@pytest.fixture
async def client(db_session):
    async def override_get_db():
        yield db_session

    app.dependency_overrides[get_db] = override_get_db

    async with AsyncClient(app=app, base_url="http://test") as client:
        yield client

# tests/test_users.py
import pytest

@pytest.mark.asyncio
async def test_create_user(client):
    response = await client.post(
        "/api/v1/users/",
        json={
            "email": "[email protected]",
            "password": "testpass123",
            "name": "Test User"
        }
    )
    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "[email protected]"
    assert "id" in data