Mejores prácticas de Streams

Los streams mantienen los servicios de Node estables en memoria; estas reglas previenen sockets colgados, OOM por buffers ilimitados y pérdida silenciosa de datos en eventos error no manejados.

Cómo usar esta lista

• Aplícala a cada carga de archivo, descarga, ETL y ruta gzip.
• Trata .pipe().pipe() manual sin manejadores de errores como un impedimento para la revisión.
• Realiza pruebas de carga en los endpoints de streaming con clientes lentos, no solo con curls rápidos en localhost.
• Combínala con las Mejores prácticas de Buffers para límites de tamaño.

A - Cableado y Errores

• Usa stream/promises.pipeline en lugar de cadenas pipe simples. Destrucción automática en caso de error.
• Envuelve await pipeline(...) en un try/catch en los manejadores HTTP. Mapea a 500 solo si los encabezados no se han enviado.
• Adjunta listeners de error si no usas pipeline. Excepciones raras para código heredado con ticket de migración.
• Destruye las lecturas ascendentes cuando el cliente HTTP aborta. Escucha req.on('aborted') o AbortSignal.
• Implementa _flush en Transforms que almacenan en búfer fragmentos/líneas parciales. No pierdas datos finales.

B - Memoria y Contrapresión

• Transmite cualquier carga útil que no quepa cómodamente en un solo Buffer. Regla general: varios MB+.
• Respeta que write() devuelva false en bucles personalizados. Pausa hasta drain.
• Ajusta highWaterMark con mediciones, no con conjeturas. Observa el heap y la latencia p99.
• Evita Array ilimitados de fragmentos antes de la concatenación. Usa pipeline o una cola limitada.
• Limita los objetos de stream en modo objeto a un tamaño razonable. No es un sustituto de los límites de bytes en JSON enormes.

C - Streaming HTTP

• Establece los encabezados content-type y de disposición antes de los bytes del cuerpo. Requerido para descargas y NDJSON.
• Deshabilita el almacenamiento en búfer del proxy para rutas de streaming en la configuración de nginx/CDN. O usa URLs pre-firmadas para archivos enormes.
• Alinea los tiempos de espera inactivos del balanceador de carga con el stream esperado más largo. O envía bytes de keepalive periódicos donde el protocolo lo permita.
• No comprimas dos veces los activos gzipeados. Evita el middleware de compresión en rutas precomprimidas.
• Usa Content-Length cuando el tamaño sea conocido. Mejor comportamiento de CDN y progreso de descarga.

D - Formatos y Transformaciones

• Mantén las transformaciones gzip/crypto en el orden de pipeline documentado. Bytes antes de las conversiones a modo objeto.
• Analiza los frames binarios con Transform incremental, no con concatenación de búfer completo. Consulta Protocolos binarios.
• Valida el tamaño máximo de frame/cuerpo antes de la asignación. Rechaza prefijos de longitud maliciosos.
• Prefiere iterables asíncronos Readable.from para fuentes simples. Subclase Readable cuando se necesite _read con estado.
• Conecta Web Streams con fromWeb/toWeb en los límites de fetch. No almacenes en búfer response.arrayBuffer() por defecto.

E - Operaciones

• Registra los errores de stream con el nombre de la ruta y el ID de correlación, no con el contenido del fragmento. Evita PII en los logs.
• Monitorea los descriptores de archivo abiertos durante las pruebas de carga de exportación. Las fugas aparecen como EMFILE.
• Prueba de integración las respuestas fragmentadas con un cliente consumidor lento. Supertest puede ocultar errores de streaming.
• Documenta qué rutas transmiten en los manuales de operaciones. Los respondedores de incidentes verifican primero el almacenamiento en búfer del proxy.
• Prefiere las URLs de almacenamiento de objetos pre-firmadas cuando el ancho de banda de la API gateway es costoso. Transmite a través de la API solo cuando se requiera auditoría.

Preguntas frecuentes

Relacionado

• stream/promises.pipeline - Referencia de la API
• Contrapresión - pausa/drenaje
• Streaming de respuestas HTTP - proxies
• Mejores prácticas de Buffers - límites de tamaño

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.