El Modelo Mental de Arquitectura para Servicios Node.js

La arquitectura, despojada de diagramas y nombres de frameworks, es simplemente el conjunto de decisiones en un sistema que son costosas de revertir. Dónde se ubican los límites de los módulos, en qué dirección apuntan las dependencias, si dos características comparten una tabla de base de datos, estas decisiones perduran más que cualquier función o ruta individual, y equivocarse en ellas no se manifiesta como un error, sino que aparece meses después como "¿por qué cada cambio en esta base de código tarda tres veces más de lo que debería?".

Conceptos básicos de arquitectura y diseño pone en marcha un monolito modular con código funcional; Monolito Modular, Arquitectura Hexagonal en Node y Microservicios Cuando Vale la Pena cubren cada uno un estilo específico en profundidad. Esta página es la capa subyacente a todos ellos: qué hace que un sistema sea fácil o difícil de cambiar, para que los estilos se lean como puntos en un espectro real en lugar de tendencias en competencia para elegir por preferencia.

Resumen

• La arquitectura es la estructura duradera de un sistema (sus límites y direcciones de dependencia), evaluada por una pregunta práctica: ¿cuán costoso es cambiar una parte sin romper, o incluso comprender, el resto?
• Por qué es importante: Una mala arquitectura no falla ruidosamente como un error, sino que se acumula silenciosamente como una entrega más lenta, hasta que un equipo se da cuenta de que cada característica ahora toca cinco archivos no relacionados.
• Conceptos clave: acoplamiento, cohesión, límite, dirección de dependencia, inversión de dependencia, coste del cambio.
• Cuándo usarlo: Al elegir dónde debe ir un límite de módulo, decidir si una dependencia pertenece a tu código de dominio o solo a tu infraestructura, evaluar si una división propuesta (servicio, capa, módulo) está resolviendo un problema real, o escribir un ADR que debe sobrevivir a la partida de la persona que lo escribió.
• Limitaciones / Compromisos: Cada elección arquitectónica que reduce el acoplamiento añade indirección en algún otro lugar (interfaces, puertos, saltos adicionales), y esa indirección tiene un coste real en el código que tienes que leer para entender lo que realmente sucede.
• Temas relacionados: monolitos modulares, arquitectura hexagonal (puertos y adaptadores), límites de microservicios, registros de decisiones de arquitectura.

Fundamentos

Dos propiedades determinan casi todo sobre si una base de código sigue siendo fácil de cambiar: el acoplamiento y la cohesión. El acoplamiento es cuánto una parte de un sistema conoce o depende de los internos de otra parte; dos módulos están fuertemente acoplados si cambiar uno fuerza rutinariamente un cambio en el otro, incluso cuando la capacidad de negocio subyacente no cambió. La cohesión es cuánto las cosas dentro de una parte realmente pertenecen juntas; un módulo es altamente cohesivo si todo en él existe para servir una responsabilidad clara, y de baja cohesión si es un revoltijo de lógica no relacionada que terminó en el mismo archivo.

El objetivo que persigue la arquitectura es simple de enunciar y difícil de lograr: alta cohesión dentro de un límite, bajo acoplamiento entre límites. Un límite es cualquier línea que dibujas y haces cumplir (una carpeta, la API pública de un módulo, una llamada de red entre servicios) más allá de la cual el resto del sistema solo puede interactuar a través de una superficie explícita y estrecha en lugar de acceder directamente a los internos.

Una analogía útil: piensa en un sistema bien arquitectado como un edificio con muros de carga en los lugares correctos. Puedes renovar una cocina sin que se caiga el dormitorio, porque el muro entre ellos es un límite real, no una sugerencia. Un sistema mal arquitectado es el equivalente a que los muebles de cada habitación también funcionen como soporte estructural para la habitación de al lado; un solo cambio en cualquier lugar corre el riesgo de un colapso en todas partes.

// Acoplamiento fuerte: la función de dominio accede directamente a la infraestructura
import { pool } from "../db/pool"; // el dominio ahora depende de la existencia de Postgres
 
export function createOrder(input: OrderInput) {
  return pool.query("INSERT INTO orders ...", [input]); // no se puede probar sin una base de datos real
}

Mecánica e Interacciones

La dirección de la dependencia es donde esto deja de ser una preferencia abstracta y comienza a ser una regla concreta y verificable. Cada declaración de importación es una flecha de dependencia, y la dirección en que apuntan esas flechas determina qué partes de un sistema pueden cambiar independientemente de otras. Si tu lógica de dominio importa tipos de Express o un cliente de Prisma directamente, entonces la lógica de dominio ahora depende de esas elecciones; intercambiar frameworks u ORMs significa tocar reglas de negocio, no solo código de infraestructura.

La inversión de dependencia es la técnica específica que rompe esto: en lugar de que el dominio dependa de una implementación de infraestructura concreta, el dominio define una interfaz (un puerto) que describe lo que necesita, y el código de infraestructura (un adaptador) implementa esa interfaz para satisfacerlo. La flecha de dependencia ahora apunta hacia el dominio, no lejos de él; la infraestructura conoce el puerto del dominio, pero el dominio no sabe nada sobre Postgres, Express o Redis. Arquitectura Hexagonal en Node es exactamente este patrón, sistematizado con un diseño de carpetas concreto.

// El dominio define lo que necesita: un puerto, no un cliente de base de datos
export interface OrderRepository {
  save(order: Order): Promise<void>;
}
 
// createOrder depende del puerto, nunca de Postgres, Prisma o pg directamente
export function createOrder(input: OrderInput, repo: OrderRepository) {
  const order = { id: crypto.randomUUID(), ...input };
  return repo.save(order); // la infraestructura cumple este contrato más tarde
}

Esta es la razón por la que "cambiar Express por Fastify" o "probar sin una base de datos real" se vuelve barato en un sistema bien delimitado y costoso en uno fuertemente acoplado: el código de dominio en la versión invertida nunca mencionó la tecnología concreta en primer lugar, por lo que reemplazarla solo toca el adaptador, nunca la lógica que realmente codifica las reglas de negocio.

Los límites también interactúan con la estructura del equipo de una manera que es fácil de subestimar. El límite de un módulo no es solo una costura técnica, sino que generalmente también es una costura de propiedad. Cuando la API pública de un módulo es estrecha y se aplica (a través de exportaciones de index.ts, restricciones de importación de ESLint o un límite de red real), un equipo puede cambiar los internos de ese módulo sin coordinarse con todos los demás equipos que tocan la base de código. Los límites débiles fuerzan la coordinación incluso cuando las capacidades de negocio subyacentes no dependen realmente entre sí, lo que a menudo es el coste real y palpable de "esta base de código es difícil de trabajar a medida que hemos crecido".

Consideraciones y Aplicaciones Avanzadas

Los estilos arquitectónicos cubiertos en otras partes de esta sección (monolito en capas, monolito modular, hexagonal, microservicios) no son realmente filosofías diferentes que compiten por la respuesta "correcta". Son el mismo objetivo de acoplamiento/cohesión perseguido con diferentes grados de aplicación y diferentes costes operativos, y elegir entre ellos es un compromiso, no una escalera de madurez que todos deberían subir.

Un monolito en capas (carpetas globales controllers/, services/, models/) tiene límites solo por convención; nada impide que un controlador acceda directamente al modelo de otra característica, por lo que el acoplamiento se introduce a medida que la base de código crece a menos que se mantenga la disciplina. Un monolito modular mantiene un único desplegable pero aplica límites entre los módulos de características, típicamente a través de reglas de linting que bloquean las importaciones profundas; obtiene la mayoría de los beneficios de acoplamiento de los límites de servicio sin pagar por una red. La arquitectura hexagonal añade un segundo eje de límite, entre la lógica de dominio y cualquier infraestructura, independientemente del módulo, por lo que se compone naturalmente dentro de los módulos de un monolito modular en lugar de reemplazar la idea. Los microservicios convierten el límite del módulo en un límite de red genuino, aplicado por el sistema operativo y el protocolo de cable en lugar de un linter, que es la aplicación más fuerte posible, y también la más costosa, intercambiando llamadas a funciones en proceso por modos de fallo distribuidos, consistencia eventual y una superficie operativa mucho mayor.

Esa progresión se mapea directamente al coste del cambio, la lente práctica para evaluar cualquiera de estas opciones: cada paso hacia límites más fuertes reduce el coste de cambiar una parte de forma aislada y aumenta el coste de cambiar algo que legítimamente abarca dos partes, además del coste operativo fijo del propio mecanismo de límite. Un equipo que aún no ha sentido un dolor de acoplamiento real suele pagar una sobrecarga pura por una subestrategia de límites más fuerte de lo que necesita; un equipo que se ahoga en roturas entre módulos suele pagar una sobrecarga pura al dejar los límites solo por convención. Microservicios Cuando Vale la Pena y ADR: Monolito vs Servicios profundizan en la localización de ese punto de inflexión para un equipo específico.

Debido a que estas decisiones son costosas de revertir y se toman bajo una incertidumbre real, registrar el razonamiento en el momento de la decisión, no solo el resultado, importa más aquí que en casi cualquier otro lugar de una base de código. Un Registro de Decisiones de Arquitectura existe específicamente porque "por qué elegimos esto" es exactamente la información que se evapora más rápido de la memoria colectiva de un equipo, y volver a litigar un compromiso establecido sin conocer el contexto original desperdicia el esfuerzo exacto que la decisión original debía ahorrar.

Errores comunes

• "Arquitectura significa elegir una forma de diagrama de antemano." La arquitectura es un conjunto continuo de decisiones de límites y dependencias, la mayoría de las cuales se revisan a medida que aparece el dolor real del acoplamiento, no un ejercicio de diagrama único terminado antes de escribir código.
• "Más capas o más servicios es automáticamente una mejor estructura." Cada límite adicional tiene un coste real: más indirección para leer o más superficie de red para operar. Los límites solo se amortizan cuando realmente resuelven el dolor de acoplamiento que siente el equipo.
• "Los microservicios son la versión madura de un monolito." Son un punto diferente en la misma curva de compromiso, no una mejora; un monolito modular puede estar significativamente mejor arquitectado, en el sentido de acoplamiento/cohesión, que un conjunto de microservicios mal delimitados.
• "Si está dividido en archivos y carpetas, tiene límites." Una carpeta es un límite solo si algo lo impone; sin una regla de lint, una API pública explícita o un salto de red, nada impide que el código lo atraviese, y lo hará, bajo la presión de los plazos.
• "La inversión de dependencia es una sobreingeniería para la mayoría de los proyectos de Node." Es excesivo para un script desechable, pero para la lógica de dominio que vale la pena proteger de la rotación del framework o la base de datos, la interfaz "extra" es lo que hace que las pruebas y futuras migraciones sean baratas en lugar de una reescritura.

Preguntas frecuentes

Relacionado

• Conceptos básicos de arquitectura y diseño - ejemplos prácticos de monolito modular y capas
• Monolito Modular - límites de módulo aplicados dentro de un único desplegable
• Arquitectura Hexagonal en Node - inversión de dependencia con puertos y adaptadores
• Microservicios Cuando Vale la Pena - cuándo un límite de red realmente se amortiza
• ADR: Monolito vs Servicios - registro del razonamiento detrás de una decisión costosa de revertir
• Mejores prácticas de arquitectura - reglas operativas que se derivan de este modelo

Versiones de la pila: Esta página es conceptual y no está ligada a una versión específica de la pila.