Mejores Prácticas para las Reglas de Node.js

Cómo convertir las reglas de servicio de Node de documentación en una práctica de ingeniería aplicada y auditable.

Cómo Usar Esta Lista

• Combínala con la Lista de Verificación de Reglas de Proyectos Node cada trimestre.
• Cada regla debe mapearse a CI, lint o revisión de código, no a un sistema de honor.
• El equipo de plataforma mantiene plantillas que incorporan valores predeterminados aplicables.

A - Mecanismos de Aplicación

• CI falla en lint, typecheck, prueba, auditoría, no advertencias en README. Las reglas sin puertas se deterioran en semanas.
• Las plantillas incluyen .npmrc engine-strict, ESLint, prueba de ejemplo, Dockerfile. Los nuevos repositorios comienzan siendo conformes.
• La lista de verificación de PR enlaza la lista de verificación de reglas para características importantes. Puerta humana para la automatización de reglas que no se puede cubrir.
• Sustituir los ADR al revertir decisiones. El historial de Git explica por qué cambiaron las reglas.
• Ticket de auditoría de reglas trimestral. El propietario escanea la lista de verificación de aprobación/fallo por catálogo de servicios.

B - Tiempo de Ejecución y Fiabilidad

• Apagado elegante probado con integración. Prueba SIGTERM en CI o script de despliegue en staging.
• La preparación difiere de la vivacidad. Verificación de la base de datos solo en /ready para evitar la eliminación en cascada durante interrupciones.
• Reglas de bucle de eventos y E/S síncrona en lint/revisión de arquitectura. Bloquear readFileSync en src/ mediante una regla personalizada o grep CI.
• Los tiempos de espera de salida son obligatorios en el wrapper del cliente HTTP. Se utiliza un único fetchWithTimeout en toda la organización.
• Los trabajos de los workers llevan IDs de correlación de la solicitud desencadenante. El seguimiento se une a través de límites asíncronos.

C - Seguridad y Dependencias

• Zod (o equivalente) en cada ruta de mutación. No hay req.body sin procesar en lo profundo de los servicios.
• Escaneo de secretos al hacer push. Escaneo de secretos de GitHub más gitleaks en CI.
• Se requiere un wrapper SSRF para las URL de usuario. No hay fetch(userInput) en ningún lugar.
• Programa de auditoría semanal de dependencias. No solo cuando Renovate abre PR.
• RFC antes de una nueva dependencia de producción. knip evita la acumulación de dependencias no utilizadas.

D - API y Observabilidad

• Manejador de errores global con forma JSON única. Los clientes y BFFs dependen de la consistencia.
• Claves de idempotencia en mutaciones financieras. El índice único de la base de datos lo aplica; no es solo una caché de la aplicación.
• Solo logs JSON estructurados; Pino o equivalente. no-console en src/.
• Métricas para señales doradas: latencia, tráfico, errores, saturación. Métricas RED mínimas por servicio.
• Esquemas OpenAPI o Zod publicados para APIs públicas. La fuente de verdad del contrato documentada.

E - Cultura y Propiedad

• Runbook de guardia enlazado y probado después de cambios importantes. Las reglas 21-25 son una parte operativa.
• Los incidentes actualizan las reglas o los ADR cuando se encuentran deficiencias. Las acciones post-mortem se convierten en elementos de la lista de verificación.
• La incorporación de juniors recorre la lista de verificación de nivel 1. Seguridad y tiempo de ejecución antes de la velocidad de las características.
• Las excepciones de plataforma tienen un tiempo limitado. Las exenciones de engine-strict caducan con el ID del ticket.
• Las reglas se enseñan a través de ejemplos de revisión de código, no solo diapositivas. Enlazar el documento de reglas en los comentarios de revisión.

Preguntas Frecuentes

Relacionado

• Lista de Verificación de Reglas de Proyectos Node - Auditoría de 25 reglas
• Plantilla ADR para Node - Documentar decisiones
• Reglas de Seguridad - Detalles de las reglas de seguridad

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.