04 - Monolito modular

En un monolito, todas las capacidades de la aplicación forman parte de un mismo sistema. A medida que crece, el código de catálogo, pedidos, usuarios o envíos puede quedar repartido por paquetes compartidos. Las dependencias entre esas capacidades se vuelven difíciles de reconocer y controlar, y un cambio en una parte puede tener efectos poco evidentes en otra.

El problema no es que la aplicación se construya y despliegue como una unidad, sino que el código no tenga límites claros entre sus capacidades.

Una forma de abordar este problema es organizar el monolito en módulos de negocio. La aplicación sigue teniendo un único despliegue, pero cada módulo reúne el código de una capacidad concreta y limita cómo pueden utilizarla los demás.

La estructura que se propone aquí es una opción entre varias arquitecturas válidas, no una receta universal. Cada módulo expone una API pública y sus DTO; su implementación queda dentro de internal, organizada con las capas existentes.

Aplicación (un despliegue)catalogordersshippingAPI públicaCatalogModuleDTO públicoscatalog.dtoCapas internascatalog.internalMódulo de pedidosMódulo de envíoscontratodelegausa la API públicasolicita una operación

En una tienda, módulos como catalog, orders, users y shipping agrupan capacidades de negocio. Cada módulo ofrece a los demás una API pública y los DTO que forman parte de ese contrato; el resto de su código queda dentro de internal.

En el catálogo, CatalogModule es la API pública. Su implementación, CatalogModuleImpl, vive en internal.application y delega en CatalogService, que forma parte de la implementación interna. Así, otro módulo depende del contrato del catálogo, no de esa clase de implementación ni de su servicio.

comexamplestorecatalogdtointernalordersAPI públicaCatalogModuleBookSummaryapplicationCatalogModuleImplcontrollerCatalogControllerdomainCatalogServicedomainCatalogRepositorypersistenceCatalogRepositoryImplCódigo consumidorexpone en el contratodelegallamainvocausaimplementausa la API pública

La estructura de un sistema expresa sus límites, pero no siempre los hace cumplir. Para comprobar que las dependencias respetan esos límites, se pueden ejecutar tests de arquitectura que verifiquen automáticamente cómo se relacionan los módulos.

En este ejemplo con Java, que una clase esté en un paquete llamado internal no la hace inaccesible: si es pública, otras clases pueden usarla. Podemos expresar con ArchUnit una regla que prohíba a las clases ajenas a catalog depender de catalog.internal:

@ArchTest
static final ArchRule outside_catalog_must_not_use_internal =
    noClasses()
        .that().resideOutsideOfPackage("..catalog..")
        .should().dependOnClassesThat()
        .resideInAPackage("..catalog.internal..");

Al ejecutar el test, ArchUnit comprueba las dependencias y detecta las que incumplen la regla. Si encuentra alguna, el test falla; no impide por sí mismo que se escriba la importación ni que se compile el código.

Con la arquitectura actual hay dos entradas que llegan a servicios internos. La API pública del módulo sigue la ruta CatalogModule → CatalogModuleImpl → CatalogService. Por otro lado, una petición HTTP llega por CatalogController → CatalogService.

Esta separación importa cuando una operación depende de quién la solicita. Por ejemplo, crear un libro puede requerir que la persona usuaria sea administradora, mientras que consultar su carrito requiere que el usuario esté logueado. Si estas comprobaciones se hacen en el controlador, quedan mezcladas con HTTP y habrá que repetirlas cuando existan más controladores o entradas. Si se aplican indiscriminadamente en el servicio interno, una llamada legítima desde otro módulo puede evaluarse con una identidad o un contexto que no corresponden. Por ejemplo, el módulo de envíos puede solicitar cancelar un pedido sin actuar como la persona dueña de ese pedido.

Las políticas de acceso de la persona usuaria dependen de quién inicia ese flujo. En cambio, las reglas e invariantes del servicio deben cumplirse siempre, venga la llamada de una persona usuaria o de otro módulo.

Para separar ambas responsabilidades, se añade la capa usecase entre el controlador y el servicio. El caso de uso coordina el flujo iniciado por una persona usuaria y comprueba las condiciones específicas de ese flujo antes de llamar al servicio. La entrada entre módulos permanece igual: CatalogModule → CatalogModuleImpl → CatalogService. Un módulo no pasa por un caso de uso de usuario.

Persona usuariaCatalogControllerCatalogUseCaseCatalogServiceM.dulo consumidorCatalogModuleCatalogModuleImplPersona usuariaCatalogControllerCatalogUseCaseCatalogServiceMódulo consumidorCatalogModuleCatalogModuleImplPetición HTTPpetición HTTPejecutar caso de usocomprobar autorizaciónejecutar operaciónLlamada de otro móduloinvocar operacióndelegar operaciónejecutar operación

Los casos de uso representan flujos de entrada, no operaciones reutilizables para otros flujos. Si un caso de uso llamara a otro, acoplaría ambos flujos y podría arrastrar las decisiones de acceso propias del caso invocado. Cuando varios flujos necesitan la misma operación, la comparten mediante el servicio. Por el mismo motivo, una llamada entre módulos utiliza la API pública —CatalogModule → CatalogModuleImpl → CatalogService— y no un caso de uso de usuario. ArchUnit también puede comprobar que los casos de uso no se invoquen entre sí y que CatalogModule no dependa de ellos.

Cada módulo mantiene sus modelos de dominio en su paquete internal. Las reglas de arquitectura impiden que otros módulos dependan de ese paquete; por tanto, esos modelos son privados para el módulo que los contiene.

Por ejemplo, Order pertenece a orders.internal. Si tuviera un campo de tipo User, necesitaría importar users.internal.User y dependería de un modelo interno de otro módulo, lo que violaría el límite entre ambos. Del mismo modo, OrderDetail no puede tener un campo de tipo Product de catalog.internal.

Por eso, los pedidos guardan identificadores en lugar de referencias a esos objetos:

  1. Order almacena userId: UUID.
  2. OrderDetail almacena productId: UUID.

El tipo del identificador tampoco debe importar clases de users.internal ni de catalog.internal. En este ejemplo se usa UUID, pero también podría emplearse un tipo definido localmente en el módulo consumidor o incluido en un contrato público, si se decide exponerlo. Si hace falta consultar más datos del usuario o del producto, se utiliza la API pública del módulo propietario.

ordersinternalusersinternalcataloginternalOrderuserId: UUIDOrderDetailproductId: UUIDUserProduct

Spring Modulith es una biblioteca del ecosistema Spring que deriva un modelo modular a partir de los paquetes de la aplicación. Ayuda a documentar ese modelo y a verificar que se respeta, pero no decide la arquitectura por el equipo.

Por defecto, los paquetes hijos directos del paquete base de la aplicación se detectan como módulos. Por ejemplo, si la aplicación parte de com.example.store, com.example.store.catalog y com.example.store.orders se consideran módulos.

El paquete raíz de cada módulo constituye su API pública. Sus subpaquetes son internos, salvo que se expongan explícitamente. Para hacer público el subpaquete catalog.dto, se puede añadir un package-info.java:

@org.springframework.modulith.NamedInterface("dto")
package com.example.store.catalog.dto;

Después, el paquete raíz del módulo puede declarar las dependencias permitidas mediante @ApplicationModule. Por ejemplo, orders puede depender de la interfaz dto de catalog:

@org.springframework.modulith.ApplicationModule(
    allowedDependencies = "catalog::dto"
)
package com.example.store.orders;

La verificación se añade como un test JUnit dentro del código de pruebas, no en el código de producción. Si la clase principal Application está en el paquete com.example.store, el archivo puede ubicarse en:

src/test/java/com/example/store/ApplicationModulesTest.java

El test puede contener:

package com.example.store;
 
import org.junit.jupiter.api.Test;
import org.springframework.modulith.core.ApplicationModules;
 
class ApplicationModulesTest {
 
    @Test
    void verifiesModuleStructure() {
        ApplicationModules.of(Application.class).verify();
    }
}

No hace falta arrancar el contexto de Spring: la prueba analiza la estructura de paquetes y sus dependencias.

Esta comprobación detecta ciclos entre módulos, accesos a paquetes internos y dependencias que no estén permitidas. Spring Modulith usa por debajo el análisis de dependencias de ArchUnit. Es una verificación automatizada del modelo modular, no una protección en tiempo de compilación.

ArchUnit sigue siendo útil para definir reglas más específicas dentro de un módulo, por ejemplo, exigir que las dependencias sigan el flujo Controller → UseCase → Service. Modulith también ofrece facilidades para documentar la estructura y probar módulos por separado, pero no sustituye todas las reglas de ArchUnit.

Los DTO también se pueden colocar directamente en el paquete raíz del módulo; allí son públicos por defecto y no hace falta usar @NamedInterface ni crear package-info.java para exponerlos. Aun así, package-info.java puede utilizarse para declarar @ApplicationModule y sus dependencias permitidas.

El monolito modular mantiene un único despliegue, pero organiza el código en módulos de negocio con límites explícitos y verificables.

Dimensión Organización por capas Monolito modular
Despliegue Una aplicación Sigue siendo una aplicación y un único despliegue
Organización Las capas organizan por responsabilidad técnica, no por capacidad de negocio Conserva las capas dentro de cada módulo de negocio
Colaboración entre módulos La estructura no define límites explícitos entre capacidades de negocio Los módulos se relacionan mediante API pública y DTO
Entradas Los flujos de entrada llegan a los servicios Separa Controller → UseCase → Service de Module → ModuleImpl → Service
Modelos Puede haber referencias directas entre modelos de distintas capacidades Los modelos de otros módulos se relacionan mediante IDs
Verificación La estructura depende principalmente de convenciones ArchUnit y Spring Modulith ayudan a verificar los límites entre módulos
  • clase/daw/dws/modulith.txt
  • Última modificación: 2026/11/07 12:23
  • por cesguiro