Pular para o conteúdo principal

ADR-001: FastAPI como Framework Web Python

Status: Aceito | Data: 2026-06-01

Contexto​

Precisamos de um framework Python para as APIs REST do CARla. Requisitos:

  • Suporte nativo a async/await (I/O intensivo: banco, LLM, integrações)
  • Validação de dados com tipagem forte (alinhado com DDD — Pydantic v2)
  • Documentação OpenAPI automática
  • Performance adequada para 500+ usuários simultâneos

Decisão​

FastAPI 0.115+ com Pydantic v2, Uvicorn e Gunicorn em produção.

Consequências​

✅ ~3–5x mais rápido que Django DRF em workloads I/O-bound
✅ OpenAPI/Swagger gerado automaticamente
✅ Integração nativa com Pydantic v2 — VOs do domínio são schemas direto
✅ SSE nativo (StreamingResponse) para o assistente IA
❌ Sem admin embutido (não necessário para APIs)
❌ Curva de aprendizado em async para times acostumados com Django

Alternativas Rejeitadas​

AlternativaMotivo da rejeição
Django REST FrameworkSíncrono por padrão; overhead desnecessário para APIs puras
Flask + marshmallowMuito manual; sem OpenAPI automático
LitestarMenos maduro; menor comunidade para projeto governamental