Spring Modulith — le monolithe modulaire outillé par Spring Boot

1📖 Glossaire — le vocabulaire de base

• Module applicatif — unité fonctionnelle de l'application. Concrètement : un package et tout ce qu'il contient.
• API du module — les types publics du package racine du module, plus les événements qu'il publie. C'est la seule partie visible depuis les autres modules.
• Package interne — tout sous-package du module. Interdit d'accès depuis un autre module.
• Named interface — sous-package qu'on choisit d'exposer aux autres modules, en plus du package racine.
• Module ouvert (open) — module dont les internes restent accessibles. Utile sur du code existant en cours de migration.
• ArchUnit — librairie de tests d'architecture. Elle lit le bytecode et vérifie des règles de dépendances. C'est le moteur utilisé par Modulith.
• Event Publication Registry — table en base qui journalise chaque événement publié, listener par listener. L'écriture se fait dans la transaction métier.
• Externalisation — republication d'un événement interne vers un broker externe (Kafka, AMQP, JMS).
• Application module canvas — fiche générée pour chaque module : beans exposés, événements publiés, événements écoutés, propriétés de configuration.

2Le projet et ses versions

Spring Modulith est un projet Spring officiel, mené par Oliver Drotbohm. Il ne remplace ni Spring Boot ni Spring Framework. Il s'ajoute par-dessus.

État des lignes de version (septembre 2026) :

Le point d'entrée est un BOM. Ensuite, on ajoute un starter par besoin.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.modulith</groupId>
      <artifactId>spring-modulith-bom</artifactId>
      <version>2.1.1</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

3Un exemple pour toute la note

Toute la suite s'appuie sur la même application : une boutique avec deux modules.

• order gère les commandes.
• inventory gère le stock.

Quand une commande est terminée, le stock doit baisser. C'est le seul lien entre les deux modules. La note montre comment l'exprimer proprement.

shop
├── ShopApplication.java                  ← package principal
├── shop.order                            ← module "order"
│   ├── OrderManagement.java                 API : public
│   ├── OrderCompleted.java                  événement : public
│   └── shop.order.internal
│       └── OrderRepository.java             interne : interdit aux autres modules
└── shop.inventory                        ← module "inventory"
    ├── InventoryManagement.java             API : public
    └── StockItem.java                       package-private : invisible

Mise en place en quatre étapes :

1. Ajouter le BOM et spring-modulith-starter-core.
2. Ranger le code : un sous-package direct de shop par module.
3. Écrire le test de vérification (section 5).
4. Remplacer les appels directs entre modules par des événements (section 6).

Les trois premières étapes tiennent en une heure sur un projet neuf.

4La structure : le package est le module

Par défaut, chaque sous-package direct du package de la classe @SpringBootApplication devient un module. Il n'y a rien à déclarer.

Deux niveaux de protection existent :

• Module sans sous-package (inventory). La visibilité Java suffit. Une classe package-private n'est visible que dans son package. Le compilateur protège.
• Module avec sous-packages (order). Pour que OrderManagement utilise OrderRepository, il faut rendre OrderRepository public. Le compilateur ne protège plus rien. C'est Modulith qui prend le relais : tout ce qui est dans shop.order.internal est interdit aux autres modules, même si c'est public.

Exposer un sous-package : la named interface

Parfois, un module veut exposer plus que son package racine. Par exemple, un package spi avec des interfaces à implémenter par les autres modules. On l'annote dans son package-info.java :

@org.springframework.modulith.NamedInterface("spi")
package shop.order.spi;

Sans Modulith, la même intention s'exprime avec les outils de base :

• Un package public explicite (order.api, order.event) qui contient les interfaces et les événements. Tout le reste en package-private.
• Une règle ArchUnit pour les types qui doivent rester public pour des raisons techniques (entités JPA, config Spring) : aucune classe hors order ne dépend de order.internal...

La named interface ne fait rien de plus. Elle rend la convention lisible et vérifiée par un test prêt à l'emploi.

Restreindre les dépendances autorisées

Par défaut, un module peut voir l'API de tous les autres. On peut limiter la liste dans le package-info.java du module :

@org.springframework.modulith.ApplicationModule(
    allowedDependencies = { "order", "order :: spi" }  // ✓ liste blanche
)
package shop.inventory;

Lecture de la syntaxe :

• "order" : accès au package racine du module order.
• "order :: spi" : accès à la named interface spi du module order.
• "order :: *" : accès à toutes les named interfaces déclarées par order.

Qui peut voir quoi

flowchart LR
    subgraph ORD["module order"]
        OM["shop.order<br/>OrderManagement, OrderCompleted<br/>(API par défaut)"]
        OS["shop.order.spi<br/>@NamedInterface(&quot;spi&quot;)"]
        OI["shop.order.internal<br/>OrderRepository"]
    end
    subgraph INV["module inventory"]
        IM["InventoryManagement"]
    end
    IM -->|autorisé| OM
    IM -->|autorisé si déclaré| OS
    IM -.->|rejeté par verify| OI
    OM --> OI
    OS --> OI

Les variantes utiles

• Modules imbriqués (depuis 1.3). Annoter un sous-package avec @ApplicationModule en fait un module dans le module. Le module imbriqué voit tout son parent. L'inverse est faux.
• Modules ouverts. @ApplicationModule(type = Type.OPEN). Les internes redeviennent accessibles. Sert à poser Modulith sur du code existant sans tout casser le premier jour.
• Détection explicite. spring.modulith.detection-strategy=explicitly-annotated. Seuls les packages annotés deviennent des modules. Les autres sont ignorés.

5La vérification : un test, trois règles

Tout tient dans un test.

class ModularityTests {

  ApplicationModules modules = ApplicationModules.of(ShopApplication.class);

  @Test
  void verifiesModularStructure() {
    modules.verify();  // ✓ échoue le build en cas de violation
  }
}

Les trois règles vérifiées :

1. Pas de cycle entre modules. Si order dépend de inventory et inventory dépend de order, le test échoue.
2. Accès par l'API seulement. Toute référence à un type situé dans un package interne d'un autre module est rejetée.
3. Dépendances déclarées seulement. Si le module a défini allowedDependencies, tout accès hors liste est rejeté.

À quoi ressemble un échec

Supposons que InventoryManagement importe shop.order.internal.OrderRepository. Le test échoue avec un message de ce type :

org.springframework.modulith.core.Violations:
- Module 'inventory' depends on non-exposed type
  shop.order.internal.OrderRepository within module 'order'!

Le message dit quel module est fautif, quel type est visé, et dans quel module ce type est enfermé. La correction est toujours l'une de ces trois options :

• passer par l'API du module order (ici OrderManagement),
• exposer le type via une named interface, si c'est vraiment voulu,
• déplacer le type dans le bon module, si c'est lui qui était mal placé.

Tolérer des violations le temps d'une migration

Sur du code existant, on ne corrige pas tout le premier jour. On peut filtrer :

ApplicationModules.of(ShopApplication.class)
    .detectViolations()
    .filter(v -> !v.getMessage().contains("legacy.reporting"))  // ⚠️ dette explicite
    .throwIfPresent();

Il existe aussi une vérification au démarrage de l'application : spring.modulith.runtime.verification-enabled=true. C'est un choix discutable. Une violation d'architecture doit casser le build, pas la production.

6Communiquer entre modules : de l'appel direct à l'événement

Reprenons le besoin : quand une commande est terminée, le stock doit baisser.

Version 1 : l'appel direct

@Service
class OrderManagement {

  private final InventoryManagement inventory;  // ⚠️ dépendance vers un autre module

  @Transactional
  public void complete(Order order) {
    order.markCompleted();
    inventory.updateStockFor(order);            // ⚠️ order connaît inventory
  }
}

Ça fonctionne et Modulith l'autorise (on reste sur l'API). Mais trois problèmes apparaissent avec le temps :

• OrderManagement accumule tout ce qui doit se passer après une commande : stock, facturation, email, statistiques.
• Pour tester order, il faut instancier ou mocker les beans de tous ces modules.
• Chaque nouveau besoin métier oblige à rouvrir OrderManagement.

Version 2 : l'événement

@Service
class OrderManagement {

  private final ApplicationEventPublisher events;

  @Transactional
  public void complete(Order order) {
    order.markCompleted();
    events.publishEvent(new OrderCompleted(order.getId()));  // ✓ order ne connaît plus ses consommateurs
  }
}

// shop/order/OrderCompleted.java
public record OrderCompleted(UUID orderId) {}

Le module order publie un fait : « cette commande est terminée ». Il ne sait pas qui écoute. Le module inventory s'abonne.

Choisir comment consommer

Publier ne suffit pas. Il faut choisir quand le listener s'exécute.

Synchrone, dans la transaction de l'appelant (le défaut de Spring avec @EventListener). Simple : tout passe ou rien ne passe. Mais la transaction s'allonge à chaque nouveau listener. Et une erreur dans le listener stock fait échouer la commande. Les règles de propagation sont détaillées dans spring-boot-transactional-propagation-isolation-appels-entre-beans.

Asynchrone, après commit (@TransactionalEventListener + @Async). La transaction métier reste courte. Mais si le listener plante, ou si l'application tombe avant de l'exécuter, l'événement est perdu. Rien ne le signale.

C'est ce trou que Modulith bouche.

@Component
class InventoryManagement {

  @ApplicationModuleListener  // ✓ raccourci fourni par Modulith
  void on(OrderCompleted event) {
    // baisser le stock des lignes de la commande
  }
}

@ApplicationModuleListener regroupe trois annotations :

@Async
@Transactional(propagation = Propagation.REQUIRES_NEW)
@TransactionalEventListener
void on(OrderCompleted event) { /* … */ }

En clair : le listener s'exécute après le commit de la commande, sur un autre thread, dans une transaction neuve. Et grâce au registry (section suivante), l'événement est journalisé avant même d'être livré.

Ce qui arrive en cas d'échec

Le mot rollback change de sens avec @ApplicationModuleListener.

• La transaction de la commande échoue : l'événement n'est jamais livré. Aucune ligne dans le registry. Rien à faire.
• Le listener échoue : la commande est déjà commitée. Elle ne sera pas annulée. Le stock n'a pas bougé. La ligne du registry passe en FAILED.

Il n'y a donc pas de rollback global. Il y a un rejeu (section 7) ou une compensation écrite à la main. Deux conséquences :

• Chaque listener doit être idempotent. Un rejeu peut relivrer un événement déjà traité en partie.
• On accepte la cohérence à terme à l'intérieur d'une seule application. C'est le même modèle mental qu'avec un broker, sans le broker.

Si ce modèle ne convient pas au cas d'usage, le @EventListener synchrone reste disponible. Tout passe ou rien ne passe, au prix du couplage transactionnel.

7L'Event Publication Registry

C'est le mécanisme central du projet. Voici ce qui se passe quand order publie OrderCompleted :

1. Modulith cherche les listeners transactionnels concernés. Ici : InventoryManagement.on(OrderCompleted).
2. Il écrit une ligne par listener dans la table event_publication, dans la même transaction que la commande.
3. La transaction commit. La commande et la ligne de journal sont écrites ensemble, ou pas du tout.
4. Le listener est appelé sur un autre thread. Un aspect met la ligne à jour selon le résultat.

sequenceDiagram
    participant O as OrderManagement
    participant DB as table event_publication
    participant L as InventoryManagement

    O->>O: order.markCompleted()
    O->>DB: INSERT 1 ligne par listener (status PUBLISHED)
    Note over O,DB: même transaction que la commande
    O->>O: COMMIT
    O-->>L: livraison asynchrone
    L->>DB: UPDATE status = PROCESSING, completion_attempts + 1
    alt listener OK
        L->>DB: UPDATE status = COMPLETED, completion_date
    else listener KO
        L->>DB: UPDATE status = FAILED
        Note over DB: resoumission possible plus tard
    end

Ce que contient la table

Schéma PostgreSQL :

CREATE TABLE IF NOT EXISTS event_publication
(
  id                     UUID NOT NULL,
  listener_id            TEXT NOT NULL,              -- ⚠️ signature de la méthode listener
  event_type             TEXT NOT NULL,
  serialized_event       TEXT NOT NULL,              -- JSON via Jackson par défaut
  publication_date       TIMESTAMP WITH TIME ZONE NOT NULL,
  completion_date        TIMESTAMP WITH TIME ZONE,
  status                 TEXT,                       -- depuis 2.0
  completion_attempts    INT,                        -- depuis 2.0
  last_resubmission_date TIMESTAMP WITH TIME ZONE,   -- depuis 2.0
  PRIMARY KEY (id)
);

Exemple concret. La commande A1 est terminée. Le listener stock réussit. Puis la commande B2 est terminée, mais la base tombe pendant le traitement du stock. Voici la table après ces deux publications :

-- event_publication (colonnes principales)
id   | listener_id                                                       | status    | completion_attempts
e-01 | shop.inventory.InventoryManagement.on(shop.order.OrderCompleted)  | COMPLETED | 1
e-02 | shop.inventory.InventoryManagement.on(shop.order.OrderCompleted)  | FAILED    | 1

La ligne e-02 reste en base. La commande B2 est bien enregistrée. Le stock n'a pas bougé. Mais on le sait, et on peut rejouer.

La table est créée automatiquement au démarrage, sauf si spring.modulith.events.jdbc.schema-initialization.enabled=false. Sur un vrai projet, on la gère par migration Flyway ou Liquibase.

Le cycle de vie d'une publication (nouveauté 2.0)

stateDiagram-v2
    [*] --> PUBLISHED : INSERT dans la transaction métier
    PUBLISHED --> PROCESSING : le listener démarre
    PROCESSING --> COMPLETED : listener OK
    PROCESSING --> FAILED : listener en erreur
    PUBLISHED --> FAILED : périmé (staleness)
    PROCESSING --> FAILED : périmé (staleness)
    FAILED --> RESUBMITTED : resubmit()
    RESUBMITTED --> PROCESSING : le listener redémarre
    COMPLETED --> [*] : purge ou archive

Avant la 2.0, une publication était « complétée » ou « pas complétée ». Impossible de distinguer « en cours depuis deux secondes » de « planté depuis une heure ». Le statut résout ce problème.

Le moniteur de staleness

Une application qui tombe en plein traitement laisse des lignes bloquées en PROCESSING. Le moniteur les passe en FAILED après une durée configurable.

spring:
  modulith:
    events:
      staleness:
        check-interval: 1m
        published: 5m      # 0 = désactivé (défaut)
        processing: 10m
        resubmitted: 10m
      completion-mode: archive

⚠️ Les trois durées sont à zéro par défaut. Le moniteur ne fait rien tant qu'on ne les configure pas.

Rejouer les échecs et purger

@Component
class EventRecovery {

  private final FailedEventPublications failed;         // depuis 2.0
  private final CompletedEventPublications completed;

  @Scheduled(fixedDelay = 60_000)
  void resubmitFailed() {
    failed.resubmit(ResubmissionOptions.defaults()
        .withBatchSize(50)
        .withMinAge(Duration.ofMinutes(2))                  // ✓ laisse passer les erreurs transitoires
        .withFilter(p -> p.getCompletionAttempts() < 5));   // ✓ évite la boucle infinie
  }

  @Scheduled(cron = "0 0 3 * * *")
  void purge() {
    completed.deletePublicationsOlderThan(Duration.ofDays(7));
  }
}

Trois modes de complétion, via spring.modulith.events.completion-mode :

Une propriété à connaître : spring.modulith.events.republish-outstanding-events-on-restart. Elle rejoue les publications en attente au démarrage. La doc déconseille de l'activer en déploiement multi-instance. Une autre instance est peut-être déjà en train de traiter ces mêmes événements.

8Sortir de l'application : l'externalisation

Certains événements intéressent d'autres systèmes. Modulith sait republier un événement interne vers un broker.

@Externalized("orders.completed::#{#this.orderId()}")  // topic :: clé de routage
public record OrderCompleted(UUID orderId) {}

La partie après :: est une expression SpEL évaluée sur l'événement. Elle donne la clé de partition Kafka ou la routing key AMQP. Sans annotation explicite, la cible par défaut est le nom du type relatif au package de base.

Pour garder la main sur le contrat externe, on configure les trois étapes : quels événements sortent, sous quelle forme, vers où.

@Bean
EventExternalizationConfiguration externalization() {
  return EventExternalizationConfiguration.externalizing()
      .select(EventExternalizationConfiguration.annotatedAsExternalized())
      .mapping(OrderCompleted.class, event -> new OrderCompletedPayload(event))  // ✓ contrat externe distinct du type interne
      .headers(event -> Map.of("schema-version", "2"))
      .routeKey(OrderCompleted.class, event -> event.orderId().toString())
      .build();
}

9Tester module par module

@ApplicationModuleTest remplace @SpringBootTest. Il ne démarre que le module dans lequel la classe de test se trouve.

package shop.order;

@ApplicationModuleTest
class OrderIntegrationTests {

  @MockitoBean InventoryManagement inventory;  // ✓ on mocke, on n'élargit pas le périmètre
}

Trois modes de démarrage :

Le contexte est réellement réduit. Le scan de composants, l'auto-configuration et le scan d'entités sont limités aux packages du module. Sur une grosse application, le gain de temps de démarrage est net.

Si un test échoue au démarrage à cause de beans d'autres modules, la bonne réaction est de les mocker, pas d'élargir le mode. Un module qui a besoin de dix beans externes est un module mal découpé.

L'API Scenario

Tester une chaîne asynchrone à la main est pénible : transactions, attente, assertions. Scenario fait le travail.

@ApplicationModuleTest
class OrderIntegrationTests {

  @Test
  void completingAnOrderTriggersStockUpdate(Scenario scenario) {
    scenario.stimulate(() -> orders.complete(order))
        .customize(it -> it.atMost(Duration.ofSeconds(2)))
        .andWaitForEventOfType(StockUpdated.class)
        .matching(event -> event.orderId().equals(order.getId()))
        .toArriveAndVerify(event -> assertThat(event.quantity()).isEqualTo(3));
  }
}

Lecture ligne par ligne : on déclenche l'action, on attend au plus deux secondes, on attend un événement StockUpdated, on filtre celui de notre commande, on vérifie son contenu.

Variante quand aucun événement de sortie n'existe. On attend un changement d'état :

scenario.publish(new OrderCompleted(orderId))
    .andWaitForStateChange(() -> inventory.findStock(sku))
    .andVerify(stock -> assertThat(stock.available()).isZero());

Deux autres outils :

• PublishedEvents / AssertablePublishedEvents, injectés en paramètre de test, pour vérifier qu'un événement a bien été publié. Depuis la 2.1, ils voient les événements de tous les threads.
• spring-modulith-junit n'exécute que les tests des modules modifiés, ou dépendant d'un module modifié. En CI, il faut renseigner spring.modulith.test.reference-commit avec le commit du dernier build vert.

10Documentation générée

Le modèle de modules sait se dessiner tout seul, depuis un test.

@Test
void writeDocumentationSnippets() {
  new Documenter(modules)
      .writeModulesAsPlantUml()             // vue d'ensemble, style C4 par défaut
      .writeIndividualModulesAsPlantUml()   // un diagramme par module
      .writeModuleCanvases();               // une fiche par module
}

La sortie va dans target/spring-modulith-docs. Voici ce que produit la doc officielle pour une application d'exemple (modules order, inventory, catalog, customer) :

Et le diagramme centré sur un seul module, avec ses dépendances directes :

Le canvas est une table par module. Elle liste :

• le package de base,
• les beans exposés, groupés par stéréotype (services, repositories, listeners),
• les événements publiés, avec la méthode qui les crée,
• les événements écoutés,
• les propriétés de configuration.

Avec spring-modulith-apt en compile, le Javadoc des types est repris dans la fiche.

11En production : actuator et traces

<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-starter-insight</artifactId>
  <scope>runtime</scope>
</dependency>

Deux choses arrivent.

L'endpoint /actuator/modulith expose la structure réelle au runtime. Pour chaque module : son package de base, ses dépendances sortantes, et le type de chaque dépendance.

{
  "order": { "basePackage": "shop.order", "displayName": "Order", "dependencies": [] },
  "inventory": {
    "basePackage": "shop.inventory",
    "displayName": "Inventory",
    "dependencies": [ { "target": "order", "types": [ "EVENT_LISTENER" ] } ]
  }
}

Trois types de dépendance existent : DEFAULT (référence de type), USES_COMPONENT (injection d'un bean), EVENT_LISTENER (écoute d'un événement). Ici, inventory ne dépend de order que par un événement. C'est le couplage le plus faible possible.

L'observabilité décore les beans exposés par chaque module. Chaque franchissement de frontière produit un span Micrometer, avec les tags module.name, module.identifier, module.method et module.invocation-type (bean ou event listener). Une trace montre alors le chemin entre modules, et pas seulement une pile d'appels Java.

Deux compteurs sont aussi publiés : module.events.published pour l'ensemble, et un compteur par type d'événement. On peut y ajouter des tags métier avec un ModulithEventMetricsCustomizer.

12️⃣ Adopter Modulith sur un projet existant

Sur un projet neuf, on pose la structure le premier jour. Sur un projet existant, on procède par étapes.

1. Ajouter spring-modulith-starter-core et le test verify(). Il échoue. C'est normal.
2. Marquer tous les modules comme ouverts (Type.OPEN). Le test passe. On a une photo de départ.
3. Fermer un module à la fois. Commencer par celui qui a le moins de dépendances entrantes. Corriger les violations qu'il révèle.
4. Remplacer les appels directs par des événements là où deux modules s'appellent dans les deux sens. C'est le seul moyen de casser un cycle sans fusionner les modules.
5. Quand plus aucun module n'est ouvert, ajouter le registry et les tests par module.

Si un module reste ouvert plus de six mois, c'est qu'il ne sera jamais fermé. Il faut soit le fusionner avec son voisin le plus proche, soit accepter que la migration s'arrête là.

13️⃣ Avantages, inconvénients, et quand le choisir

Quand le choisir

Bon terrain :

• application métier avec plusieurs domaines identifiables, équipe de 3 à 20 personnes
• projet neuf où les frontières peuvent être posées dès le départ
• monolithe existant qu'on veut assainir avant de décider s'il faut le découper
• domaine encore instable : déplacer une frontière dans un monolithe est un refactoring, entre microservices c'est un projet
• besoin d'événements internes fiables sans installer un broker

Mauvais terrain :

• application déjà en microservices : Modulith adresse l'intérieur d'un déployable, pas la communication entre déployables
• un seul domaine découpé en couches techniques : Modulith découpe par domaine, pas par couche
• plusieurs déploiements qui partagent un domaine (une app API, une app consumer Kafka, même code métier) : Modulith travaille dans un seul contexte Spring. La frontière entre les deux est Maven, la communication est Kafka ou la base. Modulith ne fait pas de pont entre deux processus
• vraie contrainte de scaling ou de déploiement séparé par domaine
• CRUD sans domaine réel : trois entités ne font pas trois modules
• code existant sans tests, où la réorganisation des packages est trop risquée pour son bénéfice

Face aux alternatives

La comparaison la plus juste est avec ArchUnit seul. Modulith est ArchUnit, plus un modèle de modules prêt à l'emploi, plus les événements, les tests, la doc et l'observabilité. Si le besoin s'arrête à « interdire tel package d'appeler tel autre », ArchUnit suffit. Dès qu'on veut le découplage par événements sans perdre de message, Modulith prend l'avantage.

Sources

• Spring Modulith Reference Documentation — documentation officielle, version 2.1.1
• Fundamentals — modules, named interfaces, allowedDependencies, modules ouverts et imbriqués
• Working with Application Events — registry, cycle de vie 2.0, staleness, externalisation, mode outbox
• Verifying Application Module Structure — les trois règles vérifiées et leur personnalisation
• Integration Testing Application Modules — modes de bootstrap, API Scenario, exécution des tests par delta
• Documenting Application Modules — diagrammes C4/UML et canvas (source des deux images de la note)
• Production-ready Features — actuator modulith, spans et métriques Micrometer
• Appendix : propriétés et schémas — liste des propriétés, DDL par SGBD, catalogue des artefacts
• Spring Modulith 2.0 M1 released — annonce du nouveau cycle de vie du registry et du moniteur de staleness
• Spring Modulith 2.1 GA released — annonce du mode outbox (Namastack, JobRunr)
• spring-projects/spring-modulith — code source et exemples exécutables
• Namastack Outbox — implémentation d'outbox déléguée depuis la 2.1