Mejores prácticas del bucle de eventos

Reglas para mantener el bucle de eventos de Node.js receptivo bajo carga: descarga la CPU, procesa E/S por lotes y mide el retraso antes de que los usuarios lo perciban.

Cómo usar esta lista

• Revisa antes de implementar endpoints que analicen, transformen o cifren cargas útiles.
• Combina con pruebas de carga que mantengan solicitudes concurrentes, no curls de una sola vez.
• Trata cualquier elemento de CPU en el hilo principal sin verificar como un incidente de producción a punto de ocurrir.
• Vuelve a revisar después de las actualizaciones de dependencias que añaden trabajo síncrono en el middleware.

A - Mantén el hilo principal libre

• Nunca ejecutes bucles intensivos de CPU, criptografía o compresión en la ruta de solicitud sin workers. Muévete a worker_threads o a una cola.
• Evita las API *Sync (readFileSync, bcrypt.hashSync) en los manejadores HTTP. Usa variantes asíncronas de promesa o callback.
• Limita el tamaño de entrada de JSON.parse en el borde y la aplicación. Los cuerpos grandes bloquean el análisis de forma síncrona.
• No registres objetos enormes de forma síncrona. Serializa solo resúmenes o campos de muestra.
• Perfila el nuevo middleware con métricas de retraso del bucle antes de fusionar. Un middleware lento afecta a todas las rutas.

B - Patrones asíncronos

• Usa Promise.all para E/S independientes, no await secuencial en bucles. Añade límites de concurrencia para lotes grandes.
• Prefiere queueMicrotask o setImmediate sobre setTimeout(fn, 0) para el aplazamiento. Haz coincidir el tipo de aplazamiento con las necesidades de ordenación.
• Nunca recurras a process.nextTick para procesar trabajo por lotes. Agota las E/S y los temporizadores.
• Siempre try/catch el código await en los manejadores de solicitudes. Las promesas rechazadas sin manejar detienen el proceso.
• Usa for await en los streams en lugar de cargar cargas útiles completas en la memoria. Los streams cooperan con la contrapresión.

C - Temporizadores y planificación

• Trata setTimeout/setInterval como aproximados, no como relojes en tiempo real. Usa planificadores externos para cron de reloj de pared.
• Evita que las callbacks de setInterval se superpongan. Encadena setTimeout después de que el trabajo se complete.
• Borra los temporizadores al apagarse (SIGTERM). O llama a .unref() solo cuando sea intencionalmente "disparar y olvidar".
• Añade fluctuación a los temporizadores de retroceso de reintento. Evita reintentos sincronizados entre instancias.
• Limita los temporizadores concurrentes en memoria. Miles de manejadores añaden sobrecarga a la fase de temporizador.

D - Observabilidad

• Exporta el retraso p99 del bucle de eventos desde monitorEventLoopDelay. Alerta antes de que el p99 visible para el usuario se duplique.
• Rastrea eventLoopUtilization junto con la CPU. Un ELU alto con una CPU moderada indica bloques síncronos.
• Usa blocked-at en staging para atribuir bloques a trazas de pila. No siempre activo en producción.
• Prueba de carga con concurrencia realista, no con solicitudes individuales. Los bloques se ocultan hasta que el tráfico se superpone.
• Documenta las secciones síncronas conocidas en los ADR. Los futuros colaboradores heredan las salvaguardias.

E - Arquitectura

• Envía trabajos intensivos de CPU a BullMQ/workers. La capa HTTP permanece ligada a E/S y es rápida.
• Usa la agrupación de conexiones para clientes de DB y HTTP. Evita patrones de bloqueo de configuración de TCP + TLS por solicitud.
• Prefiere respuestas de streaming para descargas grandes. La transferencia por fragmentos mantiene la memoria y el tiempo de bucle estables.
• Escala réplicas antes de optimizar microtareas. La escala horizontal enmascara las E/S; los bloques de CPU necesitan workers.
• Vuelve a leer Fases de libuv al depurar el orden. Adivinar el comportamiento de la cola desperdicia horas.

Preguntas frecuentes

Relacionado

• Detección de bloqueo del bucle de eventos - métricas y herramientas
• Cómo funciona Node.js - modelo V8 + libuv
• worker_threads - descarga el trabajo de la CPU
• Mejores prácticas de Streams - contrapresión y E/S

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.