Mejores Prácticas de Arquitectura

Optimiza para el aislamiento del cambio, no para la distribución prematura. Estas prácticas mantienen los backends de Node.js evolucionables sin el costo de los microservicios desde el primer día.

Cómo Usar Esta Lista

• Trata los elementos no marcados como deuda arquitectónica: prioriza el nivel A antes de las nuevas características.
• Vuelve a revisar después de hitos importantes: escala de la Serie B, alcance de PCI o división de equipos.
• Combínalo con la Lista de Verificación de Refactorización trimestralmente.
• Asigna un propietario por regla de límite de módulo, no "el equipo".

A - Empieza Simple, Mantente Evolucionable

• Por defecto, un monolito modular. Un único desplegable con módulos de características es mejor que cinco servicios que nadie puede depurar en guardia. Revisa cuando se mida el bloqueo de despliegues.
• Empaqueta por característica, no por capa técnica. modules/orders/ es dueño de los pedidos de principio a fin; evita las carpetas globales controllers/ y services/ que ocultan la propiedad.
• Dibuja los límites de los módulos antes de dibujar las cajas de los microservicios. Las exportaciones limpias de index.ts son más baratas que el YAML de Kubernetes.
• Prefiere la extracción por estrangulamiento a las reescrituras de gran impacto. Mueve una capacidad detrás de un adaptador HTTP o de eventos; mantén las transacciones en el monolito hasta que la propiedad de los datos sea clara.
• Mide las métricas DORA antes de dividir. La frecuencia de despliegue, el tiempo de entrega y la tasa de fallos de cambio te dicen si la arquitectura es el cuello de botella.

B - Dirección de Dependencias

• Las capas de dominio y aplicación no importan Express, Fastify, decoradores de Nest ni clientes ORM. El código del framework permanece en infrastructure/.
• Las importaciones entre módulos pasan solo por el index.ts público. Prohíbe las importaciones profundas en infrastructure/ pares con ESLint o dependency-cruiser en CI.
• Usa puertos para todo lo que vayas a simular en pruebas o intercambiar en producción. Los repositorios, gateways, relojes y generadores de ID son puertos.
• Mantén la raíz de composición delgada. main.ts conecta adaptadores; no contiene reglas de negocio.
• Evita las dependencias circulares entre módulos. Rompe los ciclos con eventos o invirtiendo las dependencias a través de interfaces.

C - Datos y Consistencia

• Asigna un módulo propietario por tabla o agregado. Otros módulos llaman a APIs o eventos, no a modelos Prisma compartidos.
• Documenta explícitamente los límites de las transacciones. Conoce qué casos de uso requieren ACID y cuáles toleran la consistencia eventual.
• Planifica la bandeja de salida o los consumidores idempotentes antes de las transferencias asíncronas. La entrega al menos una vez es el valor predeterminado en los workers distribuidos de Node.
• No compartas bases de datos escribibles entre futuros servicios. Un esquema por módulo dentro de un monolito ensaya la extracción.
• Versiona las cargas útiles de eventos y API. Incluye campos schemaVersion; los consumidores deben ignorar las versiones desconocidas de forma segura.

D - Operaciones y Observabilidad

• Envía trazas de OpenTelemetry antes del servicio #2. No puedes depurar lo que no puedes ver a través de las llamadas HTTP.
• Registros estructurados con requestId en cada línea. pino o equivalente; no console.log no estructurados en rutas de producción.
• Separa las sondas de actividad y de preparación. La sonda de preparación verifica Postgres/Redis; la de actividad se mantiene ligera para los despliegues de kube.
• Implementa el apagado elegante en SIGTERM. Drena el servidor HTTP y cierra los pools de la base de datos antes de salir.
• Define SLOs por recorrido crítico del usuario. El p95 de la compra de pedidos importa más que el promedio de CPU en todos los pods.

E - Decisiones y Gobernanza

• Escribe ADRs para monolito vs servicios, elección de framework y bifurcaciones de almacenamiento de datos. Incluye los negativos y una fecha de activación de revisión.
• Sustituye los ADRs en lugar de eliminarlos. Los futuros ingenieros necesitan el historial de por qué cambiaste de rumbo.
• Alinea los módulos con la propiedad del equipo (Ley de Conway). Si dos equipos poseen un módulo, espera la erosión de los límites.
• Realiza revisiones de arquitectura cuando superes los 10 ingenieros o 3 equipos en un mismo repositorio. Los límites se difuminan sin una aplicación explícita.
• Rechaza las diapositivas que digan "microservicios para escalar" sin datos de RPS y de equipo. La evidencia vence a la moda.

F - Idoneidad del Entorno de Ejecución de Node.js

• Perfiliza el bucle de eventos antes de escalar horizontalmente. El JSON síncrono en rutas críticas no se soluciona solo con más pods.
• Descarga el trabajo intensivo en CPU a hilos de worker o colas de trabajo. Mantén los procesos HTTP orientados a E/S.
• Fija Node LTS en engines y CI. Node 24.18.0 LTS Activo; prueba las actualizaciones en una versión dedicada.
• Estandariza un framework HTTP por desplegable. Express 5 o Fastify 5 o Nest 11, no los tres en un mismo proceso.
• Tipifica los límites con TypeScript 5.6+ en modo estricto. Los tipos DTO compartidos son un vector de acoplamiento; versiona intencionalmente.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Arquitectura - ejemplos introductorios
• Monolito Modular - implementación de límites
• ADR: Monolito vs Servicios - plantilla de decisión
• Lista de Verificación de Refactorización - auditoría previa a la refactorización
• Microservicios Cuando Vale la Pena - cuándo dividir

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.