Práticas Recomendadas de Resiliência

Documente a segurança de retentativas por endpoint no OpenAPI. Estas regras mantêm os serviços Node.js disponíveis quando as dependências ficam lentas ou falham.

Como Usar Esta Lista

• Aplique a cada nova integração de saída e rota HTTP.
• Emparelhe com testes de carga que simulam latência 503 downstream.
• Adicione extensões OpenAPI x-retry-safe e x-idempotency por operação.
• Revise durante os postmortems de incidentes quando as retentativas amplificaram interrupções.

A - Timeouts e Prazos

• Cada chamada fetch e cliente HTTP usa AbortSignal.timeout. Sem esperas infinitas.
• statement_timeout do DB ou timeout de consulta do driver configurado. Bloqueio no lado do servidor para SQL descontrolado.
• Timeout de saída < prazo do manipulador < requestTimeout do servidor < ocioso do LB. Orçamento escalonado.
• Timeout de aquisição de conexão em pools. Métricas de espera do pool de log.
• Jobs BullMQ têm a opção timeout. Workers não executam sem limites.

B - Retentativas e Idempotência

• Retente apenas erros 5xx e de rede, não 4xx. Classifique o que pode ser retentado versus o que é fatal.
• Backoff exponencial com jitter entre tentativas. Máximo de 3-5 tentativas em caminhos síncronos.
• Idempotency-Key em POST que cria cobranças ou pedidos. Documente no OpenAPI.
• Armazene o mapeamento chave de idempotência -> resposta por 24h+ para pagamentos. Retorne o cache em caso de duplicidade.
• Pare de retentar quando o circuito estiver aberto. Falhe rapidamente localmente.

C - Circuit Breakers e Degradação

• opossum (ou equivalente) por dependência downstream. Breakers separados por serviço.
• Fallback apenas em recursos de nível 1/2. Nunca finja sucesso de pagamento ou autenticação.
• Retorne meta.degraded em respostas da API ao descartar recursos. O cliente pode ajustar a UI.
• Flags de recursos para desativar caminhos opcionais durante incidentes. FEATURE_X=off sem redeploy.
• Alerta em eventos open do circuito. Notifique quando o breaker de dependência principal abrir.

D - Saúde e Ciclo de Vida

• Liveness barato; readiness verifica DB e dependências críticas. Sem verificações lentas na liveness.
• SIGTERM gracioso: server.close, esvazie pools, sdk.shutdown(). Corresponda ao período de graça do k8s.
• Falhe na readiness durante migrações, se necessário. O tráfego é direcionado para os pods antigos.
• Backlog da fila monitorado como indicador principal. Alerta de profundidade antes dos timeouts dos workers.
• Chaos ou injeção de falha em staging trimestralmente. Valide se os caminhos de degradação funcionam.

E - Documentação e Contratos

• OpenAPI documenta idempotência e segurança de retentativa por operação. Os consumidores conhecem as regras de retentativa seguras.
• Runbook por dependência: timeout, limites do breaker, comportamento de fallback. On-call pronto.
• Classifique as dependências como nível 0/1/2 no README do serviço. Esclarece a política de degradação.
• SLI inclui taxa de timeout de dependência. Não apenas 5xx do seu serviço.
• Revisão pós-incidente pergunta "as retentativas amplificaram?" Ajuste os limites do breaker e de retentativa.

FAQs

Relacionados

• Noções Básicas de Resiliência - exemplos introdutórios
• Timeouts em Todos os Lugares - matriz de timeouts
• Retentativas com Backoff - padrões de idempotência
• OpenAPI & Swagger - documente extensões de retentativa

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.