Lista de Verificación de Reglas para Proyectos Node
Veinticinco reglas que todo servicio HTTP o worker de Node.js debería cumplir antes de pasar a producción.
Cómo Usar Esta Lista de Verificación
- Recorre de arriba a abajo los nuevos servicios antes del primer despliegue.
- Vuelve a auditar trimestralmente o después de actualizaciones importantes de Node/framework.
- Registra el aprobado/fallido en un apéndice ADR o wiki del equipo; corrige las deficiencias en orden de prioridad.
- Haz cumplir mecánicamente a través de CI siempre que sea posible (no el sistema de honor del README).
Tiempo de Ejecución y Proceso
- Node 24 LTS Activo fijado:
enginesy DockerFROM node:24.18.0están alineados. - Apagado elegante: SIGTERM drena HTTP y cierra los pools de la base de datos dentro del tiempo de espera.
- Rutas de salud y preparación:
/healthpara la vivacidad;/readyverifica la base de datos cuando sea aplicable. - No hay E/S síncronas en rutas críticas:
fs.readFileSyncprohibido en los manejadores de solicitudes. - Concurrencia limitada: HTTP saliente y workers de cola usan límites (p-limit, tamaño del pool).
Seguridad
- Validación de entrada en el límite: Zod o validación de esquema en cada ruta de mutación.
- Secretos del entorno o bóveda: No hay secretos en git;
.envignorado por git. - Protecciones SSRF en fetch saliente: Bloquea IPs locales y de metadatos en URLs proporcionadas por el usuario.
- Encabezados de seguridad y CORS explícitos: No solo los valores predeterminados del framework en producción.
- Comprobación de auditoría de dependencias:
npm audit --audit-level=highpasa en CI.
API y Datos
- Formato JSON de error consistente:
{ error: { code, message } }en todas las rutas. - Paginación en los endpoints de lista:
cursorolimit/offsetcon límites máximos documentados. - Mutaciones idempotentes:
Idempotency-Keyo claves naturales para POST que crean recursos. - Solo registro estructurado: Registros JSON; no hay
console.logsin procesar ensrc/. - ID de correlación en cada solicitud: Propaga
X-Request-Iden los registros y llamadas salientes.
Herramientas y Calidad
- Lockfile commiteado; CI usa
npm ci. Solo instalaciones reproducibles. - Comprobación de tipos en la puerta de fusión:
tsc --noEmiten cada PR. - Política de cero advertencias de lint:
eslint --max-warnings 0. - Pruebas en CI: Unitarias requeridas; de integración para rutas de base de datos con DB aislada.
- Límites de importación aplicados: Las aplicaciones no importan aplicaciones hermanas en monorepos.
Operaciones y Arquitectura
- Construcción Docker multi-etapa: Las dependencias de desarrollo excluidas de la imagen de tiempo de ejecución.
- Configuración validada al inicio: El proceso sale si el esquema de entorno es inválido.
- Tiempos de espera en HTTP saliente: No hay
fetchilimitado a terceros. - ADR para las elecciones de framework y almacén de datos: Express/Fastify/Nest y ORM documentados.
- Runbook enlazado en README: Pasos de guardia para OOM, despliegue incorrecto, interrupción de DB.
Aplicando la Lista de Verificación en Orden
- Nivel 1 (1-5, 6-10): Seguridad y protección - bloquea el lanzamiento si falla.
- Nivel 2 (11-20): Consistencia de la API y puertas de calidad - corrige antes del tráfico GA.
- Nivel 3 (21-25): Madurez operativa - completa dentro del primer mes de producción.
Preguntas Frecuentes
¿Necesitan los workers rutas HTTP de salud?
Los workers necesitan salud del proceso a través de métricas de supervisor; la salud HTTP se aplica a los servicios API. La Regla 3 se adapta al latido del worker.
¿Podemos omitir la idempotencia para las APIs internas?
Las APIs internas aún se benefician de la idempotencia en los endpoints de creación/cobro para sobrevivir a los reintentos.
¿Cómo hacemos cumplir la prohibición de console.log?
ESLint no-console en src/** más la puerta de lint de CI (regla 18).
¿Está NestJS exento del patrón createApp?
Nest usa Test.createTestingModule para las pruebas, pero aún necesita un apagado elegante y las mismas reglas de seguridad/registro.
¿Qué pasa si la auditoría no tiene solución?
Documenta una excepción con tiempo limitado (regla 10) con el propietario; no falles silenciosamente la CI de forma permanente.
¿Cuántas reglas para Lambda sin servidor?
Se aplican las reglas 1-2, 6-8, 11-15, 16-19; Docker (21) se convierte en configuración de empaquetado; el apagado (2) es consciente de la congelación del tiempo de ejecución.
¿Quién firma la lista de verificación?
El líder técnico o el revisor marcan el ticket de lanzamiento; guarda el enlace a la lista de verificación completada.
¿Cómo se relaciona esto con otras páginas de reglas?
Esta lista de verificación resume; los análisis profundos se encuentran en los artículos de reglas de Async, Seguridad, API, Dependencias y Registro en esta sección.
¿Es suficiente la cadencia de auditoría trimestral?
Sí, para servicios estables; vuelve a ejecutar después de una actualización importante de Node o elementos de acción post-mortem de un incidente.
¿Se pueden automatizar las reglas?
Apunte a que las reglas 16-20 estén completamente en CI; las reglas 21-25 necesitan documentación y revisión, pero Docker/ADR pueden ser forzados por plantilla.
Relacionado
- Reglas de Bucle de Eventos y Asíncronas - detalles de las reglas 4-5
- Reglas de Seguridad - detalles de las reglas 6-10
- Reglas de API - detalles de las reglas 11-13
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.