Melhores Práticas de Eventos

Eventos no processo se mantêm manuteníveis com contratos explícitos, limpeza disciplinada e limites claros entre notificação e mensagens duráveis.

Como Usar Esta Lista

• Revise ao adicionar manipuladores EventEmitter, @OnEvent ou on de socket.
• Qualquer listener global sem plano de limpeza é um risco de vazamento de produção.
• Releia ao promover eventos no processo para integração entre serviços.
• Use em conjunto com Vazamentos de Memória de Listeners.

A - Nomenclatura e Contratos

• Nomeie eventos do domínio no passado (pedido.pago, não pagarPedido). Reflete fatos que já ocorreram.
• Publique o nome do evento e os tipos de payload de um módulo compartilhado ou emitter tipado. Sem strings mágicas espalhadas.
• Versionar mudanças que quebram o payload (envelope v2 ou novo nome de evento). Documente a migração para os assinantes.
• Mantenha payloads pequenos e focados em identificadores. Passe IDs, não grafos ORM completos.
• Documente quais eventos são de domínio vs. de integração. Eventos de integração cruzam limites de serviço com esquemas.

B - Ciclo de Vida e Memória

• Remova listeners quando o escopo da requisição HTTP, socket ou job terminar. Use off, once ou AbortSignal.
• Nunca aumente setMaxListeners sem corrigir o registro duplicado. Avisos indicam vazamentos.
• Evite anexar manipuladores por requisição a emitters singleton globais do processo sem limpeza. Padrão de vazamento #1.
• Em testes, desfaça os listeners em afterEach. Evite acúmulo de listeners instáveis.
• Ao desligar, use removeAllListeners apenas para barramentos de propriedade do aplicativo. Não em internos compartilhados do Node imprudentemente.

C - Tratamento de Erros e Desempenho

• Envolva listeners assíncronos com try/catch ou Promise.allSettled para fan-out. Uma falha não deve quebrar as outras silenciosamente.
• Não espere I/O longo dentro do emit, a menos que a arquitetura exija. Prefira enfileirar o job a partir de um manipulador leve.
• Não use EventEmitter para fluxos de bytes com alta pressão de backpressure. Use streams em vez disso.
• Emita após o commit da transação do banco de dados para consistência. Ou use a fila de outbox transacional.
• Registre falhas de manipuladores com o nome do evento e ID de correlação, não com PII de payload completo.

D - Quando Não Usar EventEmitter

• Use uma fila quando o trabalho deve sobreviver a uma falha do processo. BullMQ, SQS, etc.
• Use chamadas de função diretas quando um módulo é o proprietário do fluxo de trabalho. Eventos são para fan-out desconhecido.
• Use HTTP/webhooks para contratos de serviço entre equipes. Não um barramento compartilhado em memória.
• Use streams para processamento de bytes/chunks. Não eventos data em emitters personalizados.
• Use spans do OpenTelemetry para observabilidade transversal. Não eventos de métricas ad-hoc, a menos que sejam significativos para o domínio.

E - TypeScript e Testes

• Subclasse ou envolva EventEmitter com emit/on tipados. Veja Typed EventEmitter.
• Teste unidades de manipuladores isoladamente com dependências mockadas. Teste a integração da fiação do barramento separadamente.
• Afirme que listenerCount retorna ao baseline após trabalho com escopo. Teste de regressão de vazamento automatizado.
• Faça lint contra literais de string brutos para nomes de eventos no código do aplicativo. Apenas constantes ou mapa tipado.
• Compartilhe o pacote de tipos de evento sem imports apenas do servidor. Seguro para workers e testes.

FAQs

Relacionados

• Vazamentos de Memória de Listeners - padrões de limpeza
• Domain Events vs EventEmitter - fila vs barramento
• Typed EventEmitter - contratos TypeScript
• BullMQ ioredis - eventos duráveis

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.