Mejores prácticas para eventos

Los eventos en proceso se mantienen manejables con contratos explícitos, limpieza disciplinada y límites claros entre la notificación y la mensajería duradera.

Cómo usar esta lista

• Revisa al añadir EventEmitter, @OnEvent o manejadores on de socket.
• Cualquier listener global sin un plan de limpieza es un riesgo de fuga en producción.
• Vuelve a visitar al promover eventos en proceso a una integración entre servicios.
• Combínalo con Fugas de memoria de listeners.

A - Nomenclatura y Contratos

• Nombra los eventos de dominio en tiempo pasado (order.paid, no payOrder). Refleja hechos que ya ocurrieron.
• Publica el nombre del evento y los tipos de carga útil desde un módulo compartido o un emisor tipado. Sin cadenas mágicas dispersas.
• Versiona los cambios de carga útil que rompen la compatibilidad (envoltorio v2 o nuevo nombre de evento). Documenta la migración para los suscriptores.
• Mantén las cargas útiles pequeñas y centradas en identificadores. Pasa IDs, no grafos ORM completos.
• Documenta qué eventos son de dominio vs. integración. Los eventos de integración cruzan los límites del servicio con esquemas.

B - Ciclo de vida y Memoria

• Elimina los listeners cuando finalice el alcance de la solicitud HTTP, el socket o el trabajo. off, once o AbortSignal.
• Nunca aumentes setMaxListeners sin corregir el registro duplicado. Las advertencias indican fugas.
• Evita adjuntar manejadores por solicitud a emisores singleton globales de proceso sin limpieza. Patrón de fuga #1.
• En las pruebas, desmonta los listeners en afterEach. Evita la acumulación de listeners inestables.
• Al apagar, removeAllListeners solo para buses propiedad de la aplicación. No en internos de Node compartidos de forma imprudente.

C - Manejo de errores y Rendimiento

• Envuelve los listeners asíncronos con try/catch o Promise.allSettled fan-out. Un fallo no debe romper otros silenciosamente.
• No esperes E/S largas dentro de emit a menos que la arquitectura lo requiera. Prefiere encolar el trabajo desde un manejador delgado.
• No uses EventEmitter para flujos de bytes con mucha contrapresión. Usa streams en su lugar.
• Emite después de que las transacciones de la base de datos se confirmen para la consistencia. O usa una bandeja de salida transaccional para encolar.
• Registra los fallos del manejador con el nombre del evento y el ID de correlación, no la PII completa de la carga útil.

D - Cuándo no usar EventEmitter

• Usa una cola cuando el trabajo deba sobrevivir a un fallo del proceso. BullMQ, SQS, etc.
• Usa llamadas a funciones directas cuando un módulo sea dueño del flujo de trabajo. Los eventos son para fan-out desconocido.
• Usa HTTP/webhooks para contratos de servicio entre equipos. No un bus en memoria compartido.
• Usa streams para el procesamiento de bytes/chunks. No eventos data en emisores personalizados.
• Usa spans de OpenTelemetry para la observabilidad transversal. No eventos de métricas ad-hoc a menos que tengan un significado de dominio.

E - TypeScript y Pruebas

• Subclase o envuelve EventEmitter con emit/on tipados. Consulta Typed EventEmitter.
• Prueba unitariamente los manejadores de forma aislada con dependencias mockeadas. Prueba la conexión del bus por separado.
• Asegúrate de que listenerCount vuelve a la línea base después del trabajo con alcance. Prueba de regresión automatizada de fugas.
• Lint contra literales de cadena sin procesar para nombres de eventos en el código de la aplicación. Solo constantes o mapa tipado.
• Comparte el paquete de tipos de eventos sin importaciones solo de servidor. Seguro para workers y pruebas.

Preguntas frecuentes

Relacionado

• Fugas de memoria de listeners - patrones de limpieza
• Eventos de dominio vs. EventEmitter - cola vs. bus
• Typed EventEmitter - contratos de TypeScript
• BullMQ ioredis - eventos duraderos

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.