Modelos de Projeto FastAPI

Estruturas de projeto FastAPI prontas para produção com padrões assíncronos, injeção de dependência, middleware e melhores práticas para construir APIs de alta performance.

Quando Usar Esta Habilidade

• Iniciando novos projetos FastAPI do zero
• Implementando APIs REST assíncronas com Python
• Construindo serviços web e microsserviços de alta performance
• Criando aplicações assíncronas com PostgreSQL, MongoDB
• Configurando projetos de API com estrutura e testes adequados

Conceitos Principais

1. Estrutura do Projeto

Layout Recomendado:

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. Injeção de Dependência

O sistema de DI integrado do FastAPI usando Depends:

• Gerenciamento de sessão de banco de dados
• Autenticação/autorização
• Lógica de negócios compartilhada
• Injeção de configuração

3. Padrões Assíncronos

Uso adequado de async/await:

• Manipuladores de rota assíncronos
• Operações de banco de dados assíncronas
• Tarefas em segundo plano assíncronas
• Middleware assíncrono

4. Dependências

Os pacotes que os exemplos importam:

# requirements.txt
fastapi
uvicorn[standard]
pydantic-settings
sqlalchemy[asyncio]>=2.0  # DeclarativeBase; [asyncio] installs greenlet for the async engine
asyncpg                   # PostgreSQL driver: postgresql+asyncpg://...
PyJWT
pwdlib[argon2]
python-multipart          # only for a login route that uses OAuth2PasswordRequestForm

# requirements-dev.txt
pytest
pytest-asyncio
httpx
aiosqlite                 # test database: sqlite+aiosqlite:///:memory:

Exemplos Detalhados e Padrões

Seções detalhadas (começando com ## Implementation Patterns) estão em references/details.md. Leia esse arquivo quando o resumo de navegação acima for insuficiente.

Testes

# tests/conftest.py
import pytest_asyncio
from httpx import ASGITransport, 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:"

# Async fixtures need pytest_asyncio.fixture in pytest-asyncio's default strict mode
@pytest_asyncio.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
    await engine.dispose()

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

    app.dependency_overrides[get_db] = override_get_db

    # httpx 0.28 removed AsyncClient(app=...); use an ASGI transport
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as client:
        yield client
    app.dependency_overrides.clear()

# tests/test_users.py
import pytest

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