Não é querer insinuar nada. Mas quando documentei uma API que fiz para Angola (Node.js, Fastify, PostgreSQL, 18 módulos, 137 endpoints, 27 tabelas, pagamentos e carteira), vi que o que a torna sólida cabe numa lista.
Cada ponto tem Conceito (o termo técnico), Implementação (o que fazer) e Porquê (o risco que fecha).
Fase 1: Fundações
1. Arquitectura modular por domínio (feature-first)
Conceito: em vez de pastas por tipo (controllers/, services/), uma pasta por domínio de negócio (bookings, payments, auth).
Implementação: cada módulo contém *.routes.ts, *.schema.ts, *.controller.ts e *.service.ts. Os plugins transversais (JWT, CORS, helmet, rate limit) ficam em plugins/.
Porquê: alta coesão e baixo acoplamento. Testas, alteras ou removes uma funcionalidade sem espalhar mudanças pelo projecto.
2. Configuração com validação fail-fast
Conceito: a aplicação valida o ambiente (12-factor config) antes de aceitar tráfego.
Implementação:
- Valida todas as variáveis com um schema no arranque.
- Em produção, aborta se faltar
DATABASE_URL,JWT_SECRET,CORS_ORIGINSouTRUSTED_PROXIES. - Rejeita
JWT_SECRETcom o valor de exemplo e origens que não usemhttps://.
Porquê: erro de configuração apanha-se no deploy, não em runtime com utilizadores ligados.
3. TypeScript em modo estrito
Implementação: strict, noUncheckedIndexedAccess, noImplicitOverride, verbatimModuleSyntax, módulos ESM (NodeNext) e lint com Biome.
Porquê: transforma uma classe inteira de erros de runtime (undefined em índices, overrides acidentais) em erros de compilação.
Fase 2: Contrato e camadas
4. Validação schema-first (JSON Schema + AJV)
Conceito: o contrato do endpoint é um JSON Schema. A validação, os tipos estáticos e a documentação OpenAPI nascem do mesmo ficheiro (TypeBox).
Implementação:
- Valida
body,query,paramse a resposta. - AJV com
removeAdditional: false,coerceTypes: false,useDefaults: true,allErrors: true. additionalProperties: falseem praticamente todos os schemas.- Limites explícitos:
minLength,maxLength,minimum,maximum,pattern,format,enum.
Porquê: bloqueia mass assignment (campos extra que alteram colunas que não devias expor), coerção silenciosa de tipos e payloads gigantes. O OpenAPI nunca fica desactualizado.
5. Camadas: Route, Controller, Service
Implementação:
- Route: schema, autenticação (
authenticate) e RBAC (requireRoles). - Controller: fino. Extrai
userIdebodye delega. - Service: regras de negócio, máquina de estados, transacções e acesso à base de dados (Drizzle).
Porquê: as invariantes de negócio vivem num único sítio, reutilizável por rotas, jobs e testes.
6. Error handling centralizado
Implementação:
- Classe
AppError(message, statusCode)para erros de negócio esperados. setErrorHandlerglobal: usa ostatusCodedoAppError, devolve 503 quando o PostgreSQL está indisponível, traduz erros AJV para mensagens legíveis e devolve mensagem genérica em 500 (sem stack trace).request.id(UUID viagenReqId) devolvido no cabeçalhox-request-id.- Erros ≥ 500 registados com
request.log.error.
Porquê: evita information disclosure (stack traces, nomes de tabelas) e permite correlacionar a queixa do cliente com a linha de log.
Fase 3: Identidade e acesso
7. Autenticação com JWT (access token)
Conceito: o JWT (JSON Web Token) é um token assinado que transporta claims. O servidor valida a assinatura, sem consultar a base de dados em cada pedido.
Implementação:
- Algoritmo HS256, TTL de 15 minutos.
- Claims:
sub(id do utilizador),role,iss(emissor) eaud(audiência). Oauthenticatevalida todas. - O
authenticaterejeita roles fora do esperado e tokens comkind: 'admin'nas rotas de utilizador.
Porquê: um token roubado tem janela de uso curta. Validar iss/aud impede reutilizar tokens emitidos para outro serviço.
8. Refresh token com rotação e detecção de reutilização
Conceito: token opaco de longa duração, usado só para obter novos access tokens. Cada uso emite um novo (rotation).
Implementação:
- 32 bytes aleatórios (CSPRNG) em base64url (43 caracteres).
- A base de dados guarda apenas o SHA-256 do token, nunca o valor.
- Rotação em transacção:
SELECT ... FOR UPDATEpelo hash, consumo com update condicional, emissão de novo token na mesmafamilyId. - Token já consumido, revogado ou expirado → revoga toda a família e devolve 401.
Porquê: se um token roubado for usado depois do legítimo (ou o contrário), a reutilização é detectada e todas as sessões da família caem.
9. Passwords: hashing, timing e lockout
Conceito: hashing lento e com memória (memory-hard) para tornar caro o ataque offline.
Implementação:
- Argon2id com custos configuráveis.
- Hashes bcrypt legados continuam a ser verificados, sem re-hash no login (o bcrypt trunca a 72 bytes).
- Email inexistente executa uma verificação contra um hash dummy, para igualar o tempo de resposta (mitiga user enumeration por timing).
- Lockout: 10 falhas em 15 minutos → bloqueio de 15 minutos, chaveado por SHA-256 do email normalizado.
- Alterar password exige a actual, faz update condicional pelo hash antigo (detecta corrida) e revoga todos os refresh tokens.
Porquê: protege contra fuga da base de dados, credential stuffing, força bruta e enumeração de contas.
10. Autorização: RBAC + verificação de propriedade
Conceito: autenticação responde "quem és?". Autorização responde "o que podes fazer, e sobre que recurso?".
Implementação:
- RBAC (Role-Based Access Control):
requireRoles('DRIVER' | 'PASSENGER')por rota. - Verificação de propriedade no service: só o condutor dono da rota confirma o pagamento dessa rota.
- Administração com tokens, permissões e catálogo próprios, separados dos de utilizador.
Porquê: o RBAC sozinho não chega. A falha mais comum é IDOR (Insecure Direct Object Reference): um utilizador autenticado altera o recurso de outro só trocando o id na URL.
Fase 4: Perímetro HTTP
11. CORS (Cross-Origin Resource Sharing)
Conceito: o navegador aplica a Same-Origin Policy. Um site só lê respostas de outra origem (esquema + domínio + porta) se esta a autorizar. Antes de pedidos "não simples" envia um preflight (OPTIONS).
Implementação: @fastify/cors com allowlist explícita:
Access-Control-Allow-Origin: https://teu-site.ao
Nunca * em produção, e em produção todas as origens têm de ser https://.
Porquê: evita que um site malicioso use o navegador da vítima para chamar a tua API com os cookies ou credenciais dela. Atenção: CORS protege o navegador, não a API. Não substitui a autenticação.
12. Cabeçalhos de segurança (Helmet, CSP, HSTS)
Conceito:
- CSP (Content-Security-Policy): lista de onde o navegador pode carregar scripts, estilos e imagens.
- HSTS (HTTP Strict-Transport-Security): obriga o navegador a usar sempre HTTPS.
Implementação: @fastify/helmet activa CSP, HSTS e outros cabeçalhos (X-Content-Type-Options, etc.).
Porquê: mitiga XSS, clickjacking, MIME sniffing e downgrade para HTTP.
13. Rate limiting, limites e proxies
Conceito: throttling por cliente para limitar abuso e consumo de recursos.
Implementação:
@fastify/rate-limitglobal, com limites mais apertados em login e registo.- Limite de tamanho do body, de ficheiros (multipart) e timeouts.
@fastify/under-pressure: devolve 503 quando o event loop, o heap ou o RSS passam de um limiar.TRUSTED_PROXIESobrigatório: define de que proxies se aceita oX-Forwarded-For.
Porquê: sem TRUSTED_PROXIES, atrás de um proxy todos os pedidos parecem vir do mesmo IP (o rate limit bloqueia toda a gente) ou, pior, o cliente forja o IP e foge ao limite.
Fase 5: Dados, dinheiro e concorrência
14. Modelação e migrações
Implementação:
- Migrações SQL versionadas (Drizzle Kit). Nunca DDL manual em produção.
- Índices nas colunas de filtro e restrições
UNIQUEonde o negócio exige. - Dinheiro em inteiros (Kwanzas), nunca
float. - Timestamps com precisão de milissegundos; datas de negócio calculadas em
Africa/Luanda. - Pool de ligações (
pg) com limites configurados.
Porquê: reprodutibilidade de ambientes e fim dos erros de arredondamento e de fuso horário.
15. Transacções, locks e concorrência optimista
Conceito: duas formas de evitar race conditions.
- Pessimista: bloqueia a linha enquanto a alteras (
SELECT ... FOR UPDATE). - Optimista: não bloqueia, mas só aplica o update se o estado ainda for o que leste.
Implementação:
-- optimista: só muda se ainda estiver PENDING
UPDATE "Booking"
SET status = 'CONFIRMED'
WHERE id = $1 AND status = 'PENDING';
Se afectar 0 linhas, devolve 409 Conflict. Em criação de reservas, usa lock da rota, soma dos lugares ocupados e débito atómico da carteira, tudo na mesma transacção.
Porquê: dois utilizadores a reservar o último lugar. Sem isto, os dois ganham (overbooking).
16. Carteira com ledger e máquina de estados
Conceito:
- Ledger: livro de movimentos imutáveis. O saldo é consequência, não a fonte da verdade.
- Máquina de estados: só existem transições permitidas (
PENDING → CONFIRMED → IN_PROGRESS → COMPLETED).
Implementação: tabela de movimentos (PAYMENT, REFUND...) ligada ao pagamento original, reembolso integral com crédito atómico e registo de auditoria. Transição inválida → 409.
Porquê: auditabilidade (reconstróis qualquer saldo) e impossibilidade de estados incoerentes.
17. Idempotência
Conceito: uma operação é idempotente se executá-la N vezes tem o mesmo efeito que executá-la uma vez.
Implementação:
- Webhooks: se o pagamento já está
CONFIRMED/FAILED, devolve sem alterar. Só actualizaPENDING/PAID, com update condicional. - Job de expiração: usa locks e updates condicionais.
- Upsert (
onConflictDoUpdate) em pagamentos e configurações. Seeds idempotentes.
Porquê: provedores de pagamento fazem retry de webhooks (entrega at-least-once). Sem idempotência, o mesmo aviso credita duas vezes.
18. Entradas hostis: webhooks e uploads
Implementação:
- Webhook: autenticação (Basic Auth ou
x-api-key), comparação comtimingSafeEqual(evita timing attacks) e responde sempre{ "status": "1" }depois de processar, registando erros no log. - Uploads:
@fastify/multipartcom limites, validação de tipo e extensão, nomes gerados pelo servidor e ficheiros privados (comprovativos) separados dos públicos.
Porquê: evita path traversal, content-type spoofing e signature forging.
Fase 6: Performance, qualidade e entrega
19. Cache-aside tolerante a falhas
Conceito: cache-aside: lês da cache, se falhar lês da base de dados e preenches a cache. Quem escreve invalida.
Implementação: Redis (ioredis) com ligação lazy, cooldown de reconexão e falha tratada como cache miss. Chaves invalidadas quando os dados mudam.
Porquê: a cache é optimização, nunca dependência. Se o Redis cair, a API fica mais lenta, não indisponível.
20. Jobs em background
Implementação: expiração de reservas no arranque (+5 s) e a cada 5 minutos, com timers unref e operação idempotente. A longo prazo, mover para worker ou cron dedicado.
Porquê: com várias réplicas, o job corre em paralelo. Locks e updates condicionais protegem o resultado, mas gastam recursos.
21. Testes e verificação
Implementação: Vitest (unitários e integração), cobertura com V8, typecheck e lint (Biome) em cada alteração. Prioridade: autenticação, RBAC, reservas, pagamentos e concorrência.
Porquê: é aqui que um bug custa dinheiro ou dados.
22. Observabilidade e deploy
Implementação:
/health(liveness: o processo está vivo) e/health/ready(readiness: a base de dados responde).- Logs estruturados com
request.id; mais tarde, métricas Prometheus e OpenTelemetry. - Imagem Docker
node:24-alpine,docker-composecom API, PostgreSQL e Redis, entrypoint que corre migrações.
Porquê: liveness e readiness separados permitem que o orquestrador decida reiniciar ou só retirar tráfego. Ambientes reprodutíveis.
23. Dívida técnica documentada
Implementação: mantém uma lista honesta. No meu caso:
- rate limit, lockout de login e códigos de troca OAuth em memória (não partilhados entre réplicas; precisam de Redis ou sticky session);
- uploads em disco local (precisam de volume persistente ou S3 com URL assinada);
- job de expiração dentro do processo da API;
- sem CI, sem fila de eventos (outbox/retry) e sem paginação por cursor.
Porquê: quem sabe onde está a dívida consegue priorizá-la.
Checklist rápido
Fundações
- ☐ Módulos por domínio (routes, schema, controller, service)
- ☐ Ambiente validado com fail-fast
- ☐ TypeScript strict + lint
Contrato e camadas
- ☐ JSON Schema em body, query, params e resposta (
additionalProperties: false) - ☐ Controller fino, regras no service
- ☐ Error handler global (503 DB, 500 genérico,
x-request-id)
Identidade e acesso
- ☐ JWT curto (HS256, 15 min) com
sub,role,iss,aud - ☐ Refresh token opaco, só o hash (SHA-256) guardado
- ☐ Rotação com
familyIde revogação em caso de reutilização - ☐ Argon2id, hash dummy anti-timing e lockout de login
- ☐ RBAC + verificação de propriedade (anti-IDOR)
Perímetro HTTP
- ☐ CORS com allowlist
https:// - ☐ Helmet (CSP, HSTS)
- ☐ Rate limit, limites de body e
TRUSTED_PROXIES - ☐ Under-pressure activo
Dados e dinheiro
- ☐ Migrações versionadas, índices e
UNIQUE - ☐ Dinheiro em inteiros e fuso
Africa/Luanda - ☐ Transacções,
FOR UPDATEe updates condicionais (409) - ☐ Ledger e máquina de estados
- ☐ Webhooks e jobs idempotentes
- ☐ Webhooks autenticados (
timingSafeEqual) e uploads validados
Operação
- ☐ Cache-aside tolerante a falhas
- ☐ Testes de auth, RBAC, pagamentos e concorrência
- ☐
/healthe/health/ready, logs comrequest.id - ☐ Docker com migrações automáticas
- ☐ Dívida técnica escrita e priorizada
Para terminar
Um backend de sénior não é o que usa mais tecnologia. É o que faz menos suposições, protege o que importa e deixa o próximo programador (muitas vezes, eu daqui a seis meses) a perceber o que se passou.
Menos pânico, mais diagnóstico.
— Orlando Saiombo