Backend e API

Backend Python & FastAPI — APIs modernas e escaláveis

O FastAPI é a framework Python de referência para APIs REST assíncronas. Junta as anotações de tipos nativas do Python à validação automática do Pydantic, à documentação OpenAPI gerada automaticamente e a um desempenho ASGI comparável ao de Node.js — sem sacrificar a legibilidade do código.

FastAPI — a framework Python mais rápida

O FastAPI corre sobre Uvicorn (servidor ASGI) com Gunicorn para o modo multiprocesso em produção. Um endpoint simples que lê da cache Redis não precisa de consultar a base de dados. A injeção de dependências nativa permite testar qualquer camada de forma isolada, sem mocks complicados: a autenticação, a sessão de base de dados ou a limitação de pedidos são, cada uma delas, uma dependência injetável.

A documentação OpenAPI 3.1 é gerada automaticamente a partir das anotações de tipos — em desenvolvimento, o Swagger UI e o ReDoc ficam disponíveis em `/docs` e `/redoc`. O esquema Pydantic v2 (validador escrito em Rust) valida pedidos e respostas 10 a 20 vezes mais depressa do que o Pydantic v1. Qualquer campo inválido devolve um 422 com mensagens de erro claras e localizadas.

  • async/await nativo — entrada/saída não bloqueante em todas as operações de base de dados e HTTP
  • BackgroundTasks para operações posteriores à resposta (email, webhook, registo)
  • Suporte nativo de WebSocket para funcionalidades em tempo real (chat, notificações)
  • Limitação de pedidos com slowapi (baseada em limits) — por IP e por utilizador
  • Middleware de CORS, compressão (gzip/brotli), identificador de pedido e medição de tempos

PostgreSQL, SQLAlchemy e Alembic

Usamos SQLAlchemy 2.0 async (controlador asyncpg) em todas as operações de base de dados. Os modelos são definidos com Mapped types — com tipos seguros e sem cadeias de texto. As consultas complexas escrevem-se em SQLAlchemy Core (verificado em tempo de compilação) ou em SQL puro através de `text()` com parâmetros ligados — nunca por interpolação de strings, o que elimina por completo o risco de injeção de SQL.

As migrações Alembic são geradas automaticamente a partir das alterações aos modelos e revistas à mão antes de serem aplicadas. Cada migração tem o seu `upgrade()` e o seu `downgrade()` testados. Em produção, as migrações correm em CI antes do deploy — a base de dados está sempre sincronizada com o código. O pool de ligações é gerido pelo asyncpg, com um tamanho configurável por serviço.

  • Bloqueio ao nível da linha com `SELECT ... FOR UPDATE` para operações concorrentes críticas
  • Pesquisa de texto integral com pg_trgm e tsvector — sem Elasticsearch nos casos simples
  • JSONB para dados semiestruturados, com indexação GIN
  • Tabelas particionadas para tabelas com milhões de linhas (registos, eventos)

Cache Redis e escalabilidade horizontal

O Redis 7 é usado como cache aplicacional (TTL por endpoint), armazenamento de sessões (tokens de refresh JWT com revogação seletiva), pub/sub para eventos em tempo real e fila para tarefas em segundo plano (Celery ou ARQ). A estratégia de cache é cache-aside com invalidação explícita — não um TTL às cegas que possa servir dados desatualizados.

  • Autenticação JWT com token de acesso (15 min) e token de refresh no Redis (7 dias)
  • Celery com Redis como broker para tarefas assíncronas (geração de PDF, email, importações)
  • Endpoint de health check `/health` com o estado da base de dados, do Redis e a versão em produção
  • Registo estruturado em JSON (structlog) — compatível com Loki/Datadog/ELK

Vantagens e limitações

Vantagens

  • Desempenho ASGI comparável ao de Node.js e Go em entrada/saída.
  • Documentação OpenAPI gerada automaticamente a partir das anotações de tipos.
  • Validação Pydantic v2 rápida, com erros 422 claros.
  • Código legível: o Python é familiar para a maioria das equipas.

Limitações

  • O Python continua a ser mais lento do que Go ou Rust em tarefas intensivas de CPU.
  • async/await exige disciplina — uma chamada bloqueante trava todo o event loop.
  • Ecossistema mais jovem do que o do Django em funcionalidades incluídas de origem.
  • Não inclui ORM nem painel de administração integrados — escolhe-os à parte.

Veredicto breve

Escolhe o FastAPI para APIs REST assíncronas, microserviços e backends para SPA ou mobile. Para aplicações com cargas de CPU extremas ou monólitos com painel de administração já feito, Go e Django, respetivamente, podem encaixar melhor.

Tabela de especificações

CapacidadeLimite / limiarUtilização típica
Concorrênciaasync/await, entrada/saída não bloqueanteO trabalho intensivo de CPU exige workers à parteAPIs com muitas chamadas a base de dados ou HTTP
LatênciaCache Redis por endpoint, sem consulta à base de dadosAumenta com a serialização de payloads grandesBackend de SaaS, mobile e tempo real
Validação e documentaçãoPydantic v2 + OpenAPI 3.1 automáticoEsquemas complexos aumentam o tempo de arranqueAPIs públicas com Swagger/ReDoc
Custo típicoOpen-source, corre com 1 vCPUO escalamento horizontal exige mais processosDo MVP à produção

FastAPI face às alternativas

CritérioFastAPIDjango / Express
Desempenho assíncronoExcelente (ASGI nativo)Django parcial, Express bom
Documentação OpenAPI automáticaSim, a partir das anotações de tiposExige pacotes adicionais
Admin / ORM integradosNão (escolhes à parte)Django: sim; Express: não

Perguntas frequentes

O FastAPI é mais rápido do que o Django?

Em entrada/saída, sim. O FastAPI corre de forma assíncrona sobre ASGI, por isso atende muitos mais pedidos concorrentes com chamadas a base de dados ou HTTP do que o Django síncrono clássico. Em contrapartida, o Django traz mais funcionalidades de origem.

Para que é que o FastAPI não é adequado?

Para tarefas intensivas de CPU (processamento de imagem, cálculo numérico pesado) o Python é mais lento do que Go ou Rust; esse trabalho passa para workers à parte. Além disso, não vem com um painel de administração pronto a usar como o do Django.

O FastAPI precisa de um ORM?

Não obrigatoriamente. Usamos SQLAlchemy 2.0 async com Alembic para as migrações, mas também podes escrever SQL puro. O ORM não vem incluído, por isso escolhe-lo consoante o projeto.

Como escalo um backend FastAPI?

Na horizontal: corres vários processos Uvicorn sob Gunicorn, atrás de um balanceador de carga, com cache Redis e as tarefas pesadas passadas para o Celery. O design sem estado permite acrescentar instâncias sempre que for preciso.