Noções Básicas de Resiliência

8 exemplos para você começar com Resiliência para backends Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

• Node.js 24.18.0 com fetch nativo e AbortSignal.timeout.
• Serviço HTTP por trás de Kubernetes, ECS ou similar para probes de saúde/prontidão.

Exemplos Básicos

1. Timeout em fetch de Saída

Chamadas downstream travadas esgotam seu pool de conexões.

const response = await fetch("https://api.partner.com/data", {
  signal: AbortSignal.timeout(5_000),
});

• AbortSignal.timeout disponível no Node 18+ - sem setTimeout manual.
• Mapeie TimeoutError para 504 ou política de retentativa upstream.
• Timeouts mais curtos em caminhos voltados para o usuário do que em jobs em lote.

Relacionado: Timeouts em Todos os Lugares - matriz completa de timeouts

2. Falha Rápida na Configuração de Inicialização

Não sirva tráfego com ambiente inválido.

import { z } from "zod";
 
const Env = z.object({
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().default(3000),
});
 
export const env = Env.parse(process.env); // lança antes de iniciar()

• Processo sai com código não zero - orquestrador reinicia com configuração corrigida.
• Prontidão permanece falsa até que a migração do DB seja concluída, se você a usar como portão.
• Melhor um deploy falho do que erros silenciosos em tempo de execução a cada requisição.

Relacionado: Noções Básicas de Configuração - parse de env com Zod

3. Liveness vs Readiness

Informe ao Kubernetes se deve reiniciar ou parar de enviar tráfego.

app.get("/health", (_req, res) => res.json({ ok: true }));
 
app.get("/ready", async (_req, res) => {
  try {
    await db.query("SELECT 1");
    res.json({ ready: true });
  } catch {
    res.status(503).json({ ready: false });
  }
});

• Liveness: processo não está em deadlock - verificação barata.
• Readiness: dependências disponíveis - falha quando o DB está inativo, então o kube o remove do LB.
• Não coloque verificações lentas na liveness - loops de reinicialização.

Relacionado: Noções Básicas de Observabilidade - padrões de probe

4. Desligamento Gracioso em SIGTERM

Drene requisições HTTP em andamento antes de sair no deploy.

const server = app.listen(3000);
 
process.on("SIGTERM", () => {
  server.close(() => {
    logger.info({ event: "shutdown_complete" });
    process.exit(0);
  });
  setTimeout(() => process.exit(1), 30_000).unref();
});

• server.close para de aceitar novas conexões; finaliza as ativas.
• Força a saída após 30s se a drenagem travar - corresponda ao terminationGracePeriodSeconds do k8s.
• Feche pools de DB e SDK OTel no mesmo manipulador de desligamento.

Relacionado: Degradação Graciosa - modos de desativação de funcionalidades

5. Retentativa Apenas Quando Seguro

POST sem chaves de idempotência pode cobrar em duplicidade.

async function safeGetWithRetry(url: string, attempts = 3): Promise<Response> {
  for (let i = 0; i < attempts; i++) {
    try {
      const res = await fetch(url, { signal: AbortSignal.timeout(3_000) });
      if (res.status < 500) return res;
    } catch (err) {
      if (i === attempts - 1) throw err;
    }
    await delay(100 * 2 ** i);
  }
  throw new Error("unreachable");
}

• Retente GET e PUT idempotente - seguro por semântica HTTP (com ressalvas).
• Retente 5xx, não 4xx (erros do cliente não se curarão).
• Backoff exponencial reduz o "thundering herd".

Relacionado: Retentativas com Backoff - jitter e idempotência

6. Retorne Erros Explícitos, Não Travamentos

Usuários e balanceadores de carga precisam de uma resposta dentro do SLA.

app.use((req, res, next) => {
  const timer = setTimeout(() => {
    if (!res.headersSent) {
      res.status(504).json({ error: "Gateway Timeout" });
    }
  }, 30_000);
  res.on("finish", () => clearTimeout(timer));
  next();
});

• Timeout em nível de servidor é o último recurso - prefira timeouts por chamada de saída.
• Registre 504 com requestId para correlação.
• Alinhe com o timeout ocioso do LB (frequentemente 60s).

Relacionado: Timeouts em Todos os Lugares - timeouts de servidor

Exemplos Intermediários

7. Esboço de Circuit Breaker

Pare de chamar uma dependência falha para permitir que ela se recupere.

let failures = 0;
const THRESHOLD = 5;
let openUntil = 0;
 
async function callBilling() {
  if (Date.now() < openUntil) throw new Error("Circuit open");
  try {
    const result = await billingClient.charge();
    failures = 0;
    return result;
  } catch (err) {
    failures++;
    if (failures >= THRESHOLD) openUntil = Date.now() + 30_000;
    throw err;
  }
}

• Circuito aberto falha rapidamente requisições locais - economiza threads e carga downstream.
• Retentativa em meio-aberto após cooldown - use a biblioteca opossum em produção.
• Combine com degradação graciosa para a experiência do usuário.

Relacionado: Circuit Breakers - padrões com opossum

8. Bulkhead: Limita Chamadas Concorrentes de Saída

Um fornecedor lento não pode consumir todos os sockets.

import { Semaphore } from "async-mutex"; // ou pool customizado
 
const vendorSem = new Semaphore(10);
 
async function callVendor() {
  const [, release] = await vendorSem.acquire();
  try {
    return await fetch(VENDOR_URL, { signal: AbortSignal.timeout(2_000) });
  } finally {
    release();
  }
}

• Limite chamadas concorrentes para integrações frágeis - padrão bulkhead.
• Requisições restantes falham rapidamente localmente em vez de enfileirar para sempre.
• Ajuste o limite com base no SLA do fornecedor e no tamanho do seu pool.

Relacionado: Circuit Breakers - bulkhead com opossum

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.