Deep Dive Spring Modulith Teil 2: Event-Mechanismen und Teststrategien

Events sind in Spring Modulith ein zentrales Mittel zur losen Kopplung zwischen Modulen. Sie lassen sich zeitgesteuert auslösen, an externe Systeme weiterreichen und gezielt testen. Nachdem im ersten Teil die fachliche Zerlegung einer Spring Boot-Anwendung in klar abgegrenzte Module im Mittelpunkt stand, geht es nun um weitere Event-Mechanismen sowie um Teststrategien, mit denen sich einzelne Module isoliert und realitätsnah überprüfen lassen.

Wenn die Zeit vergeht – zeitgesteuerte Events

Das Beispiel des Portals zur Pflanzenpflege hat bislang Events demonstriert, die Aktionen durchführen, nachdem eine fachliche Verarbeitung („Pflanze registriert“) erfolgt ist. Daneben gibt es oft auch Aktionen, die zeitgesteuert ausgeführt werden sollen. Zum Beispiel sollen jeden Monat Rechnungen für alle Kunden erzeugt und verschickt werden. Zeitgesteuerte Aktionen lassen sich in Spring Boot mit der Annotation @Scheduled umsetzen. Dieser wird beispielsweise ein cron-Ausdruck übergeben, der festlegt, wann die annotierte Methode ausgeführt wird. Solche Methoden lassen sich jedoch schwer testen. Im beschriebenen Beispiel müsste der Test zum Erzeugen von Rechnungen die Zeit künstlich setzen, um dafür zu sorgen, dass Spring die zeitgesteuerte Methode aufruft. Zudem ist ein cron-Ausdruck weniger ausdrucksstark, da er Zeitpunkte („jeweils am Monatsersten um 3 Uhr“) aber keine Ereignisse („Monatswechsel ist erfolgt“) angibt.

Mit der Moments-API, als Bestandteil von Spring Modulith, gibt es einen weiteren Weg, wiederkehrende Aktionen auszuführen. Sie besteht aus einer Reihe von Events, die Spring Modulith am Ende eines Zeitraums (z. B. Stunden-, Tages- oder Quartalswechsel) auslöst und die von der Anwendung konsumiert werden können. So lässt sich beispielsweise beim Monatswechsel auf das Event MonthHasPassed reagieren. Die Verarbeitung erfolgt wie bei regulären Events, in einer mit @EventListener annotierten Methode, die als Argument den gewünschten Event-Typen entgegennimmt. Listing 1 zeigt die Verwendung exemplarisch für den InvoiceGenerator, der beim Monatswechsel die Rechnungen erzeugt.

Listing 1: Der InoviceGenerator wird beim Monatswechsel über das MomentHasPassed-Event getriggert

package nh.demo.plantify.billing.invoice;

import org.springframework.context.event.EventListener;
import org.springframework.modulith.moments.MonthHasPassed;
// ...

@Component
class InvoiceGenerator {

    // ...


    @EventListener
    @Transactional
    void generateInvoices(MonthHasPassed event) {
        
        var month = event.getMonth();
        // Rechnungen für den Monat month erzeugen
        // ...
    }
}

Vorteil an dieser Variante ist, dass der Code mit den Moments Events nicht nur verständlicher ist, als bei der Verwendung von @Scheduler, die Events liefern auch nützliche Informationen (z. B. welcher Monat abgelaufen ist). Das Bean TimeMaschine, das Spring Modulith automatisch im Application Context registriert, löst die Events aus. Für Tests lässt sich deren Zeit künstlich weiterstellen. Alle Events, die normalerweise in diesem vorgespulten Zeitraum ausgelöst würden, werden damit auch im Test ausgelöst.

Events für externe Systeme veröffentlichen

Die Anwendung nutzt den ApplicationEventPublisher, um fachliche Events innerhalb der Anwendung zu veröffentlichen. Mit Spring Modulith lassen sich darüber Events auch an externe Systeme wie Kafka, RabbitMQ oder einen JMS Server übergeben. Dafür stellt Spring Modulith Broker-spezifische Starter-Module zur Verfügung, die sich über die Maven- oder Gradle-Konfiguration der Anwendung einbinden lassen.

Die Annotation @Externalized an einer Event-Klasse drückt aus, dass das Event an ein externes System geschickt werden soll. Listing 2 zeigt das InvoiceCreatedEvent, das die Anwendung an Kafka schickt. Das target-Attribute enthält einen Broker-spezifischen Ausdruck, der angibt, wie das Event geroutet werden soll. Im Beispiel wird das Event an das Kafka-Topic invoices geschickt, wobei die im Event enthaltene ownerId den Message Key bildet.

Listing 2: Ein Application Event, das über Kafka veröffentlicht wird

package nh.demo.plantify.billing.invoice;


import org.springframework.modulith.events.Externalized;
// ...


@Externalized(target = "invoices::#{#this.ownerId()}")
public record InvoiceGeneratedEvent(
    UUID ownerId,
    YearMonth billingPeriod,
    BigDecimal amount
) { }

In der kommenden Version 2.1 implementiert Spring Modulith das Outbox-Pattern für das Versenden von @Externalized-Events. Damit stellt es sicher, dass jedes Event mindestens einmal erfolgreich an das externe System übermittelt wurde. Dazu wird intern das Framework Namastack verwendet, das eine Implementierung des Outbox-Patterns für Spring Boot-Anwendungen bereitstellt. Um das Verhalten für die eigene Anwendung zu aktivieren, muss lediglich eine Spring Property gesetzt werden. Im Rahmen der Ankündigung dieses Features hat sich eine interessante Diskussion über die konkrete Implementierung durch Namastack und deren Konsequenzen zwischen Roland Beisel (Lead von Namastack Outbox) und Gunnar Morling (ehem. Tech-Lead von Debezium) entwickelt.

Modularisierte Datenbankmigrationen

Bis hierhin lag der Fokus auf der Aufteilung des Java-Codes in abgeschlossene Application Modules. Oft gehören zu einer Anwendung aber auch Migrationsskripte für die Datenbank, die beispielsweise Flyway verwaltet. Spring Boot führt diese beim Starten der Anwendung automatisch aus und sorgt dafür, dass die Datenbank auf einem für die aktuelle Version der Anwendung passenden Stand ist. Typischerweise finden sich die Flyway-Skripte einer Anwendung in einem zentralen migration-Verzeichnis als Dateien mit einer Versionsnummer im Namen. Die zentrale Verwaltung und Versionierung der Migrationsskripte widersprechen allerdings der Idee der Modularisierung.

Aus diesem Grund bietet Spring Modulith die Möglichkeit, die Skripte nicht nur zentral, sondern pro Modul abzulegen und zu versionieren. So kann jedes Modul seine eigene Historie von Migrationsskripten pflegen. Die übergeordnete Reihenfolge ergibt sich aus den Modulabhängigkeiten. Die modulspezifischen Flyway-Dateien gilt es in einem Unterordner abzulegen, der genauso wie das entsprechende Modul heißt. Zusätzlich kommt das Verzeichnis __root zum Einsatz, in dem globale Migrationsskripte ihren Platz finden. Die Anwendung führt die Skripte in diesem Verzeichnis immer als Erstes aus. Abbildung 1 zeigt die Migrationsskripte von Plantify.

Damit die Modulstruktur auch in der Datenbank eingehalten wird, definiert jedes Modul sein eigenes Datenbankschema in Postgres. Im __root-Ordner befinden sich die Skripte zum Anlegen der Tabellen für die Event Publication Registry. In einem Integrationstest führt Spring Modulith immer nur die Skripte aus, deren Modul gerade getestet wird, und stellt damit sicher, dass es keine unerwünschten Referenzen zwischen den Skripten gibt.