En 2025, j’ai eu l’opportunité de mettre en place Spring Modulith sur une nouvelle application web. Pour partager cette expérience avec mes collègues, j’ai préparé une démonstration live montrant comment intégrer Spring Modulith dans une application Spring Boot.

J’avais besoin pour cela d’une application simple et universelle. Vous commencez à me connaitre : mon choix s’est naturellement porté sur la version canonique de Spring Petclinic.

Pris au jeu, j’ai progressivement enrichi l’application afin d’illustrer plusieurs fonctionnalités clés de Spring Modulith. J’ai ensuite mis ce fork à disposition de la communauté Spring Petclinic dont le code source complet est disponible sur GitHub : spring-petclinic-modulith.

Dans ce billet, je vous propose de découvrir Spring Modulith, puis de suivre pas à pas comment l’application démo Spring Petclinic a été enrichie pour tirer parti de ses fonctionnalités.

Architecture modulaire

L’architecture en microservices a le vent en poupe depuis une quinzaine d’années. Pourtant, force est de constater que nombre d’applications métiers restent des monolithes. Ce n’est pas nécessairement une mauvaise chose. Partir systématiquement d’un monolith avant de l’éclater (ou pas) en microservices est une approche préconisée par de nombreux architectes logiciels (cf. article Monolith First de Martin Fowler). Un monolithe bien structuré, celui qu’Oliver Drotbohm (le créateur de Spring Modulith) appelle le modulith ou que certains qualifient de modular monolith, représente souvent le meilleur compromis entre simplicité opérationnelle et maintenabilité au quotidien. Le projet Spring Modulith permet d’outiller cette approche.

Après plusieurs années de gestation, Spring Modulith a été rendu GA en août 2023. Relativement jeune, ce projet apporte un cadre structurant aux applications Spring Boot monolithiques en y introduisant la notion de modules applicatifs. Vérification de l’architecture au build, documentation générée automatiquement, communication inter-modules par événements, tests d’intégration ciblés… le tout sans nécessairement d’infrastructure externe.

Les fonctionnalités de Spring Modulith

Avant de plonger dans le code, prenons un peu de hauteur. Spring Modulith repose sur un principe simple : chaque sous-package direct du package de la classe principale Spring Boot (celle annotée avec @SpringBootApplication) constitue un module applicatif. Par convention, le package racine du module expose l’API publique ; tous les sous-packages sont considérés comme privés.

À partir de cette convention d’organisation, Spring Modulith propose un ensemble de fonctionnalités complémentaires :

La documentation officielle de Spring Modulith est très complète. Je vous encourage à vous y référer. Dans les paragraphes qui suivent, nous allons voir concrètement comment chaque fonctionnalité a été intégrée dans Spring Petclinic, ceci en 11 étapes. Pour rappel, cette application Spring Boot créée en 2003 met en scène une clinique vétérinaire avec ses propriétaires d’animaux, ses vétérinaires et la prise de rendez-vous.

Étape 1 – Ajouter les dépendances Maven

L’application Spring Petclinic supporte les deux principaux systèmes de build du monde Java : Maven et Gradle. Spring Petclinic Modulith également. Dans ce billet, par simplicité, nous nous focaliserons sur le build Maven.

Toute intégration de Spring Modulith commence par l’ajout du BOM et des premières dépendances. Dans le pom.xml, nous déclarons d’abord la version sous forme de properties (bonne pratique Maven) :

<spring-modulith.version>2.0.5</spring-modulith.version> 

<spring-modulith.version>2.0.5</spring-modulith.version> 

La version 2.x de Spring Modulith est compatible Spring Boot 4.

Puis on importe le BOM dans <dependencyManagement> :

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

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

Et enfin les dépendances minimales :

<!-- Annotations et API publique Spring Modulith -->
<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-api</artifactId>
</dependency>
<!-- Support JUnit 5 pour la vérification modulaire -->
<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-starter-test</artifactId>
  <scope>test</scope>
</dependency>

<!-- Annotations et API publique Spring Modulith -->
<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-api</artifactId>
</dependency>
<!-- Support JUnit 5 pour la vérification modulaire -->
<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-starter-test</artifactId>
  <scope>test</scope>
</dependency>

Deux dépendances suffisent pour démarrer. D’autres dépendances seront ajoutées au fil de l’article.

Étape 2 – Le test de vérification modulaire

C’est le point d’entrée incontournable de Spring Modulith. En quelques lignes, on écrit un test JUnit qui analyse la structure du code et vérifie que les modules respectent leurs frontières :

package org.springframework.samples.petclinic;

import org.junit.jupiter.api.Test;
import org.springframework.modulith.core.ApplicationModules;

class ModularityTests {

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

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

package org.springframework.samples.petclinic;

import org.junit.jupiter.api.Test;
import org.springframework.modulith.core.ApplicationModules;

class ModularityTests {

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

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

L’appel ApplicationModules.of(...) scanne les packages de l’application et construit un modèle en mémoire des modules détectés. L’appel à la méthode verify() s’assure ensuite trois aspects :

1. Pas de cycle entre les modules applicatifs
2. Pas d’accès aux packages internes d’un module depuis un autre module
3. Respect des dépendances explicites (si configurées via l’annotation @ApplicationModule)

Si une de ces règles est violée, le test échoue avec un message d’erreur précis. Voici un exemple dans lequel un cycle est détecté :

org.springframework.modulith.core.Violations: - Cycle detected: Slice owner ->                  
                Slice vet -> 
                Slice owner

La version Ultimate d’IntelliJ IDEA est packagée avec le plugin Spring Modulith. Le support de Spring Modulith permet à IntelliJ de mettre en évidence les utilisations de beans Spring (ou de toute autre classe) qui enfreignent les règles de Spring Modulith. IntelliJ propose de refactoriser le code afin de le rendre conforme à la structure modulaire. Je vous renvoie à la documentation de cette fonctionnalité.

Étape 3 – Identifier les modules applicatifs

Spring Modulith détecte automatiquement les modules à partir des sous-packages directs du package contenant la classe main @SpringBootApplication. Dans Spring Petclinic, la classe PetClinicApplication est localisée au niveau du package org.springframework.samples.petclinic.

Les modules identifiés étaient à ce stade au nombre de quatre :

Cette modularisation fonctionnelle de l’application Spring Petclinic avait été réalisée en 2016 par Dave Syer dans la PR #200 Modernize Spring apps structure. Oliver Drotbohm avait d’ailleurs participé à la conversation.

Le module model mutualisait 3 classes de base JPA BaseEntity, Person, NamedEntity partagées entre les modules owner et vet. Conservé en 2016, 10 ans plus tard à l’heure du Modulith, j’ai préféré reconsidérer ce choix. En effet, en DDD, chaque Bounded Context possède intégralement son modèle du domaine métier. Les classes BaseEntity, Person, NamedEntity ne sont pas des concepts métier. Ce sont des raccourcis techniques. Inliner le contenu de ces classes techniques dans vet et owner rend chaque module prêt pour un éventuel découpage en microservices, sans aucun type partagé. Plutôt que d’être exposé sous forme de module partagé (shared module), le package model a été purement et simplement supprimé.

Étape 4- Séparer l’API publique des détails d’implémentation

Spring Modulith attribue un rôle bien défini à chaque package :

1. Le package racine du module (ex : vet/) expose l’API publique : les types que les autres modules ont le droit d’utiliser
2. Les sous-packages (ex : vet/internal/) sont considérés comme internes : leur utilisation est interdite depuis les autres modules

Pour chaque module de Spring Petclinic, j’ai donc commencé par déplacer les classes d’implémentation — contrôleurs, repositories, entités JPA dans un sous-package nommé internal (nom de package donné par convention, mais tout autre nommage est possible). A ma grande surprise, le package racine de chaque module était vide : les 3 modules étaient parfaitement découplés.

Les classes de test suivent la même organisation. Trivial, ce refactoring peut paraitre déroutant. Il présente pourtant un gain immédiat : on rend explicite ce qui relève de l’API publique du module et ce qui est un détail d’implémentation. Et c’est Spring Modulith qui garantit que cette frontière est respectée via le test verify().

Dans un module applicatif, le développeur est libre d’organiser le code comme il l’entend. Chaque module peut d’ailleurs avoir sa propre organisation : découpage en couches techniques pour l’un, architecture hexagonale pour l’autre.
Dans Petclinic, le package internal du module owner contenait 13 classes à plat. Cela fait beaucoup. On s’éloigne du SRP. J’ai ainsi fait le choix de ventiler ces classes dans 3 packages différents : ui, application et domain.

Étape 5 – Communication par événements entre modules

La communication par évènements est une fonctionnalité phare de Spring Modulith qu’on peut utiliser en déclarant l’artefact spring-modulith-events-api :

<dependency> 
  <groupId>org.springframework.modulith</groupId> 
  <artifactId>spring-modulith-events-api</artifactId> </dependency>

<dependency> 
  <groupId>org.springframework.modulith</groupId> 
  <artifactId>spring-modulith-events-api</artifactId> </dependency>

Pour illustrer ce mécanisme, j’ai ajouté à Spring Petclinic un nouveau cas d’utilisation métier : lorsqu’un rendez-vous est réservé, le système affecte automatiquement le vétérinaire le moins chargé.

Plutôt que d’injecter un bean du module vet dans le module owner, on remplace l’appel direct d’une méthode par la publication d’un événement applicatif. Lors de la réservation d’un rendez-vous, la classe VisitScheduler utilise la classe ApplicationEventPublisher de Spring Framework pour émettre l’évènement VisitBooked.

@Transactional
public void bookVisit(Owner owner, Integer petId, Visit visit) {
    Owner managedOwner = owners.findById(owner.getId()).orElseThrow();
    managedOwner.addVisit(petId, visit);
    owners.flush();
    eventPublisher.publishEvent(new VisitBooked(visit.getId(), petId, visit.getDate()));
}

@Transactional
public void bookVisit(Owner owner, Integer petId, Visit visit) {
    Owner managedOwner = owners.findById(owner.getId()).orElseThrow();
    managedOwner.addVisit(petId, visit);
    owners.flush();
    eventPublisher.publishEvent(new VisitBooked(visit.getId(), petId, visit.getDate()));
}

Le record VisitBook fait partie de l’interface publique du module owner. On le déclare donc au niveau du package racine du module owner :

package org.springframework.samples.petclinic.owner;

public record VisitBooked(int visitId, int petId, LocalDate date) {
}

package org.springframework.samples.petclinic.owner;

public record VisitBooked(int visitId, int petId, LocalDate date) {
}

La classe VetEventListener du module vet réagit à cet événement via l’annotation @ApplicationModuleListener de Spring Modulith :

@Component
class VetEventListener {

    private final VetRoster vetRoster;

    VetEventListener(VetRoster vetRoster) {
       this.vetRoster = vetRoster;
    }

    @ApplicationModuleListener
    void on(VisitBooked event) {
       vetRoster.assignVet(event);
    }
}

@Component
class VetEventListener {

    private final VetRoster vetRoster;

    VetEventListener(VetRoster vetRoster) {
       this.vetRoster = vetRoster;
    }

    @ApplicationModuleListener
    void on(VisitBooked event) {
       vetRoster.assignVet(event);
    }
}

L’annotation @ApplicationModuleListener (source: spring-modulith-events-api) est un sucre syntaxique combinant trois annotations en une : @Async (source: spring-context), @Transactional (source: spring-tx) et @TransactionalEventListener (source: spring-tx). Ce listener s’exécute après le commit de la transaction émettrice, dans une nouvelle transaction, de façon asynchrone. Le module owner ne connaît pas le module vet. Le découplage est garanti par la structure des packages.

La mise à jour du tableau de garde des vétérinaires est assurée par le service VetRoster. L’affectation est persistée dans une nouvelle table visit_assignments qui appartient conceptuellement au module vet.

CREATE TABLE IF NOT EXISTS visit_assignments (
  visit_id   INT  NOT NULL PRIMARY KEY,
  vet_id     INT  NOT NULL REFERENCES vets (id),
  visit_date DATE NOT NULL
);

CREATE TABLE IF NOT EXISTS visit_assignments (
  visit_id   INT  NOT NULL PRIMARY KEY,
  vet_id     INT  NOT NULL REFERENCES vets (id),
  visit_date DATE NOT NULL
);

Notez ici un point important : la colonne visit_id de cette table est une référence lâche, intentionnellement sans clé étrangère vers la table visits du module owner. C’est le miroir en base de données du découplage Java : le module vet ne connaît que l’identifiant publié dans l’événement VisitBooked, pas l’entité Visit elle-même. Les modules communiquent par identifiants, pas par références d’objets ni par clés étrangères croisées.

Étape 6 – Déclarer les dépendances autorisées

Cette étape permet de donner un nom au système et de déclarer explicitement les dépendances inter-modules autorisées. Deux annotations entrent ici en jeu : @Modulithic et@ApplicationModule.

On commencer par annoter la classe main de l’application Petclinic avec @Modulithic :

@Modulithic(systemName = "PetClinic")
@SpringBootApplication
public class PetClinicApplication { ...}

@Modulithic(systemName = "PetClinic")
@SpringBootApplication
public class PetClinicApplication { ...}

Puis, dans les fichiers package-info.java de chaque module, on utilise @ApplicationModule :

// owner/package-info.java — aucune dépendance
@ApplicationModule
package org.springframework.samples.petclinic.owner;

// vet/package-info.java — dépend du module owner
@ApplicationModule(allowedDependencies = { "owner" })
package org.springframework.samples.petclinic.vet;

// system/package-info.java — aucune dépendance
@ApplicationModule
package org.springframework.samples.petclinic.system;

// owner/package-info.java — aucune dépendance
@ApplicationModule
package org.springframework.samples.petclinic.owner;

// vet/package-info.java — dépend du module owner
@ApplicationModule(allowedDependencies = { "owner" })
package org.springframework.samples.petclinic.vet;

// system/package-info.java — aucune dépendance
@ApplicationModule
package org.springframework.samples.petclinic.system;

Ces garde-fous architecturaux sont ici exploités par le ModularityTests. Si un développeur (ou un agent de codage) introduit une dépendance non autorisée, le test échoue immédiatement.

Étape 7 — L’Event Publication Registry

Sans harnais de sécurité, un événement publié mais dont le listener échoue serait perdu à jamais. L’Event Publication Registry résout ce problème en persistant chaque événement en base de données avant l’exécution du listener.
Spring Modulith supporte 4 technologies de persistance : JDBC, JPA, MongoDB et Neo4j.
Bien que Spring Petclinic repose sur des repositories Spring Data JPA, j’ai choisi d’exploiter le support JDBC de Spring Modulith. Compatible JPA, il propose la propriété spring.modulith.events.jdbc.schema-initialization.enabled permettant de créer la table event_publication.

La mise en place tient en une dépendance :

<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-starter-jdbc</artifactId>
</dependency>

<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-starter-jdbc</artifactId>
</dependency>

Et trois propriétés dans le fichier de configuration application.properties :

# Crée automatiquement la table event_publication au démarrage
spring.modulith.events.jdbc.schema-initialization.enabled=true

# Supprime les publications complétées immédiatement
spring.modulith.events.completion-mode=DELETE

# Re-publie les événements non traités au redémarrage
spring.modulith.events.republish-outstanding-events-on-restart=true

# Crée automatiquement la table event_publication au démarrage
spring.modulith.events.jdbc.schema-initialization.enabled=true

# Supprime les publications complétées immédiatement
spring.modulith.events.completion-mode=DELETE

# Re-publie les événements non traités au redémarrage
spring.modulith.events.republish-outstanding-events-on-restart=true

Spring Modulith intercepte chaque appel à publishEvent() et insère une ligne dans la table event_publication au sein de la transaction initiale. Si le listener s’exécute avec succès, l’entrée est supprimée (mode DELETE). Si le listener échoue ou si l’application crashe, l’entrée reste en base et sera rejouée au redémarrage de Petclinic. Cette garantie at-least-once delivery fonctionne sans infrastructure externe : pas besoin de Kafka, de RabbitMQ ni de quelconque broker de messages. Un simple SGBD relationnel suffit.

Étape 8 – Moments : les événements temporels

Spring Modulith propose un module spring-modulith-moments qui publie automatiquement des événements marquant le passage du temps : HourHasPassed, DayHasPassed, WeekHasPassed, etc. C’est une alternative élégante aux classiques @Scheduled de Spring.

Sur notre application, le module vet utilise l’évènement DayHasPassed pour nettoyer quotidiennement les affectations aux vétérinaires dont la date est passée. Dans la classe VetEventListener, on déclare une seconde méthode :

@EventListener
void on(DayHasPassed event) {
    vetRoster.cleanupPastAssignments(event.getDate());
}

@EventListener
void on(DayHasPassed event) {
    vetRoster.cleanupPastAssignments(event.getDate());
}

Notez l’utilisation de l’annotation Spring Framework @EventListener (et non @ApplicationModuleListener) : l’événement DayHasPassed est publié par Spring Modulith lui-même en dehors de toute transaction applicative.

Étape 9 – Tests d’intégration modulaires

La modularité apportée par Spring Modulith présente un autre avantage : sa capacité à bootstrapper un seul module en isolation. L’annotation @ApplicationModuleTest remplace ainsi @SpringBootTest et ne charge que le contexte application Spring nécessaire au module dans lequel le test se trouve. En théorie, le temps d’exécution du test devrait être amélioré.

Exemple d’utilisation sur le test VisitSchedulerTests :

@ApplicationModuleTest
class VisitSchedulerTests {

    @Autowired
    OwnerRepository owners;

    @Autowired
    VisitScheduler visitScheduler;

    @Test
    void bookVisitShouldPublishVisitBookedEvent(Scenario scenario) {
       // Given
       Owner owner = owners.findById(1).orElseThrow();
       Pet pet = owner.getPets().iterator().next();
       Visit visit = new Visit();
       visit.setDescription("Annual checkup");

       // When / Then
       scenario.stimulate(() -> visitScheduler.bookVisit(owner, pet.getId(), visit))
          .andWaitForEventOfType(VisitBooked.class)
          .matching(event -> event.petId() == pet.getId())
          .toArriveAndVerify(event -> then(event.petId()).isEqualTo(pet.getId()));
    }

}

@ApplicationModuleTest
class VisitSchedulerTests {

    @Autowired
    OwnerRepository owners;

    @Autowired
    VisitScheduler visitScheduler;

    @Test
    void bookVisitShouldPublishVisitBookedEvent(Scenario scenario) {
       // Given
       Owner owner = owners.findById(1).orElseThrow();
       Pet pet = owner.getPets().iterator().next();
       Visit visit = new Visit();
       visit.setDescription("Annual checkup");

       // When / Then
       scenario.stimulate(() -> visitScheduler.bookVisit(owner, pet.getId(), visit))
          .andWaitForEventOfType(VisitBooked.class)
          .matching(event -> event.petId() == pet.getId())
          .toArriveAndVerify(event -> then(event.petId()).isEqualTo(pet.getId()));
    }

}

Notez ici l’utilisation de l’API Scenario de Spring Modulith Test. On définit un stimulus (l’appel à bookVisit), on déclare l’événement attendu (VisitBooked), on pose un critère de correspondance (matching) et on vérifie. Le tout de manière fluide.

Les logs d’exécution du test donnent un aperçu des beans Spring chargés par @ApplicationModuleTest :

Bootstrapping @org.springframework.modulith.test.ApplicationModuleTest for Owner in mode STANDALONE (class org.springframework.samples.petclinic.PetClinicApplication)…

# Owner
> Logical name: owner
> Base package: org.springframework.samples.petclinic.owner
> Excluded packages: none
> Direct module dependencies: none
> Spring beans:
o ….application.VisitScheduler
o ….domain.OwnerRepository
o ….domain.PetTypeRepository
o ….ui.OwnerController
o ….ui.PetController
o ….ui.PetTypeFormatter
o ….ui.VisitController

Appartenant au module system, la classe de test existante CrashControllerIntegrationTests a pu bénéficier de l’annotation @ApplicationModuleTest.
Contrairement à @SpringBootTest, @ApplicationModuleTest n’expose pas d’attribut properties. Cette limitation a pu être contournée grâce à l’annotation TestPropertySource de Spring Test.

// Avant
@SpringBootTest(webEnvironment = RANDOM_PORT,
       properties = { "spring.web.error.include-message=ALWAYS", "management.endpoints.access.default=none" })
@AutoConfigureTestRestTemplate
class CrashControllerIntegrationTests {

// Après
@ApplicationModuleTest(webEnvironment = RANDOM_PORT)
@TestPropertySource(
       properties = { "spring.web.error.include-message=ALWAYS", "management.endpoints.access.default=none" })
@AutoConfigureTestRestTemplate
class CrashControllerIntegrationTests {

// Avant
@SpringBootTest(webEnvironment = RANDOM_PORT,
       properties = { "spring.web.error.include-message=ALWAYS", "management.endpoints.access.default=none" })
@AutoConfigureTestRestTemplate
class CrashControllerIntegrationTests {

// Après
@ApplicationModuleTest(webEnvironment = RANDOM_PORT)
@TestPropertySource(
       properties = { "spring.web.error.include-message=ALWAYS", "management.endpoints.access.default=none" })
@AutoConfigureTestRestTemplate
class CrashControllerIntegrationTests {

Contrairement à ce dont on pouvait s’attendre, le temps d’exécution a légèrement augmenté, passant en moyenne de 500 à 520 ms. La détection des beans du module explique sans doute cet overhead. A vérifier sur d’autres testes, dans d’autres applications plus conséquentes.

Étape 10 – Génération de documentation

Spring Modulith permet de générer automatiquement de la documentation à partir du modèle de modules. Il suffit d’ajouter l’artefact spring-modulith-docs dans le pom.xml puis d’enrichir notre classe ModularityTests :

@Test
void writeDocumentation() {
    new Documenter(modules).writeDocumentation();
}

@Test
void writeDocumentation() {
    new Documenter(modules).writeDocumentation();
}

L’appel à writeDocumentation() produit dans le répertoire target/spring-modulith-docs/ :

1. Des diagrammes C4 au format PlantUML (.puml) représentant les relations entre modules
2. Des « modules Canvas » au format AsciiDoc (.adoc) listant pour chaque module : les beans Spring exposés (non visible sur Petclinic) ainsi que les événements publiés et écoutés
3. Un document de synthèse (all-docs.adoc) agrégeant l’ensemble des diagrammes et canvas
   

Exemple de rendu du fichier module-vet.puml :

Exemple de rendu du fichier module-vet.adoc :

L’intérêt de cette living documentation est double : le rendu de l’architecture du code est rendu sous nos yeux et la documentation reste synchronisée avec le code sans effort supplémentaire.
Cela dit, dans une application d’entreprise, je vous recommande de ne pas regénérer systématiquement la doc à chaque exécution du build Maven, mais à la demande lorsque vous (ou votre agent IA) avez besoin de publier ou consulter la doc.

Étape 11 – l’endpoint Actuator

Cette dernière étape consiste exposer le graphe de modules au runtime. Deux dépendances Maven sont nécessaires :

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

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

Un appel GET sur l’URL http://localhost:8080/actuator/modulith renvoie le graphe complet des modules au format JSON : noms, packages et dépendances. Cette sonde est pratique pour visualiser l’architecture de l’application déployée sans avoir besoin d’aller regarder le code ou la documentation. En production, pensez néanmoins à désactiver ou sécuriser cet actuator.

{
  "owner": {
    "displayName": "Owner",
    "basePackage": "org.springframework.samples.petclinic.owner",
    "nested": [],
    "type": "closed",
    "shared": false,
    "namedInterfaces": {
      "<<UNNAMED>>": [
        "org.springframework.samples.petclinic.owner.VisitBooked"
      ]
    },
    "initializers": [],
    "dependencies": []
  },
  "system": {
    "displayName": "System",
    "basePackage": "org.springframework.samples.petclinic.system",
    "nested": [],
    "type": "closed",
    "shared": false,
    "namedInterfaces": {
      "<<UNNAMED>>": []
    },
    "initializers": [],
    "dependencies": []
  },
  "vet": {
    "displayName": "Vet",
    "basePackage": "org.springframework.samples.petclinic.vet",
    "nested": [],
    "type": "closed",
    "shared": false,
    "namedInterfaces": {
      "<<UNNAMED>>": []
    },
    "initializers": [],
    "allowedDependencies": [
      "owner"
    ],
    "dependencies": [
      {
        "target": "owner",
        "types": [
          "EVENT_LISTENER"
        ]
      }
    ]
  }
}

{
  "owner": {
    "displayName": "Owner",
    "basePackage": "org.springframework.samples.petclinic.owner",
    "nested": [],
    "type": "closed",
    "shared": false,
    "namedInterfaces": {
      "<<UNNAMED>>": [
        "org.springframework.samples.petclinic.owner.VisitBooked"
      ]
    },
    "initializers": [],
    "dependencies": []
  },
  "system": {
    "displayName": "System",
    "basePackage": "org.springframework.samples.petclinic.system",
    "nested": [],
    "type": "closed",
    "shared": false,
    "namedInterfaces": {
      "<<UNNAMED>>": []
    },
    "initializers": [],
    "dependencies": []
  },
  "vet": {
    "displayName": "Vet",
    "basePackage": "org.springframework.samples.petclinic.vet",
    "nested": [],
    "type": "closed",
    "shared": false,
    "namedInterfaces": {
      "<<UNNAMED>>": []
    },
    "initializers": [],
    "allowedDependencies": [
      "owner"
    ],
    "dependencies": [
      {
        "target": "owner",
        "types": [
          "EVENT_LISTENER"
        ]
      }
    ]
  }
}

Conclusion

Vous l’aurez vu : intégrer Spring Modulith dans Spring Petclinic s’est fait facilement et de manière très progressive. Un projet d’entreprise n’exploitera pas nécessairement toutes les fonctionnalités présentées dans cet article. Seules les étapes 1 à 5 sont obligatoires. Le fait de pouvoir ouvrir certains sous-packages à d’autres modules permet d’intégrer Spring Modulith dans des applications legacy, le temps de refactorer le code. D’expérience, le plus simple consiste néanmoins à intégrer Spring Modulith dès la mise en œuvre de l’architecture logicielle d’un nouveau monolith modulaire.

Les 3 modules initiaux de Spring Petclinic étant isolés et indépendants, l’interface publique exposée par chaque module au travers son package racine ne présentait que peu d’intérêt. L’ajout de la fonctionnalité d’affectation automatique d’un vétérinaire à un futur rendez-vous aura permis de montrer comment faire communiquer 2 modules à l’aide d ‘évènements puis de montrer comment utiliser l’Event Publication Registry. La base de données existante aura été réutilisée, facilitant son adoption (nul besoin d’infrastructure externe).

Ayant encore peu d’expérience avec Spring Modulith, je suis ouvert à toute proposition d’amélioration. Le code source du fork Spring Petclinic Modulith est disponible sur repo GitHub : spring-petclinic-modulith. Tous les changements apportés sont visibles à travers cet unique commit. N’hésitez pas à l’étudier, à expérimenter et à soumettre vos contributions à travers des issues et de Pull Requests.

Ressources

• spring-petclinic-modulith : le code source complet de la démo
• Documentation officielle de Spring Modulith
• Spring Modulith examples : les exemples fournis par l’équipe Spring
• Guide to Modulith with Spring Boot : article de blog de Piotr Mińkowski datant de 2023
• spring-modulith-with-ddd : code source d’une application Modular Monolith basée sur Spring Modulith et le Domain Driven Design
• Migrating to Modular Monolith using Spring Modulith and IntelliJ IDEA
• Monolith First : article de Martin Fowler datant de 2015
  

Dans son talk, Hoani nous présente le logiciel Obsidian, la manière dont il l’utilise au quotidien pour noter et gérer son activité, qu’elle soit professionnelle ou personnelle.
Je suis sorti de sa présentation quelque peu désarçonné. Hoani utilise Obsidian comme un Bullet Journal (qu’on appelle aussi « bujo ») numérique pour compiler notes, pense-bêtes, objectifs, rappels, tracking, plannings et coups de coeur. Son utilisation est vraiment avancée et très régulière. Je ne me voyais pas passer autant de temps que lui sur Obsidian.

L’autre domaine dans lequel Obsidian semble exceller consiste en la possibilité de se créer un un Second Cerveau. Les notes peuvent être reliées ensemble à l’aide de Map Of Content (MOC). Une alternative aux hashtags et l’organisation hiérarchisée en dossiers et sous-dossiers.
Une note de type Map of Content s’assimile à une thématique, un sujet principal, auquel on rattache bidirectionnellement des notes et qui va faire office de table de matières et de tableau de bord. La création de sous-MOCs spécialisés reste possible. On se rapproche du web, des liens hypertextes et du mind mapping.
Dans ce billet, j’aimerais vous restituer la prestation d’Hoani et vous laisser découvrir son utilisation Obsidian.

Du papier à Obsidian

Senior backend architect chez Sfeir, Hoani Cross nous explique avoir utilisé de nombreux carnets manuscrits pour apprendre et structurer sa pensée. Hoani pratique le Bullet Journal et son talk se veut être un partage de ses résultats après des années de pratiques.
Hoani commence par nous rappeler les bienfaits de prendre des notes :

• Ralentir pour assimiler, poser son téléphone pour se focaliser
• Graver dans la mémoire
• Transformer l’écoute en savoir, résumer avec ses propres mots
• Entraîner le cerveau : sport mental, reformulation, concentration
• Connecter des idées parfois éloignées les unes des autres
• Améliorer sa compréhension tout en construisant une bibliothèque personnelle (le fameux Second Cerveau)

Adepte du Bullet Journal (Bujo), Hoani a longtemps utilisé un carnet numéroté, un stylo et un index en début de carnet. Son carnet comportait une page par jour contenant des idées, des notes, le suivi des variables (énergie / humeur) et des sujets spéciaux. Pour s’y retrouver, il utilise des conventions de notation appelées Bullet Journal Key. Par exemple : un carré pour une tâche.
Première limitation : les Bujo ne permettent pas de faire de recherche textuelle.

Hoani a essayé de basculer sur des carnets numériques avec le reMarkable et a testé différents logiciels : OneNote, EverNote, Notion, Keep, Joplin. Nul n’est arrivé à la hauteur d’Obsidian qui est presque parfait pour les raisons suivantes :

• Basé sur le langage de balisage léger Markdown, ce qui permet à l’auteur de rester propriétaire de ses données
• Rendu basé le moteur web Electron (comme VS Code)
• Logiciel gratuit, créé pendant le confinement de la Covid19, mais pas Open Source
• Plus de 2 500 plugins OpenSource
• Multiplateforme : Windows, Linux, MacOS, Android, iOS

Obsidian intègre les fonctionnalités suivantes  :

• Coffre avec navigateur de fichiers : toutes les notes sont stockées localement dans un dossier (appelé « coffre »), consultable via un explorateur intégré.
• Éditeur de Markdown intelligent : éditeur fluide combinant texte brut et mise en forme instantanée, avec gestion des liens internes, blocs de code, formules et tableaux.
• Canvas pour composer ses notes : espace visuel libre pour organiser ses idées sous forme de cartes reliées, idéal pour le brainstorming et la modélisation de concepts.
• Gestion des daily notes : fonction de journal quotidien permettant de consigner rapidement pensées, tâches ou réflexions, avec génération automatique de notes datées.
• Diapositives : transformation instantanée d’une note en présentation interactive, pratique pour exposer un projet ou partager ses idées sans quitter Obsidian.
• Enregistrement audio : capture vocale intégrée pour enregistrer des idées, réunions ou commentaires, directement stockés et liés dans le coffre.
• Vue graphique de l’arborescence des notes : représentation visuelle du réseau de liens entre notes, offrant une cartographie claire et dynamique de son écosystème de connaissances.

L’une des forces du logiciel Obsidian réside dans le fait qu’il soit multiplafeforme : on peut commencer une note oralement sur son Smartphone puis la reprendre plus tard avec un clavier sur son laptop. Plusieurs techniques de synchronisation des coffres entre différents devices existent :

1. Offre de service intégré payant : Sync (4$ par mois)
2. Stockage Cloud avec iCloud, OneDrive, Google Drive
3. Syncthing (OSS) : synchronisation Peer-to-Peer de fichiers. Vos données ne sont jamais stockées dans le Cloud
4. Plugin Git (instable sur mobile) : personnellement, c’est ce dernier que j’utilise avec un repo GitHub privé.

À noter que l’utilisation d’un repo Git rend possible le partage en équipe d’un coffre Obsidian.

Utilisation d’Obsidian

Le coffre d’Hoani contient toutes ses données, tant personnelles que professionnelles. Cela peut poser un problème de confidentialité : faire sortir des données pros sur son ordi perso peut être contraire aux règles de sécurité de son entreprise.

L’organisation de son coffre comporte 8 grands dossiers :

• Notes persos
• Notes pros
• Notes de lecture (livres ou vidéo youtube)
• Notes non classées (temporaire)
• Second Brain : wiki perso
• Bullet Journal (Bujo)
• Archives
• Templates

Chaque note .md suit la structuration suivante :

• En-tête en front matter pour ajouter des méta-données
• Corps en Markdown
• Tags hiérarchisés

Le tableau suivant présente la syntaxe Markdown supportée par Obsidian :

Dans son dossier Bujo, Hoani s’appuie sur le plugin Periodic Notes pour gérer ses notes périodiques et les hiérarchise en année / trimestre / mois / jours.

Le plugin Tasks permet de gérer les tâches dans Obsidian. La syntaxe Markdown [x] et [] permet de reconnaitre une tâche terminée d’une tâche à faire. L’utilisation d’Emojis est possible pour les méta-données.
A noter la possibilité de créer des tableaux dynamiques à l’aide de requête, par exemple pour créer une liste de TODO à faire aujourd’hui.

Son daily est centré autour d’une simple bullet list renseignée tout au long de la journée.
Chaque sujet commence par un tag (ex : #perso, #tech). Hoani utilise les sous-listes pour détailler le sujet.
Chaque jour, Hoani ouvre son Daily du jour et

• Regarde les tâches à réaliser
• Note en bullet list
• Crée une tâche quand nécessaire
• Termine les tâches accomplies

Le bénéfice du numérique

Comparé au manuscrit, les bénéfices du numérique sont nombreux :

• Personnaliser son daily en ajoutant toutes les infos qui lui passent par la tête
• Suivre des variables quotidiennes (comme le temps passé à s’entrainer au Kendama)
• Afficher les tâches à réaliser et être notifié de celles en retard
• Automatiser certains traitements à l’aide de plugins additionnels : Templater, Tasks et Dataview

Le contenu du Daily peut être très riche et comporter :

• Métadonnées avec tags
• Cartouche de navigation
• Widgets de progression mois/année
• Définition de la tâche ultime de la journée
• Rappel des tâches via un filtre de recherche et un report facilité des tâches
• Le journal en lui-même
  – Entrainement au Kendama
• Des métriques sur livres (page en cours) et jeux vidéo (temps, winrate)

Exemples de métadonnées d’un Daily permettant de suivre des variables quotidiennes :

energy_level_morning : 6
energy_level_evening : 7
mood_morning : insomniaque
mood_evening : détendu
walked : 400
working_place_morning : HOME

La barre de navigation du Daily permet de passer rapidement du daily précédent au suivant, à la semaine associée …
L’ajout de barres de progression est possible via le plugin Progressbar.

Le numérique permet de créer d’autres types de notes périodiques que le daily. On peut, par exemple, se fixer des objectifs annuels (ex: courir un marathon), suivre visuellement leurs avancements puis, une fois la période écoulée, faire un bilan de la période et définir de nouveaux objectifs. Hoani insiste sur le fait que l’ouverture et la fermeture d’une période doit être vécue comme un rituel.
Pour automatiser la création de ces différentes notes périodiques, on peut s’aider du plugin Templater qui ajoute à Obsidian un langage de templating permettant d’exécuter des fonctions JavaScript. Ce plugin permet de pré-sélectionner un template en fonction du nom du fichier créé.

Conclusion

Après la démonstration de son utilisation avancée d’Obsidian, Hoani reconnaît que le démarrage peut être long, qu’il peut être difficile de décider quoi noter et surtout comment organiser son coffre. Son conseil est de rester rigoureux, y noter ce que l’on souhaite et faire en sorte que cela reste amusant et donc pas une corvée. Ses slides sont en ligne : [Devfest Nantes 25] Révolutionnez votre prise de notes – du Bullet Journal à Obsidian. Son repo GitHub rend public ses templates Obsidian.

Dépendance Maven JSpecify

Ajoutez simplement la dépendance suivante au niveau de la balise <dependencies> de votre pom.xml :

<dependency>
    <groupId>org.jspecify</groupId>
    <artifactId>jspecify</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>org.jspecify</groupId>
    <artifactId>jspecify</artifactId>
    <version>1.0.0</version>
</dependency>

A ce stade, les IDE comme IntelliJ supportant JSpecify seront à même de détecter des erreurs. Exemple extrait de Sring Petclinic dont les packages Java sont annotés avec @NullMarked :

Dans le cas où ces warnings n’apparaissent pas dans IntelliJ, vérifier que les inspections Nullability problems sont bien activées :

Configuration du Maven Compiler Plugin avec NullAway et ErrorProne

Pour faire échouer le build Maven dans le cas où un développeur ne respecterait pas les annotations JSpecify, le compilateur Java doit être strictement configuré à l’aide des plugins Error Prone de Google et de son extension NullAway d’Uber :

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-compiler-plugin</artifactId>
 <configuration>
   <parameters>true</parameters>
   <compilerArgs>
     <arg>-XDcompilePolicy=simple</arg>
     <arg>--should-stop=ifError=FLOW</arg>
     <arg>-XDaddTypeAnnotationsToSymbol=true</arg>
     <arg>-Xplugin:ErrorProne
       -XepOpt:NullAway:AnnotatedPackages=com.javaetmoi.myapp
       -XepOpt:NullAway:UnannotatedSubPackages=com.javaetMoi.myapp.controller.api,com.javaetMoi.myapp.controller.dto 
       -XepOpt:NullAway:JSpecifyMode=true
       -XepDisableAllChecks
       -Xep:NullAway:ERROR
       -XepExcludedPaths:.*/src/test/java/.*
       -XepDisableWarningsInGeneratedCode
     </arg>
   <annotationProcessorPaths>
     <path>
       <groupId>com.google.errorprone</groupId>
       <artifactId>error_prone_core</artifactId>
       <version>2.42.0</version>
     </path>
     <path>
       <groupId>com.uber.nullaway</groupId>
       <artifactId>nullaway</artifactId>
       <version>0.12.11</version>
     </path>
   </annotationProcessorPaths>
 </configuration>
</plugin>

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-compiler-plugin</artifactId>
 <configuration>
   <parameters>true</parameters>
   <compilerArgs>
     <arg>-XDcompilePolicy=simple</arg>
     <arg>--should-stop=ifError=FLOW</arg>
     <arg>-XDaddTypeAnnotationsToSymbol=true</arg>
     <arg>-Xplugin:ErrorProne
       -XepOpt:NullAway:AnnotatedPackages=com.javaetmoi.myapp
       -XepOpt:NullAway:UnannotatedSubPackages=com.javaetMoi.myapp.controller.api,com.javaetMoi.myapp.controller.dto 
       -XepOpt:NullAway:JSpecifyMode=true
       -XepDisableAllChecks
       -Xep:NullAway:ERROR
       -XepExcludedPaths:.*/src/test/java/.*
       -XepDisableWarningsInGeneratedCode
     </arg>
   <annotationProcessorPaths>
     <path>
       <groupId>com.google.errorprone</groupId>
       <artifactId>error_prone_core</artifactId>
       <version>2.42.0</version>
     </path>
     <path>
       <groupId>com.uber.nullaway</groupId>
       <artifactId>nullaway</artifactId>
       <version>0.12.11</version>
     </path>
   </annotationProcessorPaths>
 </configuration>
</plugin>

Explications clés :

• L’option -Xep:NullAway:ERROR fait échouer le build Maven lorsqu’un éventuel NullPointerException est détecté. Par défaut, de simples WARNING sont générés dans la console et risquent donc de passer inaperçus.
  
• L’option –Xplugin:ErrorProne active le plugin ErrorProne.
  
• L’option -XepDisableAllChecks désactive toutes les règles de vérification de code ErrorProne. On n’utilise ici ErrorProne que pour la nullsafety. Libre à vousd’utiliser pleinement ErrorProne ou pas.
  
• L’option -XepOpt:NullAway:AnnotatedPackages=com.javaetmoi.myapp active NullAway sur le package Java racine de l’application métier. A noter que cette option peut être remplacer par -XepOpt:NullAway:OnlyNullMarked afin de ne scanner que les packages annotés avec @NullMarked.
  
• A contrario, l’option -XepOpt:NullAway:UnannotatedSubPackages=com.javaetMoi.myapp.controller.api,com.javaetMoi.myapp.controller.dto désactive NullAway sur une liste de sous-packages. Cela permet d’exclure le code généré par des plugins comme cxf-codegen-plugin ou MapStruct qui ne supportent pas encore JSpecify.
  
• Dans le cadre d’utilisation de JSpecify dans un projet legacy, il peut-être intéressant d’exclure de l’analsyse les classes de tests avec l’option -XepExcludedPaths:.*/src/test/java/.*
  
• L’option -XepOpt:NullAway:JSpecifyMode=true active le support complet de JSpecify et exploite pleinement la sémantique de JSpecify, notamment au niveau des types génériques. 
  
• L’argument javac -XDaddTypeAnnotationsToSymbol=true est requis par la version 0.12.11 de NullAway lors de l’utilisation d’une version de Java antérieure à Java 22.

Toutes les options de NullAway peuvent être retrouvées sur sa page de Configuration.

A partir de la version 16 du langage Java, la documentation d’installation d’error prone explique comment activer des flags à la JVM via le fichier .mvn/jvm.config :

--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
--add-opens jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
--add-opens jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED

--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
--add-opens jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
--add-opens jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED

Avec cette configuration Maven, toute tentative d’accès à une référence potentiellement nulle sera détectée… dès la compilation, que ce soit sur notre poste de dév ou notre CI Jenkins, GitHub ou GitLab ! Fini les NullPointerException surprises en production.

Exemple d’une commande mvn compile sur l’exemple précédent :

[ERROR] COMPILATION ERROR : 
[INFO] -------------------------------------------------------------
[ERROR] /Users/arey/Dev/GitHub/spring-petclinic/spring-petclinic/src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java:[106,82] [NullAway] passing @Nullable parameter 'lastName' where @NonNull is required
    (see http://t.uber.com/nullaway )

[ERROR] COMPILATION ERROR : 
[INFO] -------------------------------------------------------------
[ERROR] /Users/arey/Dev/GitHub/spring-petclinic/spring-petclinic/src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java:[106,82] [NullAway] passing @Nullable parameter 'lastName' where @NonNull is required
    (see http://t.uber.com/nullaway )

Conclusion

Cinq années auront été nécessaires par le groupe de travail JSpecify pour formaliser et se mettre d’accord sur quatre annotations Java. Depuis un an, nos outillages, nos IDE et nos frameworks convergent vers ce lot d’annotations. Quelques bugs de jeunesse existent encore, à l’image de ce bug Maven Build Cache Extension corrigé par mon collègue Marco et qui faisait échouer la synchronisation Maven IntelliJ avec le message « java: plug-in not found: ErrorProne ».

A nos projets métiers de se mettre à JSpecify et d’être prêts pour Spring Framework 7 et Spring Boot 4 qui sortiront fin 2025.
Si vos projets exploitent les annotations JSR-305 ou JetBrains, migrez vers JSpecify à l’aide de la recette OpenRewrite MigrateToJSpecify.

Sachez enfin que Dan Smith a proposé la JEP draft: Null-Restricted and Nullable Types (Preview) visant à ajouter des marqueurs syntaxiques directement au niveau du langage Java. Adopter JSpecify aujourd’hui facilitera l’adoption de cette JEP.

L’usage de jOOQ se rapproche de l’utilisation de JdbcTemplate. Le développeur maitrise le nombre de requêtes envoyées à la base de données relationnelle. Ce qui les différencie, c’est la syntaxe : pas de SQL, mais une API Java fluide et type-safe spécifique à jOOQ qu’il va falloir appréhender. Rassurez-vous, cette API se rapproche du SQL : on y retrouve les mots clés select, update, insertInto, where, from, join, on, as … A ceux-ci, on ajoute des mots clés spécifiques à jOOQ : paginate, fetch, convertFrom … La documentation de jOOQ est très complète. On y apprend comment écrire des requêtes complexes à base de window function ou de Common Table Expressions (CTE) et comment utiliser des fonctionnalités avancées de SQL que peu de frameworks ORM supportent nativement : JSON functions, PIVOT, MERGE, UNION …

Cet article a pour objectif d’expliquer les étapes adoptées pour migrer l’implémentation Spring Data JPA des repository vers jOOQ. Des exemples de code avant / après y sont proposés.

Configuration du build

Spring Boot supporte nativement l’usage des versions commerciales et Open Source de jOOQ. Dans le pom.xml ou le fichier build.gradle, commencer par déclarer le starter Spring Boot pour jOOQ spring-boot-starter-jooq :

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jooq</artifactId>
</dependency>

L’étape suivante consiste à générer les classes Java à partir du schéma de la base de données. jOOQs propose différentes possibilités : à partir du script DDL de création du schéma comme sur Petclinic, de scripts Liquibase ou bien encore des méta-données d’une base existante.
Les plugins jooq-codegen-maven ou jooq-codegen-gradle sont à configurer.
Voici un exemple extrait de jOOQ Spring Petclinic :

<plugin>
  <groupId>org.jooq</groupId>
  <artifactId>jooq-codegen-maven</artifactId>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <generator>
      <database>
        <name>org.jooq.meta.extensions.ddl.DDLDatabase</name>
        <properties>
          <property>
            <key>scripts</key>
            <value>src/main/resources/db/h2/schema.sql</value>
          </property>
          <property>
            <key>sort</key>
            <value>semantic</value>
          </property>
          <property>
            <key>unqualifiedSchema</key>
            <value>none</value>
          </property>
          <property>
            <key>defaultNameCase</key>
            <value>as_is</value>
          </property>
        </properties>
      </database>
    </generator>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.jooq</groupId>
      <artifactId>jooq-meta-extensions</artifactId>
      <version>${jooq-meta-extensions.version}</version>
    </dependency>
  </dependencies>
</plugin>

La classe org.jooq.meta.extensions.ddl.DDLDatabase provenant de l’extension jooq-meta-extensions permet au plugin jooq-codegen-maven d’exploiter le script DDL src/main/resources/db/h2/schema.sql utilisé par défaut lors du démarrage de l’application avec le profil Spring par défaut.

Dans le package org.jooq.generated.tables, l’exécution du plugin jOOQ génère une classe Vets héritant de la classe TableImpl<VetsRecord> et modélisant la table éponyme. La classe VetsRecord a également été générée dans le sous-package records. Elle représente une ligne de la table pets.
Nous verrons leurs usages lors de la migration de la classe PetRepository.

Migration des repositories

L’une des forces de jOOQ est qu’il sait cohabiter aux côtés de JPA. On peut donc migrer au fil de l’eau les respositories d’une application et même choisir de conserver les 2 solutions en fonction des besoins. Cette capacité a été pratique dans le travail de migration : chaque repository a été migré l’un après l’autre. L’application Petclinic est restée fonctionnelle tout du long.

Premier changement notable : la nature des repositories qui passent d’une interface héritant de l’interface Repository de Spring Data JPA à une classe concrète qu’on annote avec @Repository et dont le constructeur accepte une instance de DSLContext.

Avant :

public interface VetRepository extends Repository<Vet, Integer> {

Après:

@Repository
public class VetRepository {

    private final DSLContext dsl;

    public VetRepository(DSLContext dslContext) {
       this.dsl = dslContext;
    }

Continuons par changer l’implémentation d’une première requête SQL simple utilisant un SELECT.
Requête native SQL utilisée par Spring Data JPA :

@Query("SELECT ptype FROM PetType ptype ORDER BY ptype.name")
List<PetType> findPetTypes();

Implémentation équivalente avec jOOQ :

public List<PetType> findPetTypes() {
    return dsl
       .selectFrom(TYPES)
       .orderBy(TYPES.NAME)
       .fetchInto(PetType.class);
}

On retrouve ici tous les éléments de la requête SQL, mais avec une syntaxe Java jOOQ équivalente. Le mot clé SQL « SELECT » est remplacé par la méthode selectFrom(), le « ORDER BY » par la méthode orderBy(). A noter que nous n’utilisons pas de chaines de caractères pour nommer les tables et les colonnes, mais les constantes générées par le plugin jOOQ. Ainsi, en cas de changement de schéma (ex : nom de colonne renommée), le code Java ne compilera plus et il faudra l’adapter. Avec cette approche, les erreurs de syntaxe ne sont plus possibles. On perçoit ici toute la sécurité apportée par la type-safety de jOOQ.
Enfin, la méthode fetchInto() mappe les lignes retournées par la base dans une liste d’instance de PetType.

Là où JPA et Hibernate nous facilitaient la sauvegarde de nos entités JPA, jOOQ va demander un travail nettement plus important. En effet, la méthode save() de l’interface CrudRepository de Spring Data JPA ne demandait qu’à être appelée. La magie des ORM opérait grâce aux annotations JPA apposées sur les entités. jOOQ nécessite de prévoir les 2 requêtes SQL correspondantes et d’effectuer à la main le binding des propriétés du Owner vers les colonnes. Exemple de sauvegarde d’un Owner :

public Integer saveOrUpdateDetails(Owner owner) {
    if (owner.isNew()) {
       return requireNonNull(
          dsl.insertInto(OWNERS)
             .set(mapOwnerToRecord(owner))
             .returningResult(OWNERS.ID)
             .fetchOne())
          .getValue(OWNERS.ID);
    } else {
       dsl.update(OWNERS)
          .set(mapOwnerToRecord(owner))
          .where(OWNERS.ID.eq(owner.getId()))
          .execute();
       return owner.getId();
    }
}

private Map<Field<?>, Object> mapOwnerToRecord(Owner owner) {
    return Map.of(OWNERS.FIRST_NAME, owner.getFirstName(), OWNERS.LAST_NAME, owner.getLastName(), OWNERS.ADDRESS,
       owner.getAddress(), OWNERS.CITY, owner.getCity(), OWNERS.TELEPHONE, owner.getTelephone());
}

Rien de compliqué, mais un peu plus verbeux.
L’un des principaux avantages de jOOQ consiste à maitriser le nombre de requêtes SQL envoyées à la base. En l’occurrence, dans cet exemple, une seule et unique requête de type UPDATE est envoyée lors d’un mise à jour.
Avec l’implémentation Spring Data JPA, dans le cadre de la mise à jour d’un Owner, comme expliqué dans l’article Skip Select Before Insert in Spring Data JPA, Spring Data JPA appelle la méthode merge() de l’entity manager JPA qui, si l’entité n’est pas en cache, va charger le Owner en exécutant autant de requêtes SQL de type SELECT que nécessaires.

Autre différence notable : jOOQ laisse décider du ou des champs à mettre à jour. Dans notre exemple, les Pets associés à leur Owner ne seront par exemple pas mis à jour. Avec JPA, on utilisait le cascading et l’attribut cascade des annotations comme @OneToMany.

Dans la même idée, lors de requêtes de type SELECT, les jointures entre tables devront être systématiquement précisées. A titre d’exemple, charger un animal et son type nécessitera un appel à join() :

@Transactional(readOnly = true)
public Optional<Pet> findByIdWithoutVisits(Integer petId) {
    return dsl.select()
       .from(PETS)
       .join(PETS.types_())
       .where(PETS.ID.eq(petId))
       .fetchOptional(PetRepository::toPet);
}

Noter ici l’utilisation d’une jointure implicite basée sur la clé étrangère, évitant ainsi d’ajouter une clause ON entre la PK de PETS et la FK de TYPES.
Avec une association 1:1, le chargement et le mapping du type d’animal ne présente aucune difficulté :

private static Pet toPet(org.jooq.Record row) {
    return new Pet(row.get(PETS.ID), row.get(PETS.NAME), row.get(PETS.BIRTH_DATE),
          new PetType(row.get(PETS.TYPE_ID), row.get(TYPES.NAME)));
}

Le chargement des associations 1:N se complexifie. L’usage de l’opérateur mulstiset() du SQL qui est supporté par jOOQ permet de charger les Vets et leurs Specialities en une seule requête :

public List<Vet> findAll(){
    return dsl.select(VETS.ID, VETS.FIRST_NAME, VETS.LAST_NAME, MULTISET_SPECIALITIES)
       .from(VETS)
       .leftJoin(VETS.vetSpecialties())
       .orderBy(VETS.ID)
       .fetch(VetRepository::toVet);
}

private static final Field<List<Specialty>> MULTISET_SPECIALITIES = multiset(
    select(VET_SPECIALTIES.specialties().ID, VET_SPECIALTIES.specialties().NAME)
       .from(VET_SPECIALTIES)
       .where(VET_SPECIALTIES.VET_ID.eq(VETS.ID)))
    .as("specialties")
    .convertFrom(result -> result.map(it -> new Specialty(it.get(SPECIALTIES.ID), it.get(SPECIALTIES.NAME))));


private static Vet toVet(Record4<Integer, String, String, List<Specialty>> row) {
    return new Vet(row.get(VETS.ID), row.get(VETS.FIRST_NAME), row.get(VETS.LAST_NAME),
       new HashSet<>(row.get(MULTISET_SPECIALITIES)));
}

jOOQ permet d’imbriquer plusieurs multiset afin de charger les visites des animaux d’un propriétaire en une seule requête. Je vous renvoie à la classe OwnerRepository.

Pour finir, les écrans « Find Owners » et « Veterinarians » affichent les résultats de manière paginée. jOOQ supporte la pagination au travers de la Seek Method (aussi appelée Keyset paging) ou du calcul des méta-données de pagination en une seule requête SQL. C’est cette dernière approche qui a été utilisée sur jOOQ Petclinic afin de garder iso-fonctionnels les écrans paginés. Les plus curieux peuvent se référer à l’implémentation de la méthode findAll(Pageable pageable) de VetRepository et à la méthode paginate() du JooqHelper. Sur le même modèle que ce que propose Spring Data, des records Pageable et Page ont été introduits dans la base de code.

Au revoir JPA

Une fois l’ensemble des Repository migrés, la dernière étape a consisté à retirer la dépendance spring-boot-starter-data-jpa ainsi que toutes les annotations JPA apposées sur les entités (@Entity, @Table, @ ManyToMany …).

Débarrassé de JPA, nous pouvons revoir en partie le design de l’application qui avait été limité par ce dernier. En effet, les entités JPA ne peuvent pas être modélisées avec des record Java. Suite à la migration vers jOOQ, les entités du domaine métier de Spring Petclinic n’ont plus d’adhérence avec la couche de persistance. Les classes immutables ont pu être converties en record. Exemple du value object Speciality :

public record Specialty(Integer id, String name) {
}

Le refactoring de la modélisation aurait pu aller plus loin, mais ce n’était pas l’objectif de cette version de Petclinic dédiée à jOOQ et non à la Clean Architecture. Peut-être l’objet d’un prochain article ?

Conclusion

A travers l’exemple de migration de l’application démo Spring Petclinic, cet article donne un aperçu des possibilités offertes par jOOQ. Cette librairie est mature, a plus de 15 ans (la version 1.0.0 de jOOQ est sortie en 2010) et est utilisée par de grands comptes comme Apple, Allianz et Mastercard.
Notez néanmoins que jOOQ possède un système de double licence : commerciale et Open Source. Les distributions commerciales de jOOQ maintiennent un support versionné des SGBDR. A contrario, l’édition Open Source de jOOQ ne supporte que la dernière version des SGBDR Open Source. A ce titre, l’utilisation de jOOQ avec Oracle et SQL Server requière une licence commerciale.

En replongeant dans le SQL, je me suis aperçu que j’étais passé à côté de certaines fonctionnalités avancées comme les MULTISET. A retenir.

Enfin, je remercie Sylvain pour sa relecture du code de Spring Petclinic jOOQ et ses conseils avisés. J’invite tous les autres experts jOOQ à venir améliorer le repository spring-petclinic-jooq en soumettant des Issues ou en proposant des Pull Requests.

Java Developer Advocate chez Oracle, José Paumard nous présente la nouvelle API Gatherers qui, depuis Java 24, vient se greffer sur l’API Stream Java sortie il y’a 11 ans avec Java 8.

Tout comme l’API Collector, José commence par rappeler que l’API Gatherers est indépendante de l’API Stream. Cette API a été introduite dans Java via la JEP 485 Stream Gatherers conduite par Viktor Klang. Les plus curieux pourront regarder la vidéo Youtube du Deep Dive qu’a animé Viktor lors de la conférence JavaOne qui s’est tenue en mars 2025.

L’article The Gatherer API permet également d’approfondir votre étude des Gatherers. Notez que le site dev.java permet désormais d’exécuter des snippets Java (pas directement dans le navigateur, mais sur un serveur Cloud).

Toutes les classes et interfaces de l’API Gatherers ont été ajoutées au package java.util.stream.

Opérations intermédiaires et terminales d’un Stream

Pour rappel, un Stream se connecte à une source de données (collections, fichier, générateur de nombres aléatoires, regex). Un stream est composé de :

1. zéro, une ou plusieurs opérations intermédiaires qui retournent un Stream
2. une seule et unique opération terminale qui retourne un résultat et clôture le Sream.

Viktor assimile l’API Stream à celle d’un Builder : on décrit un pipeline d’opérations puis on appelle l’opération terminale pour déclencher son traitement.

Exemples d’opération terminales proposées par l’API Stream :

• reduce() : opération de réduction
• findFirst() : renvoie un objet de type Optional qui encapsule le premier élément du Stream s’il existe, ne consomme pas tous les éléments du Streams.
• collect() : prend en paramètre un Collector
• toList() : méthode raccourcie disponible depuis Java 16

Les Collector permettent de créer ses propres opérations de réduction. Gatherer est le pendant des Collector pour les opérations intermédiaires. Une différence notable est qu’un Collector ne peut pas interrompre un Stream : il ne le connait pas.

Le JDK propose de nombreuses opérations intermédiaires comme map(), filter(), dropWhile(), limit() ou bien encore mapMulti() ajoutée plus récemment. L’API Gatherers va nous permettre de créer nos propres opérations intermédiaires. Ce n’était pas possible jusque-là. Parmi ces opérations intermédiaires, il existe des opérations stateless comme filter() et des opérations statefull come sorted() qui doivent consommer tous les éléments du stream avant de produire quelque chose vers le down stream.

Il n’y avait pas moyen de créer d’opérations intermédiaires jusqu’aux Gatherers.

Que propose l’API Gatherer ?

L’interface générique Gatherer s’appuie sur 3 paramètres :

interface Gatherer<T, A, R> { 
    Integrator<A, T, R> integrator(); 
}

• T : type des éléments consommés
• A : type mutable utilisé en interne par les Gatherers
• R : type des éléments poussés dans le down stream

Avec sa méthode principale integrator(), José compare l’interface Gatherer à une interface fonctionnelle de type Supplier.

L’interface Gatherer met à disposition 3 interfaces fonctionnelles imbriquées dont nous étudierons le fonctionnement : Downstream, Greedy et Integrator.
Exemple de le l’interface Integrator :

@FunctionalInterface
interface Integrator<A, T, R> {
    boolean integrate(A state, T element, Downstream<? super R> downstream); 
}

Afin de pouvoir utiliser le Gatherer, l’interface Stream de l’API Stream propose désormais depuis Java 24 la méthode gather :

Stream<R> downStream = upstream.gather(gatherer);

Le JDK s’enrichit de la classe factory Gatherers (notez son pluriel) utilisées par les différentes implémentations des méthodes of() de l’interface Gatherer.

Publier dans le Downstream

Un Downstream reçoit des données traitées par une opération intermédiaire. C’est le flux de sortie d’un Gatherer.
Voici un exemple de Gatherer chargé de pousser un élément dans le Downstream :

Gatherer<T, ?, R> gatherer = Gatherer.of(
     (_, element, downStream) -> downStream.push(element) // returns a boolean
);

Le booléen renvoyé en retour est important. Son fonctionnement est subtil : renvoyer false permet l’arrêt du traitement des éléments suivants. Il ne se passe alors plus rien lorsqu’on pousse des éléments au downStream qui n’en accepte désormais plus. Aucune exception n’est levée. Cela peut surprendre.

Dans le jargon de l’API Gatherer, lorsqu’un Integrator retourne directement la valeur du downstream.push(element), on dit qu’il est Greedy. Il traitera nécessairement tous les éléments du Stream. Son exécution est optimisée. Exemple :

Gatherer<T, ?, R> gatherer = Gatherer.of(
    Integrator.of((_, element, downstream) -> downstream.push(element))
);

Lorsqu’un Integrator n’utilise pas de coupe-circuit et consomme donc l’intégralité des éléments reçus, il est recommandé d’utiliser la méthode factory Integrator.ofGreedy() pour instancier un Integrator :

Gatherer<T, ?, R> gatherer = Gatherer.of(
    Integrator.ofGreedy((_, element, downstream) -> downstream.push(element))
);

Un Downstream possède un état nommé rejecting. La méthode isRejecting() de l’interface Downstream propose d’y accéder. Cet état a 3 propriétés :

1. Commence à false
2. Ne peut commuter que de false vers true (ne peut pas se rouvrir)
3. L’état de peut commuter que lors d’un push() => règle spécifique aux API du JDK

José nous met en garde : dans un Integrator, l’appel à la méthode isRejecting() ne sert à rien. Il s’agit d’une fausse optimisation qui s’apparente à du code mort.

(_, element, downstream) -> {
    if (downstream.isRejecting()) { //
        return false;               // Condition inutile
    }                               // 
    return downstream.push(mapper.apply(element));
}

José continue sa présentation en nous expliquant les bonnes pratiques à adopter lorsqu’on publie sur le Downstream :

• Ne pas faire de test isRejecting() sur le Downstream
• Privilégiez l’usage de la méthode allMath() plus efficace que takeWhile()
• Fermer les ressources si nécessaire. Lorsque le Stream agit sur un fichier, il faut fermer le fichier et ne pas oublier le try with ressources

Exemple exempté de bugs :

(_, element, downstream) -> {
    try (Stream<R> elements = flatMapper.apply(element);) {
        return elements.allMatch(downstream::push); 
    }
}

Un Downstream n’est pas un objet thread-safe. Il est donc nécessaire de ne pas générer d’effet de bord sur les données externes. Attention aux race conditions et plus particulièrement dans les parallel streams.
A ce titre, la méthode Gatherer.oSequential() permet de créer un Gatherer séquentiel (non parallélisable).

L’élément state est un état mutable pouvant être utilisé par le Gatherer. En complément de l’Integrator, il est nécessaire de fournir à l’API de création d’un Gatherer un Supplier chargé d’initialiser l’état du state.

Exemple d’un Gatherer limitant le nombre d’éléments et initialisant un compteur :

class Counter { long count = 0L; }

var gatherer = Gatherer.ofSequential( 
    Counter::new, // the initializer
    (state, element, downstream) -> {
        if (state.count++ < limit) {
            return downstream.push(element);
        } else {
            return false;
        }
});

A noter que l’opérateur var retient le type des classes anonymes.

Pour agir sur l’ensemble des données du Gatherer, on peut stocker les éléments dans une collection tel qu’un HashSet dans l’exemple suivant « Distinct Gatherer »:

var gatherer = Gatherer.ofSequential(
    () -> new Object() { Set<T> set = new HashSet<>(); },
    (state, element, downstream) -> {
        if (state.set.add(element)) {
            return downstream.push(element);
        } else {
            return true;
        }
});

Pour publier l’état final d’un Gatherer, on peut ajouter après l’Initializer et l’Integrator une 3ième lambda de type BiConsumer agitant comme finisher et pouvant consommer tous les éléments du state :

var gatherer = Gatherer.ofSequential(
    () -> new Object() { Set<T> set = new TreeSet<>(); },
    (state, element, downstream) -> { ... },
    (state, downstream) -> { // finisher
        state.set.stream().allMatch(downstream::push);
});

Les Parallel Gatherers

Les développeurs Java peuvent choisir de construire un Gather supportant ou non le parallélisme et les parallel Streams. A cet effet, 2 méthodes de type fabrique sont à leur disposition :

1. Gatherer.of()
2. Gatherer.ofSequential()

Pour supporter le parallélisme, l’API Gatherer adopte le principe suivant : un objet state par thread. Cela permet de ne pas utiliser de collections synchronisées dégradant les performances.
Dans chaque Stream parallèle, on a donc autant de state que de threads. A la fin de l’opération intermédiaire, il est nécessaire d’utiliser un Combiner pour combiner tous les états.

Ce Combiner est un 4^ième paramètre à passer à la méthode factory of() :

var gatherer = Gatherer.of(
    () -> new Object() { Set<T> set = new HashSet<>(); }, 
    (state, element, downstream) -> { // executed in
        state.set.add(element); // different threads
        return true;
    },
    (state1, state2) -> { // combiner
        state1.set.addAll(state2.set);
        return state1;
    },
    (state, downstream) -> { // finisher
        state.set.allMatch(downstream::push);
    }
);

Les Sequential Gatherers ne peuvent pas être appelés en même temps depuis différents thhreads. Ils ne possèdent pas de Combiner. Pour autant, José nous explique que l’API Stream est capable de séquencer les appels vers un Sequential Gatherer. Cette fonctionnalité est nouvelle et donc à utiliser avec précaution. Tester les perfs.

Pour aller plus loin, José nous invite à consulter le repo GitHub SvenWoltmann/stream-gatherers. Le JDK vient avec de nouveaux Gatherers comme scan(), fold() ou bien encore mapConcurrent().
Des librairies tierces comme gatherers4j proposent également leur propres gatherers : reverse(), repeat(n), groupBy(fn) …

Pour conclure, retenons qu’un Gatherer est construit sur 4 éléments. Tous ne sont pas obligatoires.

Cette conférence a pour objectif d’ouvrir les portes en nous donnant les clés de l’architecture. Pour seconder Cyrille, Eric a du remplacer Christian au pied levé.
Un constat est posé. Sur les dix dernières années, les systèmes ont changé : ils sont devenus modulaires, de plus en plus distribués. La modularité permise par le Cloud permet de répartir la charge. Il y’a de plus en plus d’interconnexions entre briques applicatives.
L’architecture bouge tout le temps, évolue constamment.

Que doit-on savoir ? Pour commencer, on ne saura jamais tout et il faudra vivre avec. Personne ne sait tout. Même le plus capé des architectes.

Comme fil conducteur, Cyrille et Eric prennent un exemple réel issu du monde des télécommunications.
Pour cahier des charges, le client précise que le système va recevoir des fichiers chaque minute et doit les intégrer tous les 15mn. Contexte : ces fichiers viennent d’équipements télécom.

Première question à se poser : « est-ce possible de synchroniser la temporalité ? ».
Réponse du client : « Non, ce n’est pas possible ».
La brique centrale est nommée Aggregator.


Diagramme de contexte C4 correspondant :

Première clé donnée dans ce talk : commencer par identifier le problème.
Comment l’appliquer : quel est le but ? Ici c’est d’agréger les données reçues.
Cette première clé parait banal : penser problème avant de penser à la solution. Cet adage bien connu s’applique : « un problème bien posé est à moitié une solution ».

Après avoir cerner le problème, on continue en prenant en compte les nombreux Software Quality Attributes dont font partis le cout, la performance, la sécurité ou bien encore le sourcing des dévelopeurs. Liste complète sur arc42-templates et la FAQ C-1-2.

Examinons à présent les* contraintes du système.
1^ière contrainte : disponibilité
Toujours Up pour recevoir les données. Calcule de données toutes les 15mn.

2^nde contrainte : performance
Le besoin initial mentionnait la réception d’un fichier par minute. En questionnant le métier, on dénombre un fichier par équipement. Sachant qu’il y’a 50 équipements, cela ferait 50 fichiers. Pas tout à fait, puisqu’un équipement compte 40 000 capteurs. Au total, ce sont 6 milliards de données que le système devra traiter toutes les 15 minutes.

La formule de calcul de l’agrégation est compliquée ; ce n’est pas de simples additions.
Le métier souhaiterait que le calcul soit instantané. Jouant sur le cout financier d’une telle exigence, Eric a réussi à négocier avec le client un temps de traitement de 2 minutes max. Cette durée est acceptable au vu du besoin : anticiper les pannes et remonter des alertes.

Seconde clé donnée dans ce talk : négocier, étudier, éduquer les gens.
Pas nécessaire de mettre systématiquement de la cohérence transactionnelle partout.

Les contraintes techniques nous guident pour définir l’architecture technique. Cette approche n’est pas antinomique avec le DDD. Dans notre exemple, il existe une corrélation entre les contraintes techniques et le découpage en sous-domaine.
On peut identifier 2 sous-domaines : le parsing lors de l’ingest et le calcul de statistiques.

Une troisième clé nous est donnée : penser modulaire pour adresser le problème.

Voyons à présent comment implémenter ces 2 sous-domaines.
On pourrait partir sur 2 services. Mais dans un premier temps, Eric propose de commencer par seul service, plus simple, plus facile à implémenter et livrer. Par contre, afin de préparer un éventuel futur découplage, on utilise l’approche pragmatique de modular monolith. Bel exercice de frugalité : une solution distribuée est remplacée par un monolith.

L’architecture se pense à différents niveaux, à plusieurs.

Les architectes d’entreprise ont souvent une vue d’ensemble globale. Les développeurs vont quant à eux s’intéresser davantage aux technologies.
Un conseil, garder en tête cet objectif : bien s’entendre avec tout le monde

Les différents types d’architectures ont leurs avantages et inconvénients. Voici celles qui auraient pu être choisies :

1. Microservices : modularité jusqu’au bout
2. Modular monolith : facilite le découpage en microservices
3. Function as a Service
4. Big Ball of Mud : monolith avec archi spaghetti

Parmi les contraintes techniques, le vrai risque consiste à tenir le délai de traitement d’agrégation des données en dessous des 2 minutes. La première étape consiste à lever ce risque. Il faut lever ce risque et commencer les développements.

Réversible, l’architecture n°2 est retenue avec une approche hexagonale. On reste pragmatique : les deux sous-domaines s’appellent dans la même JVM par appel de fonction. Cyrille rappelle que l’architecture hexagonale demande de créer un peu plus de code, mais ce n’est pas les 30 secondes que met la création d’une interface qui va les ralentir. Cela permet de prévoir des options pas chères pour être réversible et changer son architecture en cours de route. Les décisions sont réversibles.

Une première version de l’application est déployée en production. Passent 1mn, puis 2, puis 5. On coupe tout. Trop long. Cela ne marche pas. Cyrille invite à célébrer ce constat : on sait que çà ne marche pas. Et on l’a découvert très vite.

La cause est rapidement identifiée : l’agrégateur du monolith est mono-thread. 3 solutions son envisagées :
1. Solution 1 : mono instance avec du multi-threading. Plus de vCPU, worker pools.

2. Solution 2 : multi instance avec du pub-sub. Rien à faire. On s’appuie sur un service du Cloud Provider. Clé : on reconnait les problèmes difficiles et on les délègue à du middleware en managé.

3. Solution 3 : combine multi-thread et multi-instance : trop compliqué et trop chère. Combine tous les inconvénients. A ne pas faire.

Approche choisie : solution 2. L’architecture est l’art du tradeoff (du compromis).

La solution retenue impose la fin du modular monolith. Nécessité de passer en micro-services : 2 services, 2 deployments et N services

Réfléchissons à présent sur ce qui pourrait mal se passer avec un tuyau asynchrone : messages en double ou triple, manque de ressources, messages perdus …

Le fournisseur de Cloud garantie une partie des problèmes évoqués.
Cyrille rappelle la nécessité d’un consumer à être idempotent pour gérer les messages en double.

Avant de faire un choix sur l’implémentation de l’adaptateur et assurer la persistance des données (ex : PostgreSQL vs Redis), Eric propose de rester en mémoire pour tester rapidement en prod. Cela permet de gagner du temps et de vérifier les hypothèses.
On va livrer en prod un mock. Pas de honte. Vrai essaie sur de vraies machines avec les vraies données. On utilise la prod, le vrai environnement.

Le calcul dure moins de 2 minutes : l’hypothèse est validée. L’adaptateur peut désormais être implémenté avec Redis.

Message de fond : l’architecture est évolutive. Il ne faut pas la mettre en place dès le début. L’architecture est dynamique. Tout bouge.

L’application est composée de 2 systèmes qui doivent se parler. Un contrat JSON est définit entre dispatcher et aggregator. Le contrat est très explicite avec les unités.
Cyrille fait remarquer un problème de typo sur un champ : latencyy_ms avec 2 lettres y

Un renommage serait possible mais il est recommandé de positionner 2 champs pour respecter le contrat.

Autre clé : on ne change pas un contrat. A partir du moment où il est publié, on doit rester dans la même version majeure pour toujours. Contracts are forever. On ne doit pas casser les clients existants.

Cyrille rappelle les utiles à l’heure de l’IA :
– Architectural Decision Records (ADR) : template
– ArchUnit : try architecture tests

Autres clés proposées par Cyrille pour avoir des réunions constructives.
Commencer par time boxer les réunions. Utiliser un tableau blanc ou numérique.
Alterner raisonnement individuel et raisonnement en équipe :

1. Chacun s’isole pour réfléchir de son côté au même problème
2. Chacun vient ensuite expliquer son architecture. On essaie de dépersonnaliser sa solution. Cet exercice permet d’apprendre de ses collègues et de connaitre leurs points d’attention.

Remember :

• The system = the software + the people
• Baby steps : on apprend progressivement, par petits pas, rapidement => réduit le risque dans un monde avec beaucoup d’incertitudes
• Rester simple
• Books : toutes ces attitudes nécessaires à l’Architecture restent inchangées depuis 30 ans : couplage et cohésion, contrats, modularités, API … Cet apprentissage est pérenne et en vaut donc la peine. Les livres recommandés par Cyrille resteront intemporels.

Sébastien est Core Commiter sur Spring Framework. Il intervient également sur des sujets transverses au portfolio Spring : support de Kotlin, null-safety (avec JSpecify) et les sujets d’optimisation. Dans ce talk, il a pour ambition de nous montrer comment améliorer l’efficacité de 80% des applications Spring, que ce soit de nouvelles applications ou des applications Legacy.

Les raisons d’améliorer l’efficacité de nos applications sont multiples :

• Baisser le cout de run des applications
• Développement durable pour diminuer la consommation d’énergie, de mémoire et de CPU
• Optimiser les applications pour les containers (sur le Cloud ou OnPremise)

Pour arriver à nos fins, Sébastien nous propose 3 technologies :

1. CDS : techno relativement vieille mais qui s’est améliorée au fil des versions de Java
2. AOT cache : Java 24 permet d’utiliser l’AOT cache qui est une version améliorée CDS. Sébastien prédit l’exploision de AOT Cache avec la LTS Java 25
3. AOT cache with profiling : technologie expérimentale et prometeuse

Ces 3 technologies nécessitent un training run. Cette « exécution d’entrainement de l’application » consiste à lancer l’application pour charger les classes et créer un cache utilisé par la suite pour les déploiements en production. Le gain est triple :

• Temps de démarrage réduit
• Empreinte mémoire réduite
• Warmup de la JVM plus rapide

1. Class Data Sharing (CDS)

Disponible depuis Java 9 (2017), CDS a continué à évoluer au fil des versions de Java.

Par facilité (notamment pour la fonctionnalité d’extraction), un prérequis conseillé par Sébastien consiste à utiliser Java 17 et Spring Boot 3.3 et +.

Pour utiliser la fonctionnalité CDS, une archive CDS (format .jsa) doit être créée pour le classpath de l’application. Spring Framework fournit un mécanisme facilitant la création de cette archive. Une fois l’archive disponible, on peut l’utiliser via un flag de la JVM.

La création de l’archive CDS nécessite 2 paramètres de JVM :

• -Dspring.context.exit=onRefresh : démarrage les beans singletons Spring non lazy puis arrête l’application.
• -XX:ArchiveClassesAtExit=spring-petclinic.jsa : création de l’archive CDS lorsque la JVM s’arrête.

Les plugins Maven et Gradle de Spring Boot permettent de créer un JAR auto-exécutable. Disposer d’une seul JAR est bien pratique pour le déploiement et le téléchargement d’une application depuis le repository Maven d’entreprise, mais pas efficiente avec CDS qui ne supporte pas les JAR imbriqués. La version 3.3 de Spring Boot a facilité le support de CDS en ajoutant une fonctionnalité d’auto-extraction du JAR via le paramètre -Djarmode=tools. Son utilisation est illustrée par la commande suivante :

java -Djarmode=tools -jar spring-petclinic.jar extract

Sébastien fait une démonstration à l’aide de l’application Spring Petclinic.

Commande permettant d’utiliser l’archive CDS au démarrage de l’application :

java -XX :SharedArchiveFile=spring-petclinic.jsa – jar spring-petclinic.jar

Le gain au démarrage est de 19%. A noter que l’utilisation de CDS peut engendrer des effets de bord si l’on ne suit pas les bonnes pratiques suivantes :

• Utiliser idéalement la même JVM pour la capture du CDS et le run de l’application
• Spécifier le classpath avec la liste complète des JAR et ne pas utiliser de wildcard *
• Le timestamp des JAR doit être préservé
• Les éventuels JAR additionnels doivent être ajoutés à la fin du classpath.

L’étape de démarrage nécessaire à l’enregistrement de l’archive CDS est appelée le training run. Cette étape peut être intégrée dans le pipeline CI/CD de build de l’application Spring. Spring utilise une base de données H2 en mémoire. Une application d’entreprise se connectera à un PosgreSQL ou un MongoDB. Le paramétrage Spring diffère en fonction des dépendances externes de l’application. Sébastien nous recommande de consulter le repository spring-lifecycle-smoke-tests donnant différents exemples de configuration pour Spring Data, Spring Batch, Spring Coud, Kafka, Spring Security …

Par exemple, pour éviter qu’une application Spring Data JPA ne fasse appel à la base de données, il est possible de désactiver la lecture des méta-données par Hibernate. Ne pouvant plus déterminer automatiquement le dialect, il est alors nécessaire de lui spécifier.

# Specify explicitly the dialect (here for PostgreSQL, adapt for your database)
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect

# Disable Hibernate usage of JDBC metadata
spring.jpa.properties.hibernate.boot.allow_jdbc_metadata_access=false

# Database initialization should typically be performed outside of Spring lifecycle
spring.jpa.hibernate.ddl-auto=none
spring.sql.init.mode=never

Le support de Buildpack par les plugins Maven et Gradle de Spring Boo transforme une application Spring Boot en une image OCI (Docker). Commandes :

mvn spring-boot:build-image
gradle bootBuildImlage

Le support de CDS est prévu dans Buildpacks via l’activation du flag BP_JVM_CDS_ENABLED. Exemple de configuration Maven :

<plugin>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-maven-plugin</artifactId>
	<configuration>
		<image>
			<env>
				<BP_JVM_CDS_ENABLED>true</BP_JVM_CDS_ENABLED>
			</env>
		</image>
	</configuration>
</plugin>

Buildpack effectue le training run et ajoute l’archive jsa dans le container.

Pour un effort mesuré, le temps de démarrage de Spring Petclinic est réduit de 3 secondes à 1,8 secondes.

2. AOT Cache

Successeur de CDS, AOT Cache (Ahead-Of-Time Cache) est une fonctionnalité de la JVM intégrée à Java 24 qui permet d’améliorer l’efficience de nos applications Java. Permettant de diminuer les temps de démarrage, Spring AOT est une fonctionnalité Spring obligatoire pour les images natives mais optionnelle sur la JVM. Sébastien perçoit une synergie entre AOT Cache et Spring AOT.

L’utilisation Spring AOT impose certaines contraintes comme la pré-configuration des profiles Spring. Le repo Github sdeuleuze/demo-profile-aot montre comment activer les profils Spring dans un build Maven et Gradle.

Pensée dans le cadre du projet Leyden, La JEP 483 Ahead-of-Time Class Loading & Linking est disponible dans Java 24 et des améliorations prévues dans les versions suivantes de Java. L’utiliser est un bon investissement.

La création du cache AOT nécessite 2 étapes :

La 1^ière étape consiste à générer le fichier .aotconf à l’aide de l’option -XX:AOTMode=record et la ligne de commande suivante :

java -XX:AOTMode=record -XX:AOTConfiguration=spring-petclinic.aotconf \
-jar spring-petclinic.jar

Au préalable, comme avec CDS, le JAR auto-exécutable aura été extrait à l’aide de -Djarmode=tools.

La 2^ième étape consiste à générer un fichier .aot avec l’option -XX:AOTMode=create et la ligne de commande suivante :

java -XX:AOTMode=create -XX:AOTConfiguration=spring-petclinic.aotconf -XX:AOTCache=spring-petclinic.aot -jar spring-petclinic.jar

Le temps de démarrage de Spring Petclinic descend à 1,3 secondes :

3. AOT Cache with code compilation and Spring AOT

Sébastien rappelle que ce n’est que le début de l’histoire et que ces temps de démarrage à l’aide d’AOT Cache ne pourront que s’améliorer dans le futur. En effet, le projet Leyden prévoit de nouvelles améliorations, donc les 3 JEPs en draft :

1. Ahead-of-Time Method Profiling : amelioration du temps de chauffe
2. Ahead-of-time Command Line Ergonomics : une seule étape au lieu de 2 étapes pour créer les fichiers .aotconf et .aot
3. Ahead-of-time Code Compilation : récupération du code natif du JIT pour le réutiliser en prod

Sébastien nous fait une démo live à partir d’une version du JDK compilée en local avec les dernières fonctionnalités du projet Leyden. Cette fois-ci, le workflow va être un peu différent : on ne fait pas de stop après le démarrage. On laisse tourner l’application. Sébastien utilise l’outil oha pour chauffer la JVM (faire le warmup). Il mesure des améliorations très significatives alors même que techno en work-in-progress. Jugez par vous-même :

• Courbe bleue : JVM classique qui prend son temps pour le warmup
• Courbe rouge : AOT profiling. Warmup assez rapide.
• Courbe jaune : warmup passé de 30 à 7 secondes. Fonctionne sur des applications Legacy

Récapitulatif

Le tableau récapitulatif ci-dessous compare 3 technologies d’optimisation d’une application Java :

1. GraalVM : la version gratuite de GraalVM vient avec le Garbage Collector serial adapté pour les applications ayant une faible empreinte mémoire et une petite taille du de Heap. Le GC G1 n’est disponible que dans la version commerciale Oracle de GraalVM. Avantage : conso mémoire réduite au max. Pas fait pour des applications qu’on déploie / construit plusieurs fois par jour. Dépend de la taille de l’appli : ok pour un microservice mais pas un monolith. Spring fait le travail pour préconfigurer GraalVM. Mais quid des autres librairies qui ne supporte pas GraalVM et pour lesquels les développeurs doivent ajouter des méta-données. Sébastien considère que GraalVM est une niche pour 5 à 10% des applications Spring. Cela dit, des travaux sont en cours pour améliorer le support dans Spring.
2. JVM with Project CRaC : Sébastien est assez sévère sur cette technologie qui comporte 2 énorme défauts : Linux uniquement mais surtout à cause du cycle de vie nécessitant de restaurer l’application (handles filesystems, sockets réseaux …). Quid du support des autres librairies ? L’API de ces librairies peut bloquer. Plus encore : l’image snapshot de la JVM contient les credentials. Aussi, Sébastien de recommande pas CRaC pour la production. La techno a des limites malgré l’effort de l’équipe Spring.
3. JVM with AOT cache : utilisable sur un grand nombre de projets legacy. Temps de démarrages est réduit de 2 à 4 fois. Les effets de bord sont mesurés. La CI doit être adaptée pour lancer le warmup.

Le projet Leyden et la JVM continue à évoluer. Preuve en est la Pull Request #44 datant de février 2025 du projet Leyden : 8350488: [leyden] Experimental AOT-only mode

D’autres améliorations concernant les applications Legacy seront annoncées à la conférence Spring IO qui aura lieu du 21 au 23 mai 2025 à Barcelone.

Enfin, pour ses benchmarks, Sébastien passe une annonce : il recherche de plus grosses applications Open Source basées sur Spring Boot et plus réalistes que l’application démo Petclinic.

Si vous voulez creuser le sujet, je vous recommande la lecture de l’article intitulé Spring Boot CDS support and Project Leyden anticipation qu’a publié Sébastien le 29 aout 2024.

1. Montrer comment migrer une application Spring Boot 3.4 vers Quarkus 3.21, avec le minium d’effort et en modifiant le moins de code possible
2. Utiliser les extensions Spring proposées par Quarkus pour garder un lien avec le monde Spring tout en soulignant l’effort de l’équipe Quarkus pour supporter Spring, un framework incontournable de l’écosystème Java

Les extensions Spring pour Quarkus utilisées sont au nombre de quatre : Spring DI, Spring Web, Spring Data JPA et Spring Cache.
Le changement majeur aura été de porter le templating des pages HTML de Thymeleaf vers Qute.

Débutant en Quarkus, le code proposé ne respecte peut-être pas toutes les règles de l’art prônées par l’équipe de dév Quarkus. Je m’en excuse par avance. Si vous voulez contribuer et corriger le tir : issue et Pull Request sont les bienvenues.

Le différenciel complet entre la version Spring Boot et la version Quarkus de Petclinic peut-être visualisé sur Github.

Configuration du build Maven et Gradle

Spring Petclinic supporte les 2 principales plateformes de build de l’ecosystème Java, à savoir Maven et Gradle. Pour chaque dépendance Spring Boot, le tableau ci-dessous dresse l’équivalent utilisé sur la version Quarkus :

Les dépendances vers les 2 webjars bootstrap et font-awesome sont restés inchangées.
La migration a été faite avec une approche top-down : on part de la couche persistance pour remonter vers la couche de présentation.

Adaptation de la couche Spring Data JPA

L’extension Spring Data JPA pour Quarkus présente l’avantage de pouvoir conserver les conventions de nommage des interfaces des repository Spring Data JPA. Sous le capot, l’implémentation est générée à l’aide de Panache. Les repository migrés peuvent continuer à implémenter les interfaces JpaRepository et ListCrudRepository, à utiliser les interfaces Spring Data Page et Pageable pour la pagination.

Ce portage a permis de conserver 90% du code existant de la couche de persistance de Spring Petclinic. Je l’ai personnellement trouvé plus strict que l’original. Preuve en est ce premier exemple possible avec Spring Data JPA, mais qui ne fonctionne pas sous Quakus : déclarer sur l’interface OwnerRepository la méthode findPetTypes manipulant des entités JPA de type PetType et non de type Owner.
L’erreur suivante était générée pendant le build :

Query annotations may only use interfaces to map results to non-entity types. Offending query string is "SELECT ptype FROM PetType ptype ORDER BY ptype.name" on method findPetTypes of Repository org.springframework.samples.petclinic.owner.OwnerRepository

Les messages d’erreur ne sont pas explicites. Aussi, pour debugger et trouver la cause, j’ai eu besoin d’ajouter temporairement la dépendance suivante :

<dependency> 
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-spring-data-jpa-deployment</artifactId>
</dependency>

Le moyen de contournement a consisté tout simplement à découper en deux l’interface OwnerRepository. L’interface PetTypeRepository a été ajoutée et a pour responsabilité l’accès aux PetType. On a ainsi un meilleur découplage.

Second cas dysfonctionnant sous Quarkus :

public interface VetRepository extends Repository<Vet, Integer> {
	Collection<Vet> findAll();
}

Quarkus génère l’exception suivante :

Caused by: io.quarkus.spring.data.deployment.UnableToParseMethodException: Method 'findAll' of repository 'org.springframework.samples.petclinic.vet.VetRepository' cannot be parsed as there is no proper 'By' clause in the name.

La classe MethodNameParser ne supporte pas le type de retour Collection. Triviale, la correction a consisté à le changer en List.

Dernier changement mineur apporté à la couche de persistance : l’exception non checkée DataAccessException n’est pas supportée par Quarkus. Elle a donc été retirée de l’interface des méthodes des Repository.

Une fois migrée, l’interface OwnerRepository n’a aucune adhérence à Quarkus ou Panache. Elle conserve ses imports sur les classes de Spring Data Commons et Spring Data JPA :

package org.springframework.samples.petclinic.owner;

import java.util.Optional;

import jakarta.annotation.Nonnull;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.JpaRepository;

public interface OwnerRepository extends JpaRepository<Owner, Integer> {

	Page<Owner> findByLastNameStartingWith(String lastName, Pageable pageable);

	Optional<Owner> findById(@Nonnull Integer id);

	Page<Owner> findAll(Pageable pageable);

Adaptation des scripts SQL

Migrer les Repository Spring Data JPA, c’est bien. Les tester, c’est mieux. Les tests unitaires de Quarkus Spring Petclinic utilisent la base de données embarquées H2.
L’exécution du script data.sql échouait avec l’erreur suivante :

Caused by: org.h2.jdbc.JdbcSQLIntegrityConstraintViolationException: Intégrité référentielle violation de contrainte: "FK35UIBOYRPFN1BNDRR5JORCJ0M: PUBLIC.VET_SPECIALTIES FOREIGN KEY(SPECIALTY_ID) REFERENCES PUBLIC.SPECIALTIES(ID) (4)"
Referential integrity constraint violation: "FK35UIBOYRPFN1BNDRR5JORCJ0M: PUBLIC.VET_SPECIALTIES FOREIGN KEY(SPECIALTY_ID) REFERENCES PUBLIC.SPECIALTIES(ID) (4)"; SQL statement:
INSERT INTO vet_specialties VALUES (4, 2) [23506-230]

Cette différence de comportement s’explique par le fait que Quarkus utilise Hibernate pour générer le script DDL de création du schéma et non pas directement le script DDL schema.sql. L’ordre des colonnes diffère entre le script DDL généré par Hibernate et le script SQL existant. Je n’ai pas trouvé la possibilité d’utiliser le script schema.sql. Je ne suis apparemment pas le seul. Si vous avez une idée, vous pouvez contribuer à l’issue #8.

En attendant de trouver une solution, j’ai modifié le script SQL en précisant le nom des colonnes dans l’instruction INSERT, ce qui est une bonne pratique :

Portage des tests AssertJ vers Hamcrest

Pour les tests unitaires, Quarkus recommande l’utilisation de JUnit 5 déjà utilisé sur Spring Petclinic. Les assertions de JUnit sont limitées. Là où Spring Petclinic utilise la librairie AssertJ, Quarkus préconise l’utilisation d’Hamcrest. D’après l’issue #38689 “Include AssertJ with Quarkus releases”, le support d’AssertJ dans Quarlus ne semble pas planifié.

Migrer des assertions AssertJ vers les matchers Hamcrest peut être facilitée par la recette Open Rewrite MigrateHamcrestToAssertJ. L’inverse n’est pas vrai. C’est là où Github Copilot ou Codeium facilite la tâche. On migre un premier test, et l’IA vous assiste pour la suite.

Exemple avec la méthode shouldFindSingleOwnerWithPet() extrait de la classe ClinicServiceTests :

Avant migration sous AssertJ :

@Test
void shouldFindSingleOwnerWithPet() {
	Optional<Owner> optionalOwner = this.owners.findById(1);
	assertThat(optionalOwner).isPresent();
	Owner owner = optionalOwner.get();
	assertThat(owner.getLastName()).startsWith("Franklin");
	assertThat(owner.getPets()).hasSize(1);
	assertThat(owner.getPets().get(0).getType()).isNotNull();
	assertThat(owner.getPets().get(0).getType().getName()).isEqualTo("cat");
}

Après migration sous Hamcrest :

@Test
void shouldFindSingleOwnerWithPet() {
	Optional<Owner> optionalOwner = this.owners.findById(1);
	assertThat(optionalOwner.isPresent(), is(true));
	Owner owner = optionalOwner.get();
	assertThat(owner.getLastName(), startsWith("Franklin"));
	assertThat(owner.getPets(), hasSize(1));
	assertThat(owner.getPets().get(0).getType(), notNullValue());
	assertThat(owner.getPets().get(0).getType().getName(), is(equalTo("cat")));
}

Passer à l’annotation @TestTransaction

Dans les classes de tests faisant appels à des Repository, l’annotation org.springframework.transaction.annotation.Transactional du module spring-tx a été remplacée par io.quarkus.test.TestTransaction du module quarkus-test-commons. Ces annotations permettent de rollbacker la transaction à la fin de l’exécution d’une méthode de test, laissant ainsi la base de données inchangée pour le prochain test.

Exemple avec la méthode shouldInsertOwner() extrait de la classe ClinicServiceTests :

@Test
@TestTransaction
void shouldInsertOwner() {
	Page<Owner> owners = this.owners.findByLastNameStartingWith("Schultz", pageable);
	int found = (int) owners.getTotalElements();

	Owner owner = new Owner();
	owner.setFirstName("Sam");
	owner.setLastName("Schultz");
	owner.setAddress("4, Evans Street");
	owner.setCity("Wollongong");
	owner.setTelephone("4444444444");
	this.owners.save(owner);
	assertThat(owner.getId(), is(not(0)));

	owners = this.owners.findByLastNameStartingWith("Schultz", pageable);
	assertThat(owners.getTotalElements(), is(equalTo(found + 1L)));
}

De DataJpaTest à QuarkusTest

Pour tester les Repository JPA, Spring Boot met à disposition l’annotation @DataJpaTest automatisant la configuration des classes de test. Elle s’occupe notamment de démarrer en mémoire une base de données embarquée H2, de créer son schéma et de charger un jeu de données de test.

Pour arriver à un résultat similaire avec Quarkus, l’annotation @DataJpaTest a été remplacée par 2 annotations :

@QuarkusTest
@QuarkusTestResource(H2DatabaseTestResource.class)
class ClinicServiceTests {

L’annotation @QuarkusTestResource permet de référencer la classe H2DatabaseTestResource (fournie par l’artefact io.quarkus:quarkus-test-h2) chargée de démarrer / arrêter un serveur H2.

Par défaut, l’application Spring Petclinic démarre une base de données H2, la même que celle utilisée pour les tests. La propriété quarkus.hibernate-orm.sql-load-script du fichier application.properties a été positionnée sur h2 :

quarkus.datasource.db-kind=h2
quarkus.hibernate-orm.log.sql=true
quarkus.hibernate-orm.sql-load-script=db/${quarkus.datasource.db-kind}/data.sql

La propriété quarkus.hibernate-orm.sql-load-script a quant à elle permis de réutiliser le script DML existant data.sql insérant quelques données de test.

A ce stade de la migration vers Quarkus, les tests unitaires de la couche de persistance et de la couche service sont passants.

Internationalisation

Le support de l’internationalisation (i18n pour les intimes) est incomplet dans Spring Petclinic (cf. issue #1854). Le ressource bundle messages contient différent fichiers properties de traduction. Les clés sont utilisées dans certains templates Thymeleaf (ex : welcome) et pour les messages d’erreur (ex : required, typeMismatch.birthDate). Ce ressource bundle a pu être réutilisé dans la version Quarkus.

Qute propose un mécanisme typesafe de ressource bundle basé sur l’annotation @ResourceBundle. La classe AppMessages a été ajoutée à Petclinic. En voici un extrait contenant 3 clés :

import io.quarkus.qute.i18n.Message;
import io.quarkus.qute.i18n.MessageBundle;

@MessageBundle(value = "messages", locale = "en")
public interface AppMessages {

  @Message
  String welcome();

	@Message
	String required();

	@Message
	String typeMismatch_birthDate();

Le nom des clés des properties ne semble pas accepter le caractère point (ex : @Message(value = « typeMismatch.birthDate »). Certaines clés ont donc dû être renommées (ex : typeMismatch.birthDate vers typeMismatch_birthDate).

Au runtime, l’usage du ressource bundle Quarkus peut-être utilisé dans un template Qute via le namespace du message bundle. Exemple :


{#for err in errors}
  {#if err == 'notFound'}
    <p>{messages:notFound}</p>
  {#else}
    <p>{err}</p>
  {/if}
{/for}

Ce même ressource bundle peut également être exploité depuis un contrôleur REST. La création de classe I18nHelper permet d’exploiter dynamiquement l’en-tête HTTP Accept-Language :

@GetMapping("/")
public TemplateInstance processFindForm(@RequestParam(defaultValue = "1") int page, @RequestParam String lastName,
		@HeaderParam("Accept-Language") String language) {
	Page<Owner> ownersResults = findPaginatedForOwnersLastName(page, lastName);

if (ownersResults.isEmpty()) {
	// no owners found
	String notFound = I18nHelper.lookupAppMessages(language).notFound();
	return OwnerTemplates.findOwners(List.of(notFound));
}

Possible que Quarkus propose nativement un mécanisme similaire. Quarkus Renarde utilise quant à lui le header Accept-Language et un cookie.

En passant, l’exemple précédent montre l’usage des annotations Spring @GetMapping et @RequestParam. L’annotation Spring @RequestHeader n’est pas supportée par Quarkus et a dû être substituée par l’annotation @HeaderParam de JAX-RS.

Le debuggage de la méthode MessageBundleProcessor::parseKeyToTemplateFromLocalizedFile aura nécessité d’ajouter temporairement au classpath la dépendance io.quarkus:quarkus-qute-deployment.

Ressources statiques

Afin de se conforter aux conventions de Quarkus, les ressources statiques (fonts, css et images) ont été déplacées du répertoire static/resources vers le répertoire META-INF/resources.

Migration templates Thymeleaf vers Qute

Les templates Thymeleaf de Spring Petclinic utilisent le mécanisme de fragments Thymeleaf à la fois pour le gabarit des pages (layout.html) et pour les tags HTML réutilisables (inputField.html et selectField.html).

Une première étape a donc consisté à migrer ces fragments Thymeleaf vers une équivalence Qute. La syntaxe de ces 2 moteurs de templating Java diffère beaucoup. A l’aide du guide de référence de Qute, le gabarit des pages layout.html a été migré sans difficulté majeure. La gestion dynamique du menu est désormais gérée en JavaScript. Ce gabarit est référencé dans les autres templates Qute via la section {#include fragments/layout}.

Template Thymeleaf de la page welcome originale :

<!DOCTYPE html>
<html xmlns:th="https://www.thymeleaf.org" th:replace="~{fragments/layout :: layout (~{::body},'home')}">
  <body>
    <h2 th:text="#{welcome}">Welcome</h2>
    <div class="row">
        <div class="col-md-12">
          <img class="img-responsive" src="../static/resources/images/pets.png" th:src="@{/resources/images/pets.png}"/>
        </div>
    </div>
  </body>
</html>

Template Qute équivalent de la page welcome :

{#include fragments/layout}
  <body>
    <h2>{messages:welcome}</h2>
    <div class="row">
        <div class="col-md-12">
          <img class="img-responsive" src="/images/pets.png" />
        </div>
    </div>
  </body>
{/include}

Afin d’être enregistrés automatiquement par Quarkus, les user-defined tags input et select ont été déplacés dans le répertoire src/main/resources/templates/tags. Les 2 exemples de tags suivants permettent de comparer les syntaxes Thymeleaf et Qute.

Exemple du tag Thymeleaf inputField.html :

<html>
<body>
  <form>
    <th:block th:fragment="input (label, name, type)">
      <div th:with="valid=${!#fields.hasErrors(name)}"
        th:class="${'form-group' + (valid ? '' : ' has-error')}"
        class="form-group">
        <label class="col-sm-2 control-label" th:text="${label}">Label</label>
        <div class="col-sm-10">
            <div th:switch="${type}">
                <input th:case="'text'" class="form-control" type="text" th:field="*{__${name}__}" />
                <input th:case="'date'" class="form-control" type="date" th:field="*{__${name}__}"/>
            </div>
          <span th:if="${valid}"
            class="fa fa-ok form-control-feedback"
            aria-hidden="true"></span>
          <th:block th:if="${!valid}">
            <span
              class="fa fa-remove form-control-feedback"
              aria-hidden="true"></span>
            <span class="help-inline" th:errors="*{__${name}__}">Error</span>
          </th:block>
        </div>
      </div>
    </th:block>
  </form>
</body>
</html>

Exemple équivalent du tag Qute inputField.html :

 {#let invalid=result.hasErrors(name)}
      <div class="form-group {#if invalid} has-error {/if}">
        <label for="{name}" class="col-sm-2 control-label">{it}
        </label>
        <div class="col-sm-10">
          <input class="form-control" id="{name}" name="{name}" type="{type}" value="{field}" />
          <span class="fa {#if invalid}fa-remove{#else}fa-ok{/if} form-control-feedback" aria-hidden="true"></span>
          {#if invalid}
            <span class="help-inline">{result.getErrorMessage(name)}</span>
          {/if}
        </div>
      </div>
{/let}

Binding du modèle

Une fois les templates Thymeleaf converties en Qute, des ajustements ont été nécessaire du côté des contrôleurs web, notamment au niveau du binding des champs du formulaire. Le binding est le processus par lequel les données envoyées par l’utilisateur, généralement via un formulaire, sont automatiquement associées à un objet du modèle. Spring Web MVC gère le binding en utilisant des DataBinder qui convertissent automatiquement les paramètres de requête HTTP en propriétés d’un objet Java, en s’appuyant sur les noms des champs du formulaire et les conventions de nommage. Dans l’exemple suivant, la méthode processCreationForm accepte en paramètre un objet de type Owner bindé avec les champs du formulaire createOrUpdateOwnerForm.html :

@PostMapping("/owners/new")
public String processCreationForm(@Valid Owner owner, BindingResult result, RedirectAttributes redirectAttributes) {

Positionnée sur le paramtètre owner, l’annotation @Valid permet d’exécuter la validation Bean Validation / Hibernate Validator. Je n’ai pas trouvé dans Quarkus l’équivalent des classes BindingResult et RedirectAttibutes. Ainsi, la signature de cette méthode s’allège en Quarkus :

@PostMapping("/owners/new")
public TemplateInstance processCreationForm(Owner owner) {

On retrouve l’annotation Spring @PostMapping supportée par l’extension Quarkus. Le type de retour n’est plus une String correspondant à la vue MVC à afficher, mais une TemplateInstance.

Pour binder la classe Owner, un changement a dû être opéré au niveau de la classe Owner et de ses classes parentes Person et NamedEntity : ajouter l’annotation JAX-RS @FormParam sur les attributs bindés comme address. Extrait de la classe Owner :

public class Owner extends Person {

	@Column(name = "address")
	@NotBlank
	@FormParam("address")
	private String address;

Sans ce changement, voici le message d’erreur obtenu lors de la création d’un nouveau propriétaire d’animal de compagnie :

2025-04-12 17:36:04,095 ERROR [org.spr.sam.pet.sys.ExceptionMappers] (executor-thread-1) Internal server error: jakarta.ws.rs.NotSupportedException: HTTP 415 Unsupported Media Type
        at org.jboss.resteasy.reactive.server.handlers.RequestDeserializeHandler.handle(RequestDeserializeHandler.java:75)

Ce ciblage explicite des champs bindés depuis un formulaire HTML pourrait être justifié par des mesures de sécurité.

Pour terminer sur le binding du modèle, l’interface org.springframework.ui.Model est conservée dans quarkus-spring-context-api mais ne semble pas être exploitée par Quarkus.

Validation des données

Dans le paragraphe précédent, nous avons vu comment récupérer de manière typée les données saisies par l’utilisateur dans l’interface web de Petclinic. Nous allons voir à présent comment il est possible de valider les données avant de les insérer en base de données.

Le guide Validation with Hibernate Validator explique comment mettre en place Bean Validation sur une API REST. L’annotation @jakarta.validation.Valid est supportée par Quakus. Pour autant, son usage n’a pas pu être conservé dans Petclinic. En effet, si on la laisse, Quarkus valide les données du Owner et, en cas d’erreur, ne rentre pas dans la méthode processCreationForm. Il renvoie directement un flux texte contenant le rapport d’erreur complet. Exemple de la soumission d’un formulaire vide :

ViolationReport{title='Constraint Violation', status=400, violations=[Violation{field='processCreationForm.owner.address', message='ne doit pas être vide'}, Violation{field='processCreationForm.owner.telephone', message='ne doit pas être vide'}, Violation{field='processCreationForm.owner.telephone', message='Telephone must be a 10-digit number'}, Violation{field='processCreationForm.owner.city', message='ne doit pas être vide'}, Violation{field='processCreationForm.owner.lastName', message='ne doit pas être vide'}, Violation{field='processCreationForm.owner.firstName', message='ne doit pas être vide'}]}

Dans Petclinic, on souhaite renvoyer le formulaire HTML en erreur avec le message d’erreur à côté de chaque champ erroné.

Dans la documentation Quakus Qute, je n’ai pas trouvé l’équivalent de ce que propose Spring Web MVC, grâce notamment à la classe BindingResult. Pour contourner cette limitation, j’ai introduit le record Result. L’appel au Validator Bean Validation est fait de manière impérative. Son résultat (un ensemble de ConstraintViolation) permet de construire une instance de Result.

Exemple en Spring :

@PostMapping("/owners/new")
public String processCreationForm(@Valid Owner owner, BindingResult result, RedirectAttributes redirectAttributes) {
	if (result.hasErrors()) {
		redirectAttributes.addFlashAttribute("error", "There was an error in creating the owner.");
		return VIEWS_OWNER_CREATE_OR_UPDATE_FORM;
	}

	this.owners.save(owner);
	redirectAttributes.addFlashAttribute("message", "New Owner Created");
	return "redirect:/owners/" + owner.getId();
}

Exemple équivalent en Quarkus :

@PostMapping("/new")
public TemplateInstance processCreationForm(Owner owner) {
	Result result = Result.from(validator.validate(owner));
	if (result.hasErrors()) {
		return OwnerTemplates.createOrUpdateOwnerForm(owner, result);
	}

	this.owners.save(owner);
	return OwnerTemplates.ownerDetails(owner, Result.success("New Owner Created"));
}

Noter l’appel à la méthode OwnerTemplates::ownerDetails() dont nous allons étudier le fonctionnement dans le paragraphe suivant.

A noter également un écart de fonctionnement entre les versions Spring Boot et Quarkus de Petclinic : lors de la soumission d’un formulaire (POST), la version Spring utilise une redirection http pour rediriger l’utilisateur sur l’URL de consultation (GET). Nativement, Quarkus et Qute ne supportent pas ce fonctionnement. Pour être iso-fonctionnel, il aurait fallu utiliser Quarkus Renarde qui supporte les redirections et le scope flash.

Enfin, dans la version Spring, la classe PetValidator assure la validation des champs obligatoires name, type et birthDate. Dans la version Quarkus, cette classe a été supprimée au profit de l’utilisation de l’annotations @NotNull ajoutée sur classe Pet et du support de Bean Validation.

Templates Qute type-safe

Dans la version Quarkus de Petclinic, on note l’introduction de 3 nouvelles classes annotées chacune avec @CheckedTemplate : OwnerTemplates, PetTemplates et VetTemplates. Appelées depuis les contrôleurs REST, leurs méthodes natives permettent de sélectionner le template à rendre, ceci de manière type-safe. Exemple de la classe OwnerTemplates :

@CheckedTemplate(basePath = "owners")
public class OwnerTemplates {

	public static native TemplateInstance findOwners(List<String> errors);

	public static native TemplateInstance ownersList(List<Owner> owners, int currentPage, Page<Owner> page);

	public static native TemplateInstance ownerDetails(Owner owner, Result result);

	public static native TemplateInstance createOrUpdateOwnerForm(Owner owner, Result result);

}

Les paramètres des méthodes correspondent au modèle de données requis lors du rendu des templates Qute. Lors du build, la classe QuteProcessor vérifie leur concordance. C’est la magie de Quarkus. Voici un exemple explicite d’erreur remontée si l’on omet le paramètre owners à la méthode ownersList:

io.quarkus.qute.TemplateException: owners/ownersList.html:20:36 - {owner.firstName}: Only type-safe expressions are allowed in the checked template defined via: org.springframework.samples.petclinic.owner.OwnerTemplates.ownersList(); an expression must be based on a checked template parameter [page, currentPage], or bound via a param declaration, or the requirement must be relaxed via @CheckedTemplate(requireTypeSafeExpressions = false)

Au niveau de l’annotation @CheckedTemplate, l’attribut basePath permet de pointer sur le répertoire templates/owners et ne pas toucher à la localisation des fichiers te template html. Quarkus utilise le nom de la méthode pour retrouver le fichier html du même nom dans le répertoire templates/owner.

Test des contrôleurs

Le test unitaire Spring Boot de la classe OwnerController utilise l’annotation @WebMvcTest pour configurer un contexte d’application limité, ciblant uniquement les composants liés à la couche web, ceci afin de tester les endpoints HTTP sans charger l’intégralité du contexte Spring de l’application.
La classe utilitaire MockMvc permet à Spring de simuler des requêtes HTTP et de tester les contrôleurs Spring MVC sans démarrer un serveur web.

La migration des tests des contrôleurs REST vers Quarkus demande un peu de travail. En effet, Quarkus préconise l’utilisation de la bibilothèque REST-assured. Cette dernière permet de tester les API REST en facilitant l’envoi de requêtes HTTP et la vérification des réponses de manière fluide et intuitive à l’aide d’une fluent API.

Combinée à l’annotation @QuarkusTest, l’annotation @TestHTTPEndpoint permet de tester spécifiquement un contrôleur REST. Le support par Quarkus des annotations Spring demande quelques ajustements. En effet, la classe QuarkusTestExtension fait appel à la classe SpringWebEndpointProvider qui s’attend à ce qu’une annotation @RequestMapping annote le contrôleur REST testé. Pour être testable, le code de prod a dû être refactoré : il a été nécessaire de déclarer une annotation @RequestMapping au top niveau de chaque contrôleur REST.

Avant la mise en place du test OwnerControllerTests :

@RestController
class OwnerController {

	@GetMapping("/owners/new")
	public TemplateInstance initCreationForm() {

Après la mise en place du test OwnerControllerTests :

@RestController
@RequestMapping("/owners")
class OwnerController {

	@GetMapping("/new")
	public TemplateInstance initCreationForm() {

En prenant comme exemple la méthode testProcessCreationFormSuccess, vous pouvez comparer le code d’un test migré de Spring MockMvc vers REST-assured.
Test avec Spring MockMvc :

@Test
void testProcessCreationFormSuccess() throws Exception {
	mockMvc
		.perform(post("/owners/new").param("firstName", "Joe")
			.param("lastName", "Bloggs")
			.param("address", "123 Caramel Street")
			.param("city", "London")
			.param("telephone", "1316761638"))
		.andExpect(status().is3xxRedirection());
}