Melhores Práticas do Event Loop

Regras para manter o event loop do Node.js responsivo sob carga - descarregue CPU, agrupe I/O e meça o lag antes que os usuários o sintam.

Como Usar Esta Lista

• Revise antes de enviar endpoints que analisam, transformam ou criptografam payloads.
• Emparelhe com testes de carga que sustentam requisições concorrentes, não curls de tiro único.
• Trate qualquer item de CPU-na-thread-principal não verificado como um incidente de produção esperando para acontecer.
• Releia após atualizações de dependência que adicionam trabalho síncrono em middleware.

A - Mantenha a Thread Principal Livre

• Nunca execute loops pesados de CPU, criptografia ou compressão no caminho da requisição sem workers. Mova para worker_threads ou uma fila.
• Evite APIs *Sync (readFileSync, bcrypt.hashSync) em manipuladores HTTP. Use variantes assíncronas de promise ou callback.
• Limite o tamanho de entrada de JSON.parse na borda e na aplicação. Corpos grandes bloqueiam a análise de forma síncrona.
• Não registre objetos enormes de forma síncrona. Serialize apenas resumos ou campos de amostra.
• Profile o novo middleware com métricas de atraso do loop antes de mesclar. Um middleware lento prejudica todas as rotas.

B - Padrões Assíncronos

• Use Promise.all para I/O independente, não await sequencial em loops. Adicione limites de concorrência para lotes grandes.
• Prefira queueMicrotask ou setImmediate em vez de setTimeout(fn, 0) para adiamento. Combine o tipo de adiamento com as necessidades de ordenação.
• Nunca recorra a process.nextTick para agrupar trabalho. Isso deixa I/O e timers sem atendimento.
• Sempre use try/catch em código aguardado em manipuladores de requisição. Rejeições não tratadas derrubam o processo.
• Use for await em streams em vez de carregar payloads inteiros na memória. Streams cooperam com backpressure.

C - Timers e Agendamento

• Trate setTimeout/setInterval como aproximados, não relógios em tempo real. Use agendadores externos para cron de relógio de parede.
• Evite callbacks setInterval sobrepostos. Encadeie setTimeout após a conclusão do trabalho.
• Limpe timers no desligamento (SIGTERM). Ou chame .unref() apenas quando for intencionalmente fire-and-forget.
• Adicione jitter aos timers de backoff de retentativa. Evite retentativas sincronizadas entre instâncias.
• Limite timers concorrentes na memória. Milhares de handles adicionam sobrecarga de fase de timer.

D - Observabilidade

• Exporte p99 de atraso do event loop de monitorEventLoopDelay. Alerte antes que o p99 voltado para o usuário dobre.
• Rastreie eventLoopUtilization ao lado da CPU. ELU alta com CPU moderada sinaliza blocos síncronos.
• Use blocked-at em staging para atribuir blocos a stack traces. Não ativado o tempo todo em produção.
• Teste de carga com concorrência realista, não requisições únicas. Blocos se escondem até que o tráfego se sobreponha.
• Documente seções síncronas conhecidas em ADRs. Contribuidores futuros herdam as salvaguardas.

E - Arquitetura

• Envie jobs vinculados à CPU para BullMQ/workers. A camada HTTP permanece vinculada a I/O e rápida.
• Use pooling de conexão para clientes DB e HTTP. Evite padrões de bloqueio de configuração TCP + TLS por requisição.
• Prefira respostas de streaming para downloads grandes. Transferência em chunks mantém a memória e o tempo do loop estáveis.
• Escale réplicas antes de otimizar microtasks. Escala horizontal mascara I/O; blocos de CPU precisam de workers.
• Releia Fases do libuv ao depurar a ordenação. Adivinhar o comportamento da fila desperdiça horas.

FAQs

Relacionado

• Detectando Bloqueio do Event-Loop - métricas e ferramentas
• Como o Node.js Funciona - modelo V8 + libuv
• worker_threads - descarregar trabalho de CPU
• Melhores Práticas de Streams - backpressure e I/O

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.