Monolito modular vs Vertical Slice: diferencias y cuándo elegir

La escena se repite con una regularidad sospechosa. Una plataforma de comercio electrónico arrancó con cuatro entidades y dos desarrolladores. Tres años después hay catorce personas, el dominio cubre clientes, catálogo, pedidos y facturación, y un cambio en el cálculo de impuestos de una factura obliga a tocar siete ficheros repartidos entre cuatro paquetes. Ninguno de esos paquetes se llama facturación.

Cuando eso pasa, la propuesta que aparece en la reunión suele ser la misma: dividir en microservicios. Es una respuesta cara a una pregunta que todavía no se ha formulado bien. Antes de repartir el sistema en artefactos independientes hay una decisión más barata, más reversible y casi siempre más rentable: ¿alrededor de qué organizamos el código?

Conviene separar dos cosas que se mezclan constantemente. Una es cómo se despliega el sistema: un artefacto o varios. Otra es cómo se organiza el código dentro de ese artefacto. El monolito modular y Vertical Slice son respuestas a la segunda pregunta. Las dos conviven perfectamente con un único despliegue.

Tres formas de cortar el mismo sistema

El mismo código fuente admite al menos tres ejes de corte principales, y cada uno decide dónde cae un cambio.

• Monolito tradicional. El corte principal es la capa técnica: controller, service, repository, model. Todo el sistema comparte esos cuatro cajones, sin importar a qué parte del negocio pertenezca cada clase.
• Monolito modular. El corte principal es el módulo de negocio: clientes, catálogo, pedidos, facturación. Cada módulo tiene un límite explícito y publica un contrato; lo demás es interno y nadie de fuera lo toca.
• Organización Vertical Slice. El corte principal es el caso de uso: crear pedido, cancelar pedido, consultar pedido. Cada operación reúne en un mismo sitio todo lo que necesita para ejecutarse.

Que un eje sea el principal no elimina a los demás. Dentro de un módulo sigue habiendo capas, y dentro de un slice también. Lo que cambia es qué criterio manda en el primer nivel de la estructura de paquetes.

El problema del diagrama anterior no es que existan capas. Las capas separan responsabilidades reales y eso sigue siendo útil. El problema es que, cuando la capa es el criterio principal, el código que cambia junto vive separado y el código que no tiene relación acaba compartiendo la misma clase. Eso es acoplamiento accidental: no viene del dominio, viene del sitio donde hemos puesto los ficheros.

El resto del artículo responde a cuatro preguntas concretas: qué resuelve cada enfoque, en qué se diferencian de verdad, cuándo conviene cada uno y cómo se combinan. Porque se combinan, y esa es la parte que más veces se pierde en la discusión.

Un monolito modular es una aplicación que se despliega como un solo artefacto y cuyo corte principal es el dominio. En lugar de cuatro capas compartidas por todo el sistema, hay módulos de negocio: clientes, catálogo, pedidos y facturación en el ejemplo que venimos usando.

Qué pertenece a cada módulo

A un módulo pertenece todo lo necesario para sostener sus reglas: sus entidades, su lógica, su persistencia y sus puntos de entrada. El criterio para decidir dónde va algo no es qué tablas toca, sino quién decide cuándo cambia esa regla. Si la política de reintento de un cobro la fija el área financiera, vive en facturación aunque consulte datos de pedidos.

Es el mismo razonamiento que hay detrás de un contexto delimitado en Domain-Driven Design, aplicado al primer nivel de paquetes. Si el reparto en módulos no se parece al reparto de responsabilidades de la organización, los límites se van a romper solos.

El límite no es el paquete: es el contrato

Cada módulo expone una superficie deliberadamente pequeña —una o dos interfaces publicadas, y eventos de dominio cuando la relación es asíncrona— y mantiene todo lo demás como interno. Facturación no importa OrderEntity; recibe un evento OrderPlaced o llama a una operación del contrato de pedidos que devuelve un objeto propio de ese contrato.

Cuando ese límite no existe, pasa algo concreto y bastante difícil de revertir: una consulta JPQL lanzada desde facturación sobre la tabla de pedidos convierte el esquema interno de pedidos en API pública sin que el equipo de pedidos se entere. El día que renombren una columna romperán un código que no conocen, y lo descubrirán en producción.

Dependencias, ciclos y cómo se hacen cumplir

Un monolito modular necesita una regla de dependencia escrita: pedidos puede depender del contrato de catálogo, catálogo no puede depender de pedidos. En cuanto aparece un ciclo, los dos módulos implicados dejan de poder razonarse por separado, dejan de poder probarse por separado y dejan de poder extraerse por separado. Un ciclo no es un defecto de estilo: es la pérdida del único beneficio por el que se paga la estructura.

La regla que funciona en producción es sencilla de enunciar y exigente de aplicar: el límite tiene que romper el build. Una convención documentada en la wiki aguanta tres meses; una prueba de arquitectura con ArchUnit o la verificación de módulos de Spring Modulith aguanta mientras exista el proyecto. También sirven los módulos de Maven o el sistema de módulos de la plataforma Java, a cambio de una estructura de proyecto más rígida.

Una base de datos compartida no rompe la modularidad

Compartir una instancia de base de datos es perfectamente compatible con un monolito modular. Lo que importa no es cuántas bases de datos hay, sino la propiedad de los datos: cada tabla pertenece a un módulo y solo ese módulo la escribe y la consulta directamente.

A partir de ahí hay un abanico de opciones con costes distintos. Un esquema por módulo dentro de la misma instancia da un límite visible y permisos separados, manteniendo las transacciones locales. Un esquema único con convención de prefijo es más barato de montar y más fácil de incumplir. Una base de datos por módulo facilita una extracción futura, pero elimina los JOIN entre módulos y obliga a consistencia eventual desde el primer día, muchas veces antes de que el sistema lo necesite.

Volvamos al OrderService de novecientas líneas de la primera sección. Añadir «cancelar pedido» a una estructura por capas obliga a tocar cuatro directorios y a meter un método más en una clase que ya comparten otros diez casos de uso sin ninguna relación entre sí. A partir de cierto tamaño, cada cambio exige entender código que no tiene nada que ver con el cambio.

Vertical Slice invierte el criterio: el corte principal es el caso de uso. Un slice agrupa el punto de entrada, la lógica de la operación, sus validaciones, el acceso a datos que necesita, los modelos propios de esa operación y sus pruebas.

Qué no significa Vertical Slice

Cuatro aclaraciones que ahorran discusiones. Ninguna es un matiz menor.

• No es una arquitectura de despliegue. Un slice no es un servicio, no se despliega por separado y no escala por separado. Describe cómo se agrupa el código fuente dentro de una aplicación.
• No exige una base de datos por funcionalidad. Lo normal es que todos los slices compartan la misma. Lo que cambia es cómo se accede a ella, no cuántas hay.
• No obliga a duplicar la lógica. Las invariantes del dominio siguen viviendo en el modelo, en un único sitio. Lo que deja de compartirse es el flujo de la operación, no las reglas.
• No implica que los slices sean independientes entre sí. Comparten dominio, infraestructura y, muy a menudo, transacción.

Dónde está la ganancia real

La ventaja que más se nota en un sistema en producción no es estética: es que cada operación puede usar la estrategia de acceso a datos que le conviene. Crear un pedido necesita el agregado completo, con sus invariantes y su transacción. Listar los pedidos de un cliente para una pantalla necesita cinco columnas, y cargar el agregado entero para descartar el noventa por ciento es un coste que se paga en cada petición.

Con un repositorio genérico compartido por todos los casos de uso, esa diferencia se resuelve añadiendo métodos y parámetros hasta que el repositorio sirve mal a todos. Con slices, la escritura usa JPA y la lectura proyecta una consulta SQL directamente sobre un DTO, sin que ninguna de las dos decisiones contamine a la otra. Es el mismo razonamiento que sostiene la separación entre comandos y consultas, aplicado sin necesidad de adoptar CQRS como tal.

Cuándo empeora las cosas

Vertical Slice reduce el acoplamiento accidental y a cambio abre la puerta a la duplicación. Si cada slice reimplementa el cálculo de impuestos, el sistema tiene ahora cinco versiones de una regla de negocio y ninguna garantía de que coincidan. Ese fallo no se ve en una revisión de código: se ve en una conciliación contable.

El otro riesgo es la deriva. Veinte slices escritos por seis personas a lo largo de dos años, sin una referencia común, producen veinte formas distintas de validar una entrada y de devolver un error. La estructura no impone cohesión por sí sola.

Casi todas las comparativas entre estos dos enfoques fallan por el mismo sitio: los presentan como opciones excluyentes y acaban mezclando organización del código con decisiones de infraestructura. La tabla siguiente se limita a lo primero, que es lo único en lo que realmente se diferencian.

La fila que mejor resume la diferencia es la segunda. En un monolito modular el límite es un artefacto del proyecto: existe una interfaz publicada y existe una prueba que falla si alguien la rodea. En Vertical Slice el límite es una convención: nada impide que un handler importe clases de otro slice, y lo que lo evita es la disciplina del equipo y la revisión de código.

Eso no convierte a uno en superior. Significa que resuelven problemas distintos y que la pregunta «¿cuál elijo?» suele estar mal planteada, como veremos en la sección 6.

Cuándo suele encajar un monolito modular

• El dominio tiene límites reconocibles. Si puedes nombrar cuatro o cinco áreas de negocio y señalar quién decide en cada una, los módulos ya existen en la organización y el código solo tiene que reflejarlos.
• Necesitas imponer reglas entre áreas. Cuando hay partes del sistema que no deben tocarse desde cualquier sitio —precios, límites de crédito, datos personales—, el contrato publicado es el mecanismo que lo hace verificable en el build en vez de confiarlo a la revisión.
• Varios equipos comparten un despliegue. El módulo da propiedad sin exigir separar artefactos: cada equipo manda en lo suyo y negocia solo el contrato.
• Hay lógica de negocio que atraviesa casos de uso. Si veinte operaciones dependen de las mismas invariantes de pedido, tener un modelo de dominio compartido dentro de un límite es justo lo que evita veinte copias.
• Podrías necesitar extraer un módulo. Un módulo con contrato y sin ciclos es extraíble el día que aparezca un motivo real: un ritmo de despliegue incompatible, un requisito de aislamiento, una carga que no cabe. Que sea posible no significa que vaya a ocurrir, ni que deba.

Cuándo suele encajar Vertical Slice

• La aplicación gira alrededor de operaciones, no de áreas. Un back-office, un motor de trámites o una API de integración son conjuntos de casos de uso heterogéneos dentro de un mismo dominio.
• Las operaciones se parecen poco entre sí. Cuando una escritura transaccional y un listado de lectura intensiva comparten el mismo repositorio, el repositorio acaba sirviendo mal a las dos.
• El equipo necesita localizar un cambio rápido. Un paquete por caso de uso reduce el tiempo de «dónde está esto» prácticamente a cero, y eso importa mucho cuando hay rotación o incorporaciones frecuentes.
• Las funcionalidades evolucionan a ritmos distintos. Si una operación cambia cada semana y otra lleva dos años intacta, compartir servicio obliga a arrastrar la segunda en cada despliegue de la primera.
• Organizar por capas está dispersando los cambios. El síntoma medible es el número de ficheros que toca una historia de usuario media. Si crece sin que crezca la funcionalidad, el eje de corte está trabajando en contra.

Cuándo cada uno resulta excesivo

El monolito modular sobra cuando el dominio no tiene fronteras claras todavía. Dibujar módulos sobre un dominio que aún no se entiende produce límites en el sitio equivocado, y un límite mal puesto es más caro de mover que la ausencia de límite. En un sistema pequeño con un solo equipo, el coste de gobernar contratos no lo paga nadie.

Vertical Slice sobra cuando la aplicación tiene pocas operaciones y se parecen mucho entre sí. Un CRUD sobre seis entidades organizado en treinta paquetes de un fichero cada uno no ha reducido ninguna complejidad: ha añadido ceremonia. También sobra cuando el equipo no tiene todavía criterio compartido sobre qué es dominio y qué es flujo, porque es justo la decisión que el enfoque obliga a tomar en cada slice.

El módulo responde a dónde está la frontera del negocio. El slice responde a dónde cae un cambio funcional. Son preguntas independientes, y por eso la estructura que las combina no tiene nada de híbrida: el primer nivel de paquetes es el dominio y el segundo es el caso de uso.

src/main/java/com/tienda/
├── customers/                  ← módulo: frontera de negocio
│   ├── CustomerQuery.java          contrato publicado
│   ├── domain/                     modelo del módulo
│   └── usecases/
│       ├── createcustomer/         ← slice
│       ├── getcustomer/
│       └── updatecustomer/
├── orders/
│   ├── OrderQuery.java
│   ├── OrderPlaced.java            evento de dominio
│   ├── domain/
│   └── usecases/
│       ├── createorder/
│       ├── cancelorder/
│       └── getorder/
├── billing/
│   ├── domain/
│   └── usecases/
│       ├── issueinvoice/
│       └── getinvoice/
└── shared/                     ← infraestructura, sin reglas de negocio
    ├── security/
    └── persistence/

Es un esquema, no una plantilla. Los nombres concretos, la profundidad y la decisión de agrupar los casos de uso bajo usecases/ o colgarlos directamente del módulo dependen del proyecto. Lo que sí debe conservarse es el orden de los dos ejes: primero el módulo, después la operación.

Qué se gana

• Las fronteras de negocio son explícitas y verificables. La regla «ningún slice puede importar clases internas de otro módulo» es una prueba de arquitectura de cinco líneas.
• Un cambio funcional cae en un sitio. Modificar la cancelación de pedidos toca orders/usecases/cancelorder/ y, si cambia una invariante, orders/domain/. Nada más.
• La duplicación queda acotada. El dominio compartido vive en el módulo, así que la tentación de copiar una regla se topa con un modelo que ya está ahí y a mano.
• El borrado es limpio. Retirar una funcionalidad es borrar un paquete y su prueba, sin ir buscando métodos huérfanos por tres servicios.

Qué cuesta

Más convenciones que explicar y defender. Un desarrollador que entra tiene que entender dos niveles de agrupación y la regla de dependencia entre módulos antes de escribir la primera línea. Eso es documentación que hay que escribir y mantener.

Y una decisión que hay que tomar en cada caso de uso: qué pertenece al dominio del módulo y qué es propio del slice. Tomarla mal hacia un lado produce duplicación de reglas; tomarla mal hacia el otro produce un modelo de dominio que crece con cada operación hasta volver al OrderService del principio, solo que con otro nombre.

orders/
├── controller/
│   └── OrderController.java        6 endpoints
├── service/
│   └── OrderService.java           11 métodos públicos
├── repository/
│   └── OrderRepository.java        23 métodos de consulta
└── model/
    ├── Order.java
    └── OrderDto.java

orders/
├── OrderQuery.java                 contrato publicado
├── domain/
│   ├── Order.java                  invariantes del agregado
│   └── OrderRepository.java        puerto del módulo
└── usecases/
    ├── createorder/
    │   ├── CreateOrderController.java
    │   ├── CreateOrderHandler.java
    │   ├── CreateOrderRequest.java
    │   ├── CreateOrderResponse.java
    │   └── CreateOrderTest.java
    └── cancelorder/
        ├── CancelOrderController.java
        ├── CancelOrderHandler.java
        └── CancelOrderTest.java

Fíjate en dos detalles que no son cosméticos. domain/ está fuera de usecases/: ahí viven las invariantes del pedido y las comparten todos los slices, que es lo que impide que la organización por operaciones degenere en copias de las reglas. Y OrderQuery está en la raíz del módulo porque es la única clase que los demás módulos pueden ver.

El handler del caso de uso

package com.tienda.orders.usecases.createorder;

import com.tienda.catalog.CatalogQuery;
import com.tienda.orders.domain.Order;
import com.tienda.orders.domain.OrderRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
class CreateOrderHandler {

    private final OrderRepository orders;
    private final CatalogQuery catalog;

    CreateOrderHandler(OrderRepository orders, CatalogQuery catalog) {
        this.orders = orders;
        this.catalog = catalog;
    }

    @Transactional
    CreateOrderResponse handle(CreateOrderRequest request) {

        var items = request.lines().stream()
                .map(line -> catalog.priceOf(line.sku(), line.quantity()))
                .toList();

        var order = Order.place(request.customerId(), items);

        orders.save(order);

        return CreateOrderResponse.from(order);
    }
}

El handler es visible solo dentro de su paquete —sin public— y esa es una decisión deliberada: nadie fuera del slice debería invocarlo. Depende de dos cosas, y las dos están declaradas en el constructor: el puerto de persistencia del módulo y CatalogQuery, que es el contrato publicado por catálogo. No importa ninguna clase interna de otro módulo, y ese es exactamente el límite que la siguiente prueba verifica.

La transacción vive aquí, en el caso de uso, y no en un servicio compartido. Permite que «cancelar pedido» tenga un comportamiento transaccional distinto sin negociarlo con nadie, que es una de las razones prácticas por las que esta organización reduce fricción.

La prueba que sostiene los límites

@AnalyzeClasses(packages = "com.tienda")
class ModuleBoundaryTest {

    @ArchTest
    static final ArchRule los_modulos_solo_se_hablan_por_contrato =
            noClasses()
                    .that().resideInAPackage("com.tienda.(*)..")
                    .should().dependOnClassesThat()
                    .resideInAPackage("com.tienda.(*).domain..")
                    .because("el dominio de un módulo es interno: fuera se usa su contrato publicado");

    @ArchTest
    static final ArchRule sin_ciclos_entre_modulos =
            slices().matching("com.tienda.(*)..")
                    .should().beFreeOfCycles();
}

Esta es la pieza que convierte un diagrama en una arquitectura. La primera regla impide que un módulo alcance el dominio interno de otro; la segunda detecta ciclos entre módulos en cuanto aparecen, no seis meses después. Si falla, falla el build, y nadie tiene que acordarse de la convención durante una revisión de código a las siete de la tarde.

Quien prefiera no escribir las reglas a mano tiene en Spring Modulith una verificación equivalente basada en la estructura de paquetes, más la documentación del modelo de módulos generada a partir del propio código. Lo importante no es la herramienta: es que exista algo que falle.

Qué cambia al añadir una funcionalidad

Añadir «devolver pedido» a la estructura por capas significa un método en el controlador, uno en el servicio, dos consultas en el repositorio y un DTO nuevo: cuatro ficheros modificados que otros casos de uso también usan, y por tanto cuatro oportunidades de romper algo ajeno.

En la estructura por slices significa un paquete nuevo, orders/usecases/returnorder/, y una modificación en Order si la devolución introduce una invariante nueva. El resto del módulo no se toca. La diferencia se nota sobre todo en la revisión: el diagrama de cambios de la pull request coincide con el alcance funcional del cambio.

Los dos primeros tienen la misma raíz: un límite que nadie hace cumplir no es un límite. Se corrigen con una prueba de arquitectura, y cuesta una tarde montarla sobre un proyecto que ya existe, aunque al principio haya que marcar excepciones para las violaciones heredadas e ir reduciéndolas.

El tercero y el quinto son de criterio y no se resuelven con herramientas. Lo que ayuda es acordar de antemano dos cosas: qué pertenece al dominio compartido del módulo, y cuál es el tamaño a partir del cual la estructura deja de ser gratuita. Escribirlo en una decisión de arquitectura evita volver a discutirlo en cada pull request.

Si el problema es que cualquier parte del código puede tocar cualquier regla de negocio, lo que necesitas son límites: el monolito modular los establece y, con una prueba de arquitectura, los sostiene.

Si el problema es que cada cambio funcional se reparte por cuatro directorios y obliga a entender código ajeno al cambio, lo que necesitas es cohesión por caso de uso: Vertical Slice la da.

Y si tienes los dos problemas a la vez, que es lo habitual en un sistema con varios años y varios equipos, no hay que elegir. Los módulos marcan las fronteras del negocio; los slices organizan el trabajo dentro de ellas. Son ejes distintos del mismo código.

Lo que ninguno de los dos hace es sustituir a la decisión. Una estructura no mantiene sola un sistema: lo que lo mantiene es que las reglas de dependencia estén escritas, que algo las verifique en cada build y que el equipo entienda por qué están ahí. Sin eso, cualquiera de las dos organizaciones degenera en la anterior en un par de años.

Si vas a tocar la estructura de un sistema que ya está en producción, empieza por lo barato y reversible: dibuja los módulos que ya existen de hecho en el código, escribe una prueba de arquitectura que falle con las dependencias que no deberían existir, y mira cuántas falla. Ese número dice más sobre tu arquitectura que cualquier diagrama, y es también el mejor punto de partida para decidir qué organización necesitas de verdad.

Fuentes

• Jimmy Bogard — Vertical Slice Architecture Formulación original del enfoque y de su contraste con la organización por capas. Respalda la sección 3.
• Martin Fowler — Presentation Domain Data Layering Qué resuelve la organización por capas y dónde deja de escalar como criterio principal. Respalda la sección 1.
• Martin Fowler — Bounded Context El razonamiento de Domain-Driven Design que hay detrás del reparto en módulos de negocio. Respalda la sección 2.
• Martin Fowler — Monolith First Por qué dividir antes de entender el dominio fija los límites en el sitio equivocado. Respalda la sección 5.
• Spring Modulith Verificación de módulos, eventos de dominio entre módulos y documentación generada desde el código. Respalda las secciones 2 y 7.
• ArchUnit Reglas de arquitectura como pruebas de JUnit, incluida la detección de ciclos entre paquetes. Respalda la sección 7.

Continúa en este blog

• Arquitectura Hexagonal desde cero Cómo aislar el dominio de un módulo con puertos y adaptadores, que es la estructura interna que mejor acompaña a los contratos de la sección 2.
• Observabilidad en Microservicios Qué hace falta tener instrumentado antes de extraer un módulo y convertirlo en un servicio independiente.
• Arquitectura Java Decisiones estructurales en plataformas Java enterprise, más allá de la organización de paquetes.
• Domain-Driven Design Cómo se identifican las fronteras de negocio que después se convierten en módulos.
• Auditoría técnica El servicio que aplica a una plataforma concreta el diagnóstico con el que cierra la conclusión.