Spring Modulith: módulos con fronteras verificadas en un monolito Spring Boot

• Un módulo es, por defecto, cada subpaquete directo del paquete donde está tu clase @SpringBootApplication. No hay descriptores ni plugins.
• La API de un módulo son los tipos públicos de la raíz de su paquete. Lo que cuelga de sus subpaquetes es interno.
• @NamedInterface publica a propósito un subpaquete concreto, ampliando esa API.
• ApplicationModules.verify() convierte esas reglas en un test: falla si un módulo usa tipos internos de otro o si hay ciclos entre módulos.
• Documenter genera diagramas C4 y fichas por módulo a partir del mismo modelo que se verifica.
• Todo vive en un solo despliegue: sigues teniendo un monolito, pero con fronteras que se pueden comprobar.

• Qué es Spring Modulith y qué no es
• Spring Modulith vs microservicios
• Qué es un módulo
• API pública, internal y @NamedInterface
• Caso real: el ciclo que obligó a partir un módulo
• ApplicationModules.verify()
• Romper una frontera a propósito
• Documenter y sus límites
• Cuándo utilizar Spring Modulith

En Java, una clase public se puede importar desde cualquier paquete del classpath. El compilador no distingue entre «esta clase es la API de pedidos» y «esta clase es un detalle de implementación que nadie debería tocar». Esa distinción vive en la cabeza del equipo, en una página de la wiki o en un comentario de la code review.

Y lo que solo vive en la cabeza del equipo se erosiona: por plazos, por gente nueva, por un «lo arreglo luego» que nunca llega. El resultado es el monolito en el que todo depende de todo.

La respuesta habitual ha sido saltar a microservicios: si los módulos están en procesos distintos, no pueden importarse clases. Funciona, pero el aislamiento se paga con red, latencia, despliegues múltiples y N proyectos que mantener.

Spring Modulith es un proyecto de Spring para diseñar y verificar aplicaciones Spring Boot como monolitos modulares: un único despliegue dividido en módulos con APIs explícitas y dependencias verificables.

No es un framework de microservicios, ni OSGi, ni un sistema de plugins, ni un mecanismo de aislamiento de procesos, ni un modelo de despliegue nuevo. Tus módulos siguen siendo paquetes Java dentro de la misma JVM, con los mismos beans de Spring. Lo que añade Spring Modulith es:

• Un modelo de tu aplicación: qué módulos hay, qué expone cada uno y de quién depende.
• Verificación de ese modelo en un test.
• Documentación generada desde ese modelo.
• Comunicación por eventos fiable entre módulos, tema del siguiente artículo de la serie.

Solemos mezclar dos decisiones: cómo organizas el dominio y cómo lo despliegas. Spring Modulith actúa sobre la primera y deja intacta la segunda.

Modularidad y distribución son decisiones diferentes. Primero se ponen fronteras sólidas dentro del monolito; si un módulo crece tanto que justifica un despliegue propio, ya tiene trazada la frontera, que es la parte difícil de sacarlo. Spring Modulith no sustituye a los microservicios: hace que la decisión de distribuir se tome cuando de verdad hace falta.

Para que todo sea concreto, el repositorio implementa una tienda mínima. En el tag blog-1-modulos tiene tres módulos de negocio y uno transversal:

catalog: qué se vende y a qué precio.

inventory: cuántas unidades hay en el almacén.

order: los pedidos. Para crear uno necesita el nombre y el precio de cada producto, así que consulta a catalog.

shared: configuración transversal, como un Clock y el manejador global de errores.

No hay frontend ni pagos: solo lo justo. La serie avanza por tags del mismo repositorio: módulos y fronteras (este artículo), eventos y fiabilidad, externalización con Kafka y, por último, Spring AI como un módulo más.

Lo primero que sorprende de Spring Modulith es lo poco exótico que es. Este es el árbol real del proyecto en el tag blog-1-modulos:

Ver en texto · Estructura de paquetes en el tag blog-1-modulos

com.datiacode.shop
├── ShopApplication.java                 ← @SpringBootApplication
├── catalog
│   ├── CatalogService.java              ← API pública
│   ├── model                            ← interfaz con nombre catalog::model
│   │   ├── ProductInfo.java
│   │   └── package-info.java            ← @NamedInterface("model")
│   └── internal
│       ├── DefaultCatalogService.java
│       ├── Product.java
│       └── ProductRepository.java
├── inventory
│   ├── InventoryService.java            ← API pública
│   └── internal
│       ├── DefaultInventoryService.java
│       ├── StockItem.java
│       └── StockItemRepository.java
├── order
│   ├── OrderService.java                ← API pública
│   ├── NewOrder.java, OrderDetails.java, OrderCompleted.java
│   ├── UnknownProductException.java, OrderNotFoundException.java
│   └── internal
│       ├── DefaultOrderService.java
│       ├── OrderController.java         ← controlador REST
│       ├── Order.java, OrderRepository.java, OrderLine.java, OrderStatus.java
│       └── CreateOrderRequest.java, OrderResponse.java, OrderExceptionHandler.java
└── shared
    ├── config
    │   └── ClockConfig.java
    └── web
        └── GlobalExceptionHandler.java

La regla por defecto admite variantes que describe la documentación de fundamentos: considerar módulos solo los paquetes anotados con @ApplicationModule, añadir paquetes raíz con @Modulithic o declarar módulos anidados. Este proyecto usa la detección por defecto. Y un detalle del árbol: el controlador REST vive en order.internal. La API de un módulo no es su API REST: es lo que otros módulos pueden usar desde Java.

La API modular define qué tipos Java puede usar otro módulo. Por defecto, Spring Modulith considera API de un módulo los tipos públicos que están en la raíz de su paquete; los subpaquetes son internos y el código de otros módulos no debe referenciarlos.

El nombre internal es una convención, no una palabra reservada: cualquier subpaquete es interno salvo que se publique. Usarlo hace evidente la intención al abrir el proyecto.

package com.datiacode.shop.catalog;

/**
 * Public API of the catalog module: what is sold and at which price.
 */
public interface CatalogService {

	Optional<ProductInfo> findProduct(String sku);
}

ProductInfo vive en catalog.model, un subpaquete. Por la regla anterior sería interno y order no podría usarlo. Para publicarlo hay que declararlo explícitamente con @NamedInterface en el package-info.java del paquete.

Con eso, catalog expone dos interfaces: la raíz, que Spring Modulith llama interfaz sin nombre (<<UNNAMED>>), y la interfaz con nombre model. Desde fuera se refieren como catalog y catalog::model, y el resumen del módulo que genera el propio Spring Modulith lo confirma:

/**
 * Read-only product data that the catalog module shares with other modules.
 * <p>
 * Exposed as the named interface {@code catalog::model}: a sub-package that would otherwise be internal to the
 * module.
 */
@org.springframework.modulith.NamedInterface("model")
package com.datiacode.shop.catalog.model;

package com.datiacode.shop.catalog.model;

public record ProductInfo(String sku, String name, BigDecimal unitPrice) {
}

# Catalog
> Logical name: catalog
> Base package: com.datiacode.shop.catalog
> Excluded packages: none
> Named interfaces:
  + NamedInterface: name=<<UNNAMED>>, types=[ c.d.s.c.CatalogService ]
  + NamedInterface: name=model, types=[ c.d.s.c.m.ProductInfo ]
> Spring beans:
  o ….internal.DefaultCatalogService
  o ….internal.ProductRepository

Como todos los módulos viven en la misma JVM, no hay HTTP entre ellos: se comunican por llamada directa o por evento, como resume la tabla.

En el proyecto, order llama directamente a catalog porque sin nombre y precio no puede guardar el pedido:

@Service
@Transactional
class DefaultOrderService implements OrderService {

	private final OrderRepository orders;
	private final CatalogService catalog;
	// ...

	private OrderLine toLine(NewOrder.Item item) {
		return catalog.findProduct(item.sku())
				.map(product -> new OrderLine(product.sku(), product.name(), item.quantity(), product.unitPrice()))
				.orElseThrow(() -> new UnknownProductException(item.sku()));
	}
}

DefaultOrderService es package-private y vive en order.internal. Lo que ve el resto de la aplicación es la interfaz OrderService.

El primer diseño del proyecto no tenía catalog. Había un único módulo inventory con productos, precios y stock, y order le preguntaba si había unidades antes de aceptar el pedido.

El problema apareció al planificar el siguiente paso: cuando se acepta un pedido, inventory tiene que descontar stock, así que escucha el evento OrderCompleted de order. Eso es una dependencia de inventory hacia order. Con la consulta de stock en sentido contrario, el resultado era un ciclo:

order ──(consulta stock)──▶ inventory
  ▲                            │
  └──(escucha OrderCompleted)──┘

• verify() rechaza los ciclos entre módulos: la documentación exige que las dependencias formen un grafo dirigido acíclico. Y con razón: dos módulos que dependen el uno del otro no se pueden entender, probar ni extraer por separado. Son un único módulo con dos nombres.
• La solución fue separar lo que se vende (catalog: nombre y precio) de lo que hay en el almacén (inventory: unidades). Ahora order depende de catalog e inventory de order, sin ciclo.
• El cambio está en el historial del repositorio, en el commit «separa catalog de inventory para evitar el ciclo con order».

Lo valioso es que la herramienta obligó a tomar la decisión de forma explícita, en lugar de dejar que el ciclo se instalara en silencio. Y el proyecto la fija en un test, como se ve más abajo.

Lo que convierte esas convenciones en reglas es este test:

class ModularityTest {

	static final ApplicationModules MODULES = ApplicationModules.of(ShopApplication.class);

	@Test
	void verifiesModularStructure() {
		MODULES.verify();
	}
}

• ApplicationModules.of(...) analiza las clases compiladas a partir del paquete de ShopApplication y construye el modelo de módulos.
• verify() valida ese modelo y lanza una excepción con todas las violaciones encontradas.
• No arranca el contexto de Spring ni necesita base de datos: se ejecuta como un test unitario más, con ./mvnw test en local y en cualquier pipeline de CI.
• Si alguien rompe una frontera, el build falla, igual que fallaría un test de negocio.

Son las reglas que enumera la documentación de verificación. Si jMolecules está en el classpath, verify() dispara además sus reglas de arquitectura; este proyecto no lo usa. En la ejecución con la que se preparó este artículo, los tres tests de ModularityTest tardaron 0,99 s; al repetirlos nosotros dentro de un contenedor Docker en un servidor compartido, entre 1,8 y 1,9 s. Es una medida de este proyecto de ejemplo, no una promesa: en una base de código grande el análisis tardará más.

No. Spring Modulith utiliza ArchUnit internamente para parte de la verificación estructural —ApplicationModules importa las clases con ArchUnit, que es dependencia de spring-modulith-core—, pero añade un modelo explícito de módulos, APIs y dependencias que reutiliza para documentar y para las funcionalidades de runtime.

ArchUnit sirve para escribir reglas de arquitectura generales sobre cualquier código Java; Spring Modulith construye además un modelo específico de los módulos de una aplicación Spring Boot. Pueden coexistir y complementarse: ArchUnit para reglas propias y verify() para las fronteras entre módulos.

El repositorio tiene una rama, demo/verify-roto, que hace exactamente lo que no se debe: un componente de order que usa el repositorio interno de catalog para ahorrarse la API.

package com.datiacode.shop.order.internal;

import org.springframework.stereotype.Component;

import com.datiacode.shop.catalog.internal.ProductRepository;

/**
 * DEMO ONLY: reaches into catalog's internals instead of using CatalogService.
 */
@Component
class StockShortcut {

	private final ProductRepository products;

	StockShortcut(ProductRepository products) {
		this.products = products;
	}

	long countProducts() {
		return products.count();
	}
}

[ERROR] Tests run: 3, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 1.891 s <<< FAILURE! -- in com.datiacode.shop.ModularityTest
[ERROR] com.datiacode.shop.ModularityTest.verifiesModularStructure -- Time elapsed: 0.077 s <<< ERROR!
org.springframework.modulith.core.Violations:
- Module 'order' depends on non-exposed type com.datiacode.shop.catalog.internal.ProductRepository within module 'catalog'!
StockShortcut declares constructor StockShortcut(ProductRepository) in (StockShortcut.java:0)
- Module 'order' depends on non-exposed type com.datiacode.shop.catalog.internal.ProductRepository within module 'catalog'!
Method <com.datiacode.shop.order.internal.StockShortcut.countProducts()> calls method <com.datiacode.shop.catalog.internal.ProductRepository.count()> in (StockShortcut.java:20)
- Module 'order' depends on non-exposed type com.datiacode.shop.catalog.internal.ProductRepository within module 'catalog'!
Field <com.datiacode.shop.order.internal.StockShortcut.products> has type <com.datiacode.shop.catalog.internal.ProductRepository> in (StockShortcut.java:0)
- Module 'order' depends on non-exposed type com.datiacode.shop.catalog.internal.ProductRepository within module 'catalog'!
Constructor <com.datiacode.shop.order.internal.StockShortcut.<init>(com.datiacode.shop.catalog.internal.ProductRepository)> has parameter of type <com.datiacode.shop.catalog.internal.ProductRepository> in (StockShortcut.java:0)
...
[INFO] BUILD FAILURE

El fallo no es conceptual: el build identifica el módulo, el tipo prohibido y cada punto de uso —el constructor, el campo, el parámetro y la llamada al método, con su línea—. No hace falta interpretar nada. La misma salida está guardada en el repositorio, en docs/verify-error.txt.

Hay un matiz en esa rama fácil de pasar por alto. En el proyecto, las clases de internal son package-private, así que Java ya impide la mayoría de los accesos ilegales en compilación, sin Spring Modulith. Para que el atajo compile, hubo que cambiar dos líneas en catalog:

-class Product {
+public class Product {

-interface ProductRepository extends JpaRepository<Product, Long> {
+public interface ProductRepository extends JpaRepository<Product, Long> {

• Clases internas que tienen que ser públicas porque las usa otro subpaquete del mismo módulo (internal.web usando internal.domain, por ejemplo).
• Proxies, mappers generados o frameworks que exigen visibilidad pública.
• Los ciclos, que la visibilidad de Java no detecta en absoluto.
• El cambio inocente de class a public class en un pull request, que es exactamente lo que muestra la rama.

verify() aplica las reglas generales. Pero el modelo que construye ApplicationModules también se puede consultar como un modelo de la arquitectura, y eso permite fijar decisiones de diseño concretas del proyecto.

@Test
void exposesCatalogModelAsNamedInterface() {
	var catalog = MODULES.getModuleByName("catalog").orElseThrow();

	assertThat(catalog.getNamedInterfaces().getByName("model")).isPresent();
}

@Test
void orderDoesNotDependOnInventory() {
	var order = MODULES.getModuleByName("order").orElseThrow();

	// "Pedidos ya no conoce a inventario": inventory listens to order's events, never the other way round
	assertThat(order.getAllDependencies(MODULES).containsModuleNamed("inventory")).isFalse();
}

El segundo test es la decisión del caso del ciclo convertida en una prueba ejecutable. Si dentro de un año alguien vuelve a hacer que order consulte a inventory, el test falla con un nombre que explica por qué no se debe.

La documentación de arquitectura tiene un problema conocido: a los tres meses deja de parecerse al código. Spring Modulith la genera a partir del mismo modelo que verifica, con el Documenter. El objetivo no es sustituir toda la documentación arquitectónica, sino evitar que la descripción estructural quede obsoleta respecto al código.

@Tag("documentation")
class DocumentationTest {

	@Test
	void writesModuleDocumentation() throws IOException {
		var modules = ApplicationModules.of(ShopApplication.class);

		new Documenter(modules, Options.defaults().withOutputFolder("docs/modules"))
				.writeDocumentation()
				.writeModulesAsPlantUml();

		// Canvases do not list named interfaces; the module description does
		var summary = modules.stream().map(Object::toString).collect(Collectors.joining(System.lineSeparator()));
		Files.writeString(Path.of("docs/modules/modules.txt"), summary);
	}
}

No conviene regenerar la documentación en cada ejecución de tests: ensuciaría el directorio de trabajo y alargaría el build. Por eso el test lleva @Tag("documentation"), el pom.xml lo excluye por defecto y un perfil de Maven lo activa:

<properties>
	<excludedGroups>documentation</excludedGroups>
</properties>

<profiles>
	<profile>
		<id>docs</id>
		<properties>
			<excludedGroups/>
			<groups>documentation</groups>
		</properties>
	</profile>
</profiles>

Con eso, ./mvnw test no lo ejecuta y ./mvnw test -Pdocs regenera la documentación. Encaja bien en un pipeline de release.

Este es el diagrama de componentes que genera el Documenter sobre el tag: no es una ilustración, es la salida tal cual.

La documentación generada es fiable en lo que muestra, pero no lo muestra todo. Probándolo sobre este proyecto con Spring Modulith 2.1.1 y las opciones por defecto, encontramos tres huecos; contrastados con la documentación oficial y con la propia librería, los tres tienen explicación.

• Lo primero es un valor por defecto del diagrama, no un límite. En la 2.1.1, las DiagramOptions que recibe writeModulesAsPlantUml admiten withElementsWithoutRelationships con el valor VISIBLE, y con esa opción, sobre este mismo tag, inventory y shared aparecen. El tag no lo usa: lo comprobamos aparte para este artículo.
• Lo segundo coincide con la documentación: entre las secciones que enumera para el canvas no figuran las named interfaces.
• Lo tercero también tiene explicación oficial: el canvas solo lista como publicados los eventos marcados con @DomainEvent de jMolecules o que implementan su interfaz DomainEvent. OrderCompleted es un record sin esas marcas, así que no aparece.

Nada de esto invalida la herramienta. Pero si alguien usa el diagrama para decidir qué módulos existen, conviene que sepa que, con las opciones por defecto, faltan dos.

La aplicación puede exponer el mismo modelo en /actuator/modulith, en JSON, para inspeccionar en runtime el modelo modular que Spring Modulith ha detectado sin abrir el código. Hacen falta tres piezas: la dependencia spring-modulith-actuator, Spring Boot Actuator —normalmente con spring-boot-starter-actuator— y la exposición del endpoint. El proyecto tiene las tres: ambas dependencias en el pom.xml y management.endpoints.web.exposure.include=health,info,modulith.

{
    "catalog": {
        "displayName": "Catalog",
        "basePackage": "com.datiacode.shop.catalog",
        "nested": [],
        "type": "closed",
        "shared": false,
        "dependencies": []
    },
    "order": {
        "displayName": "Order",
        "basePackage": "com.datiacode.shop.order",
        "nested": [],
        "type": "closed",
        "shared": false,
        "dependencies": [
            {
                "target": "catalog",
                "types": [
                    "USES_COMPONENT"
                ]
            }
        ]
    }
}

La respuesta completa lista los cuatro módulos, también inventory y shared, que el diagrama por defecto omite; no incluye las named interfaces. El formato está descrito en la documentación de funcionalidades de producción. Como cualquier endpoint de Actuator, /actuator/modulith solo estará disponible si Spring Boot Actuator está incluido y el endpoint se ha expuesto mediante la configuración correspondiente, y exponerlo es una decisión que conviene tomar con criterio.

Tiene sentido especialmente cuando hay un monolito Spring Boot con varios dominios, varios desarrolladores o equipos, riesgo real de acoplamiento o la posibilidad de extraer algún módulo en el futuro.

Probablemente aporta menos cuando la aplicación es pequeña y de un solo dominio, cuando necesitas aislamiento real de procesos —todos los módulos comparten JVM— o cuando ya operas servicios bien delimitados y el problema está en otro sitio.

Adoptarlo en un proyecto existente es incremental:

La primera ejecución suele ser el mejor diagnóstico del estado real de la arquitectura.