srsaiombo

Backend de sénior: o que deve ter, passo a passo (sem querer insinuar nada)

Um guia passo a passo do que um backend de sénior deve ter: configuração validada, contratos, autenticação, transações, segurança HTTP, testes, logs e deploy. Cada ponto explicado com o que fazer e porquê, sem pressa e sem termos escondidos.

Imagem de capa: Backend de sénior: o que deve ter, passo a passo (sem querer insinuar nada)

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_ORIGINS ou TRUSTED_PROXIES.
  • Rejeita JWT_SECRET com o valor de exemplo e origens que não usem https://.

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, params e a resposta.
  • AJV com removeAdditional: false, coerceTypes: false, useDefaults: true, allErrors: true.
  • additionalProperties: false em 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 userId e body e 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.
  • setErrorHandler global: usa o statusCode do AppError, 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 via genReqId) devolvido no cabeçalho x-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) e aud (audiência). O authenticate valida todas.
  • O authenticate rejeita roles fora do esperado e tokens com kind: '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 UPDATE pelo hash, consumo com update condicional, emissão de novo token na mesma familyId.
  • 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-limit global, 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_PROXIES obrigatório: define de que proxies se aceita o X-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 UNIQUE onde 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ó actualiza PENDING/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 com timingSafeEqual (evita timing attacks) e responde sempre { "status": "1" } depois de processar, registando erros no log.
  • Uploads: @fastify/multipart com 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-compose com 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 familyId e 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 UPDATE e 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
  • ☐ /health e /health/ready, logs com request.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

Achaste útil?

Leva esta ideia contigo.

Novidades sem ruído

A próxima ideia
chega à tua caixa.

Recebe um email quando sair um novo artigo. Sem frequência inventada e podes cancelar quando quiseres.

Só usamos o email para enviar novidades do blogue.