Mejores Prácticas de las APIs Integradas

Node 24 incluye la mayoría de las primitivas que los backends necesitan; por defecto, usa módulos node:, APIs de promesas y patrones de seguridad documentados antes de añadir superficie de npm.

Cómo Usar Esta Lista

• Revisa durante las PR de dependencias que añaden paquetes que se superponen con las APIs integradas.
• Aplica a cada nuevo arranque de servicio y ruta de E/S de archivos.
• Las rutas sensibles a la seguridad (crypto, rutas, child_process) son elementos obligatorios.
• Revisa cuando las notas de lanzamiento de Node añadan nuevas APIs estables (por ejemplo, fetch, test).

A - Selección de Módulos

• Importa las APIs integradas con el prefijo node: en el código de la aplicación. node:fs/promises, node:crypto, etc.
• Prefiere las APIs de promesas (fs/promises, timers/promises) sobre las callbacks. Promisifica solo para callbacks de terceros.
• Usa fetch global y node:test antes de añadir node-fetch/Jest para casos simples. Menos dependencias.
• Evalúa un paquete npm solo cuando la API integrada carezca de una característica (políticas de reintento, OTel SDK). Documenta el ADR cuando añadas superposición.
• Fija @types/node a la versión mayor del tiempo de ejecución (24.x). Los tipos coinciden con la disponibilidad de la API.

B - Sistema de Archivos y Streams

• Nunca uses readFileSync/writeFileSync en rutas de solicitud. Bloquea el bucle de eventos.
• Transmite archivos de más de unos pocos MB con createReadStream + pipeline. Memoria limitada.
• Protege el recorrido de rutas en rutas influenciadas por el usuario. resolve + verificación de prefijo bajo el directorio base.
• Establece el modo de archivo unix 0o600 en secretos escritos en disco. Permisos restrictivos.
• Cierra los manejadores de archivos en finally cuando uses fs.open. Evita fugas de EMFILE.

C - Criptografía y URLs

• Genera tokens con randomBytes/randomUUID, nunca con Math.random. Solo CSPRNG.
• Verifica webhooks con HMAC y timingSafeEqual en resúmenes de igual longitud. Sin comparación de cadenas simples.
• Hashea contraseñas con scrypt/argon2, no solo SHA256. Ajusta los parámetros de costo.
• Analiza URLs con WHATWG URL, no con el obsoleto url.parse. Lista blanca de SSRF en el nombre de host.
• No registres secretos, el entorno completo o bytes de firma. Redacta en los errores.

D - Proceso, SO y Temporizadores

• Dimensiona los pools con os.availableParallelism(), no con el recuento de CPU sin procesar en contenedores. Conciencia correcta de vCPU.
• Valida process.env una vez al inicio con Zod. Configuración inmutable después del análisis.
• Maneja SIGTERM con drenaje HTTP; consulta la sección de procesos. También servidores http integrados.
• Borra los temporizadores al apagar; usa unref para tics de fondo opcionales. Salida de despliegue limpia.
• Expón metadatos mínimos del host en los puntos de conexión de salud públicos. Sin enumeración de red interna.

E - Diagnóstico

• Usa los límites de util.inspect al registrar objetos, no JSON.stringify sin límites. Evita ciclos y volcados de PII.
• Habilita NODE_DEBUG solo en reproducción de desarrollo/staging. No permanente en producción.
• Usa las métricas del bucle de eventos de perf_hooks en pruebas de carga de staging. Correlaciona con la latencia del usuario.
• Marca la documentación de la API de Node 24 para APIs específicas de la versión (parseEnv, styleText). Evita patrones de blog obsoletos.
• Suscribe diagnostics_channel con limpieza en las pruebas. Sin fugas de listener.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de las APIs Integradas - recorrido por los módulos
• Mejores Prácticas Fundamentales de Node.js - LTS y entorno
• Conceptos Básicos de Librerías Esenciales - cuándo añadir npm
• Conceptos Básicos de Seguridad - seguridad más amplia

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