Technologie-Exkurse

Bei Node- und Playwright-Projekten werden mehrere Installationsebenen leicht verwechselt. Der folgende Überblick zeigt, was auf dem Betriebssystem, im Projekt und im Benutzerprofil liegt.

Beispiel im PROCUREX-Projekt

Windows/Linux:  Node.js ─────────────── Voraussetzung für npm
                               │
PROCUREX:      npm ci ─────────┼─► procurex-frontend/node_modules
                               │       └─ @playwright/test
                               │
                               └─► npx playwright test

Benutzerprofil: npx playwright install chromium ─► Playwright-Browser-Cache
Git:            package.json + package-lock.json + e2e/ ─► versioniert
                node_modules + Browser-Cache       ─► nicht versioniert

Die wichtigsten Befehle

Vollständige Playwright-/Selenium-Dokumentation öffnen →

PROCUREX liegt als Git-Repository auf GitHub, während Jira und Confluence bei Atlassian laufen. Das wirft die naheliegende Frage auf, worin sich die großen Git-Hosting-Plattformen eigentlich unterscheiden – und warum man sich in der Praxis für die eine oder andere entscheidet.

Direktvergleich

Preise sind Richtwerte (Einstiegs- bzw. mittlere Stufe, Stand ca. 2025) und ändern sich laufend – vor einer Entscheidung immer die aktuelle Preisseite des Anbieters prüfen.

GitHub

Mit weit über 100 Millionen Entwicklerkonten und mehreren hundert Millionen Repositories ist GitHub die mit Abstand größte Plattform und faktisch der Standard für Open-Source-Projekte. Stärken sind das riesige Ökosystem (Actions, Marketplace, Copilot, Discussions, Sponsors) und die Sichtbarkeit für Personal Branding und Recruiting. Der kostenlose Plan deckt unbegrenzt öffentliche wie private Repositories ab; bezahlte Stufen bringen mehr CI/CD-Minuten, erweiterte Sicherheits- und Governance-Funktionen.

GitLab

GitLab versteht sich als „Single Application“ für den kompletten DevOps-Lebenszyklus – Planung, Code, CI/CD, Security-Scanning und Deployment in einem Werkzeug statt vieler Einzeltools. Die Community Edition lässt sich vollständig kostenlos selbst betreiben, was GitLab besonders bei Unternehmen mit Compliance- oder On-Premise-Anforderungen beliebt macht. Die kostenpflichtigen Stufen (Premium, Ultimate) sind spürbar teurer als vergleichbare GitHub-Pläne, bieten dafür aber tiefere integrierte Security- und Compliance-Funktionen ohne Zusatzprodukte.

Bitbucket

Bitbucket punktet vor allem dort, wo bereits Jira und Confluence im Einsatz sind – genau wie im PROCUREX-Projekt: Commits, Branches und Pull Requests lassen sich direkt mit Jira-Vorgängen verknüpfen. Der kostenlose Plan reicht für Teams bis 5 Personen; für größere Teams sind die bezahlten Stufen aber vergleichsweise günstig. Außerhalb des Atlassian-Ökosystems ist die Marktdurchdringung deutlich geringer als bei GitHub oder GitLab.

Weitere Plattformen

Azure DevOps (Microsoft) bündelt Boards, Repos, Pipelines, Test Plans und Artifacts und wird häufig dort eingesetzt, wo bereits stark auf Azure und .NET gesetzt wird. Gitea und dessen Fork Forgejo sind schlanke, quelloffene Git-Server für alle, die volle Kontrolle über die Infrastruktur wollen. Codeberg ist eine gemeinnützige, spendenfinanzierte SaaS-Instanz auf Forgejo-Basis – kostenlos, werbefrei und beliebt in der FOSS-Community als Alternative zu großen kommerziellen Anbietern. SourceHut verfolgt bewusst einen minimalistischen, textbasierten Ansatz (E-Mail-Patches statt Weboberfläche) und richtet sich an eine kleine, aber treue Nutzergruppe. Historisch relevant, aber heute kaum noch genutzt sind SourceForge und Launchpad.

PROCUREX wird nicht auf einem klassischen Java-EE-Anwendungsserver betrieben, sondern als Spring-Boot-Anwendung mit eingebettetem Tomcat gestartet (spring-boot-starter-web in allen Fachmodulen). Das ist ein bewusster architektonischer Unterschied zur „alten Welt“ der Application Server – dieser Exkurs zeigt, was WebSphere & Co. eigentlich sind und warum viele neue Projekte heute darauf verzichten.

Direktvergleich

Versionsangaben und Preise sind grobe Richtwerte (Stand ca. 2025/26); Fix-Packs, Support-Zeiträume und reale Lizenzangebote ändern sich laufend und hängen stark von Rabatten, Core-Zahl und Vertragslaufzeit ab. PROCUREX selbst erzwingt per Maven-Enforcer-Regel eine Java 17-Baseline und nutzt Spring Boot 3.3.4 mit eingebettetem Tomcat 10.1.x (Jakarta EE 10) – siehe pom.xml, Regel enforce-java-17-baseline.

Support-Status & Java-Empfehlung

Neben der reinen Versionsnummer entscheidet vor allem der Support-Zeitraum und die empfohlene (nicht nur minimal unterstützte) Java-Version, ob ein Server für ein Neuprojekt noch infrage kommt. Diese Tabelle fasst das pro Server zusammen.

Support-Enddaten sind Näherungswerte (Stand ca. 2025/26) und variieren je nach Support-Vertrag (Premier/Extended/Sustaining); für verbindliche Daten zählt immer die jeweilige Herstellermatrix. PROCUREX nutzt aktuell Java 17 – kompatibel mit allen hier gelisteten aktuellen Serverversionen, nicht aber mit den älteren javax.*-Linien (WebSphere traditional, WebLogic 12.2.1.4, EAP 7.4, Tomcat 9.0.x).

Wichtige Versionssprünge

Bei allen Servern gab es einen Bruch, der weit mehr war als eine normale Minor-Version: den Wechsel von Java EE (Namespace javax.*) zu Jakarta EE (Namespace jakarta.*), nachdem Oracle die Java-EE-Marke 2019 nicht an die Eclipse Foundation weitergeben wollte. Jede Anwendung, die von einer alten auf eine neue Serverversion wechselt, muss deshalb javax.servlet.*, javax.persistence.* usw. per Suchen-und-Ersetzen auf jakarta.* umstellen – ein mechanischer, aber projektweiter Eingriff.

PROCUREX ist von der javax→jakarta-Umstellung nicht betroffen, weil es von Anfang an auf Spring Boot 3 / Tomcat 10.1.x (bereits jakarta.*) aufgesetzt wurde – ein Vorteil, den nur Neuprojekte ohne Altlast-Migration haben.

Klassische Java-EE-Anwendungsserver

WebSphere, WebLogic und JBoss EAP entstammen einer Zeit, in der mehrere Anwendungen (WAR-Dateien) gemeinsam auf einem zentral verwalteten, langlaufenden Server-Prozess deployt wurden. Dafür bringen sie eingebaute Funktionen wie verteilte Transaktionen (JTA), Nachrichtenwarteschlangen (JMS), Clustering, Failover und zentrales Administrationstooling mit – Funktionen, die früher aufwendig selbst gebaut werden mussten. Der Preis dafür sind hohe Lizenzkosten, träge Release-Zyklen und ein Betriebsmodell, das schlecht zu Containern passt, weil ein Server-Prozess viele Anwendungen gleichzeitig trägt.

Leichte Servlet-Container und eingebettete Server

Tomcat, Jetty und Undertow sind selbst keine vollständigen Jakarta-EE-Server, sondern schlanke HTTP-/Servlet-Engines. Frameworks wie Spring Boot betten einen dieser Container direkt in die Anwendung ein: Aus einem mvn package entsteht ein ausführbares Fat-JAR, das per java -jar app.jar startet – ohne separate Serverinstallation, ohne WAR-Deployment auf einen extern verwalteten Anwendungsserver. Genau dieses Modell nutzt PROCUREX in allen Fachmodulen.

Warum PROCUREX keinen klassischen Application Server braucht

Im Microservice-Zuschnitt von PROCUREX bekommt jeder Bounded Context (Katalog, Bestellung, Genehmigung, Rechnung, …) einen eigenen, kleinen Prozess statt eines gemeinsam genutzten Servers. Ein eingebetteter Tomcat pro Container passt zu diesem „ein Prozess pro Container“-Muster aus Kubernetes und Helm deutlich besser als ein zentraler WebSphere- oder WebLogic-Cluster, auf dem mehrere Anwendungen gemeinsam liefen. Zusätzlich entfällt die kommerzielle Lizenzierung vollständig, was für ein Lernprojekt ohne Enterprise-Support-Vertrag ohnehin die einzig praktikable Wahl ist.

Die Katalogsuche von PROCUREX läuft heute über eine einfache LIKE-Abfrage direkt in PostgreSQL (CatalogItemRepository.search()). Dieser Exkurs zeigt, was Elasticsearch & Co. zusätzlich bieten, warum diese Tools JVM-lastig und lizenzrechtlich bewegt sind – und ab wann sich ihr Einsatz für PROCUREX lohnen würde.

Direktvergleich

Versionsangaben sind Richtwerte (Stand ca. 2025/26) und ändern sich mit jedem Major-Release. Elasticsearch und OpenSearch bündeln jeweils eine eigene JDK-Runtime im Serverpaket, sodass die Java-Version des restlichen Projekts (bei PROCUREX: Java 17) unabhängig davon ist.

Der Lizenz-Bruch bei Elasticsearch

Elasticsearch stand bis Version 7.10 (2021) unter der freizügigen Apache-2.0-Lizenz. Aus Sorge, dass Cloud-Anbieter wie AWS gehostete Elasticsearch-Dienste anbieten, ohne zum Projekt beizutragen, wechselte Elastic NV zur Server Side Public License (SSPL) bzw. zur proprietären Elastic License. AWS reagierte darauf mit einem eigenständigen Fork unter Apache 2.0: OpenSearch. Erst 2024 (ab Version 8.16 bzw. der 9.x-Linie) machte Elastic einen Teil-Rückzieher und bietet seither zusätzlich eine AGPL-v3-Variante als Open-Source-Option an. Wer heute zwischen Elasticsearch und OpenSearch wählt, wählt damit auch zwischen zwei Lizenzphilosophien und zwei seit 2021 getrennten Entwicklungslinien.

Warum PROCUREX (aktuell) kein Elasticsearch braucht

Ein Suchcluster wie Elasticsearch oder OpenSearch lohnt sich vor allem bei sehr großen, häufig wachsenden Datenmengen, Relevanz-Ranking, Facettensuche (Filter nach Kategorie, Preis, Lieferant gleichzeitig) oder Volltextsuche über mehrere Sprachen und Tippfehler hinweg. Der PROCUREX-Katalog ist dafür aktuell zu klein: Eine LIKE-Abfrage über Name und SKU in PostgreSQL (procurex-catalog/.../CatalogItemRepository.java) reicht für die Datenmengen eines Lernprojekts völlig aus und spart einen zusätzlichen, separat zu betreibenden Cluster samt eigenem Speicher- und Update-Management. Der nächste sinnvolle Schritt wäre nicht gleich Elasticsearch, sondern zunächst pg_trgm für unscharfe Suche direkt in PostgreSQL – erst bei echtem Skalierungsbedarf würde ein dedizierter Suchserver Sinn ergeben.

PROCUREX speichert alle Fachdaten in einer gemeinsam genutzten PostgreSQL-Instanz (shared-postgres, Datenbank procurex_db); Schemamigrationen laufen pro Modul über Flyway (flyway-database-postgresql, siehe z. B. procurex-catalog/pom.xml), und Integrationstests starten testweise postgres:16-alpine per Testcontainers. Dieser Exkurs zeigt, wie PostgreSQL im Vergleich zu anderen relationalen Datenbanken und zu NoSQL-Alternativen einzuordnen ist.

Direktvergleich: relationale Datenbanken

Versionsangaben und Preise sind Richtwerte (Stand ca. 2025/26) und ändern sich mit jedem Release bzw. Lizenzmodell des Anbieters.

NoSQL-Kontrast: wenn ein starres Schema nicht passt

Relationale Datenbanken sind nicht immer die beste Wahl. MongoDB speichert Daten als flexible JSON-ähnliche Dokumente ohne festes Schema und eignet sich für stark variierende oder tief verschachtelte Datenstrukturen. Redis ist eine In-Memory-Key-Value-Datenbank, die vor allem als Cache, Session-Store oder für Warteschlangen eingesetzt wird – nicht als primärer Datenspeicher für transaktionale Geschäftsdaten. Beide ergänzen relationale Datenbanken typischerweise, statt sie zu ersetzen.

Lizenz-Dramen sind kein Einzelfall

Der Elasticsearch-Lizenzwechsel aus dem Suchtechnologie-Exkurs steht nicht allein: Auch MongoDB wechselte 2018 von AGPL zur selbst entworfenen SSPL, um Cloud-Anbieter am kostenlosen Weiterverkauf als Managed Service zu hindern – die SSPL gilt bis heute nicht als Open-Source-Lizenz im Sinne der Open Source Initiative. Redis vollzog 2024 einen ganz ähnlichen Schritt weg von der freizügigen BSD-Lizenz, woraufhin die Linux Foundation den bis dahin letzten BSD-Stand als Valkey weiterführte – genau das Muster, das bei Elasticsearch zu OpenSearch führte. Cloud-Hyperscaler als kostenlose Trittbrettfahrer sind der wiederkehrende Auslöser für diese Lizenzwechsel in der gesamten Datenbank- und Such-Branche.

Warum PROCUREX auf PostgreSQL setzt

Bestellungen, Rechnungen und Genehmigungen sind klassisch relationale, stark konsistenzkritische Geschäftsdaten mit festen Beziehungen (Bestellung → Positionen → Lieferant, Rechnung → Bestellung) – ein Anwendungsfall, für den ACID-Transaktionen und feste Schemata (per Flyway versioniert) besser passen als ein schemaloser Dokumentenspeicher. PostgreSQL bietet dafür ausgereifte Transaktionsgarantien, ist vollständig kostenlos und quelloffen unter einer sehr permissiven Lizenz (kein SSPL-/Elastic-License-Risiko), und Spring Data JPA/Hibernate unterstützen es als Referenzdatenbank erstklassig. Ein Cache wie Redis oder ein Dokumentenspeicher wie MongoDB wären ergänzende, aber keine ersetzenden Bausteine – und sind für den aktuellen PROCUREX-Umfang nicht notwendig.

Suns Katalog „Core J2EE Patterns“ (Alur/Crupi/Malks, 2001) hat für EJB-basierte Anwendungen Muster wie Data Access Object, Session Facade, Business Delegate oder Service Locator geprägt. PROCUREX verwendet keine EJBs mehr, folgt aber inhaltlich denselben Entwurfsproblemen – nur mit modernen Werkzeugen gelöst. Die Paketstruktur jedes Fachmoduls (domain, application, port, adapter/in, adapter/out, siehe z. B. procurex-catalog/src/main/java/com/procurex/catalog/) setzt bewusst eine hexagonale Architektur (Ports & Adapters) um. Darunter liegt eine noch ältere Schicht: die 23 „Gang of Four“ (GoF)-Entwurfsmuster, aus denen sich viele J2EE-Patterns erst zusammensetzen – dieser Exkurs prüft am Ende alle 23 einzeln gegen den PROCUREX-Code.

Klassische J2EE-Muster und ihre moderne Entsprechung

Die rechte Spalte verweist auf real existierenden PROCUREX-Code (Stand dieses Exkurses); Klassennamen können sich mit künftigen Refactorings ändern.

Hexagonale Architektur in PROCUREX

Am Modul procurex-catalog lässt sich der Aufbau direkt ablesen: ein REST-Adapter nimmt Anfragen entgegen, ein Application-Service kapselt die Fachlogik und implementiert dabei einen Port, den andere Module direkt als Spring-Bean injizieren – ganz ohne REST-Aufruf zwischen den Modulen.

Innerhalb eines Moduls fließen Aufrufe von außen nach innen (Adapter → Application → Domäne) und wieder hinaus (Application → Adapter → Datenbank). Zwischen Modulen läuft die Kommunikation nicht über HTTP, sondern über ein gemeinsames Port-Interface, das der Spring-Container zur Laufzeit auflöst.

Warum Dependency Injection den Service Locator abgelöst hat

Im klassischen Service-Locator-Muster fragt der Client zur Laufzeit aktiv bei einer zentralen Registry (typischerweise über JNDI) nach einer Implementierung – der Aufruf ist im Code unsichtbar und lässt sich nur schwer durch ein Test-Double ersetzen. Dependency Injection dreht das um: Der Spring-Container reicht die passende Implementierung beim Erzeugen eines Objekts direkt in den Konstruktor. Das macht Abhängigkeiten explizit im Code sichtbar, erlaubt in Tests das einfache Einsetzen von Mocks (z. B. in CartSubmissionServiceTest) und verhindert verstreute, schwer auffindbare JNDI-Lookups quer durch die Anwendung.

Die 23 GoF-Muster: welche PROCUREX tatsächlich nutzt

Die J2EE-Core-Patterns von oben sind Enterprise-spezifische Kombinationen einer viel älteren, allgemeineren Quelle: dem 1994 erschienenen Katalog „Design Patterns: Elements of Reusable Object-Oriented Software“ von Gamma, Helm, Johnson und Vlissides – kurz „Gang of Four“ (GoF). Business Delegate etwa ist im Kern eine Kombination aus Proxy und Facade; Session Facade ist schlicht Facade auf EJB-Ebene. Die folgenden drei Tabellen ordnen alle 23 GoF-Muster ihren drei Kategorien zu und prüfen ehrlich, wo PROCUREX sie tatsächlich einsetzt, wo ein Framework sie unsichtbar für den Entwickler übernimmt – und wo bewusst darauf verzichtet wird, weil kein passendes Problem existiert.

Erzeugungsmuster (Creational)

Strukturmuster (Structural)

Verhaltensmuster (Behavioral)

„Ja“ bedeutet handgeschriebener PROCUREX-Code; „indirekt/konzeptionell“ bedeutet, dass Spring, Hibernate oder Kafka das Muster für PROCUREX unsichtbar umsetzen. Das ist beabsichtigt: moderne Frameworks nehmen Entwicklern viele GoF-Muster als wiederkehrendes Handwerkszeug ab, statt sie jedes Mal neu zu implementieren.

PROCUREX übersetzt Fehler zentral in GlobalExceptionHandler (procurex-common/.../web/GlobalExceptionHandler.java): vier Domain-Exceptions (NotFoundException, ConflictException, DomainRuleViolationException, ForbiddenException) werden per @RestControllerAdvice auf passende HTTP-Status-Codes und ein standardisiertes ProblemDetail abgebildet, angereichert um eine Correlation-ID aus CorrelationIdFilter. Dieser Exkurs ordnet das in die allgemeine Java-Enterprise-Historie ein – von J2EE-Checked-Exceptions bis zum heutigen RFC-7807-Standard.

Checked vs. Unchecked Exceptions: die große J2EE-Lehre

Frühe Java-EE-APIs (java.rmi.RemoteException, javax.naming.NamingException, java.sql.SQLException) waren fast alle checked – der Compiler zwang jeden Aufrufer, sie entweder zu fangen oder in der eigenen throws-Klausel weiterzureichen. In der Praxis führte das zu leeren catch-Blöcken, aufgeblähten Methodensignaturen und Exceptions, die durch fünf Schichten hindurch deklariert werden mussten, ohne dass eine davon sinnvoll reagieren konnte. Rod Johnsons Spring-Philosophie (ab „J2EE without EJB“, 2004) drehte das bewusst um: Sprachs eigene DataAccessException-Hierarchie ist komplett unchecked und wrappt SQLException intern. PROCUREX folgt exakt diesem Muster – alle vier Domain-Exceptions erben direkt von RuntimeException, nirgends im Code steht eine throws-Klausel für sie.

Zentrale Fehlerübersetzung: Spring vs. Jakarta EE

Sowohl Spring als auch Jakarta EE (über JAX-RS) lösen dasselbe Problem – Exceptions an einer zentralen Stelle in HTTP-Antworten übersetzen –, nur mit unterschiedlicher Mechanik.

Beide modernen Ansätze (Spring-Advice, JAX-RS-ExceptionMapper) verfolgen dieselbe Idee: Controller/Ressourcen bleiben von Fehlerbehandlungscode frei, ein zentraler Ort entscheidet über das HTTP-Antwortformat.

RFC 7807 Problem Details für HTTP APIs

RFC 7807 (mittlerweile abgelöst durch RFC 9457, inhaltlich nahezu unverändert) standardisiert ein JSON-Format für Fehlerantworten mit den Feldern type, title, status, detail und instance, erweiterbar um beliebige zusätzliche Felder. Seit Spring Framework 6 / Boot 3 gibt es dafür die eingebaute Klasse org.springframework.http.ProblemDetail – kein externes Zusatzpaket mehr nötig. So sieht die reale Antwort aus, wenn CatalogService.findOrThrow(id) eine NotFoundException wirft:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Katalogartikel nicht gefunden: 3fa8...e21b",
  "instance": "/api/v1/catalog-items/3fa8...e21b",
  "correlationId": "9c2e4b7a-1f3d-4a2e-8b6c-7d0a5e9f1c22"
}

detail stammt direkt aus ex.getMessage(), instance aus der Request-URI, und correlationId ist ein von GlobalExceptionHandler.problem(...) zusätzlich gesetztes Property – ProblemDetail erlaubt beliebige weitere Properties über setProperty(...), genau wie bei der Validierungsantwort, die zusätzlich ein errors-Array mit Feldfehlern anhängt.

Jakarta Bean Validation: die Exception, die eigentlich ein Sammelbecken ist

Woher kommt die Validierungsantwort überhaupt? CreateCatalogItemRequest annotiert seine Felder mit Jakarta Bean Validation (JSR 380, Referenzimplementierung Hibernate Validator) – derselbe Standard, den auch klassische Jakarta-EE-/JAX-RS-Anwendungen nutzen:

public record CreateCatalogItemRequest(
        @NotBlank String sku,
        @NotBlank String name,
        @NotBlank String category,
        @NotNull UUID supplierId,
        @NotNull @DecimalMin(value = "0.0", inclusive = false) BigDecimal priceAmount,
        @NotBlank String priceCurrency,
        @NotBlank String unit) {
}

Der @Valid-Parameter in CatalogController.create(...) löst die Validierung aus, bevor die Controller-Methode überhaupt betreten wird. Wichtig dabei: Bean Validation sammelt alle verletzten Constraints eines Objekts (fehlender sku und negativer Preis gleichzeitig) und wirft danach eine einzige Exception mit der vollständigen Liste – kein Fail-Fast bei der ersten Verletzung. Das gibt dem Client in einer Antwort alle Korrekturen mit, statt ihn mehrfach nachfragen zu lassen.

Die Constraint-Annotationen selbst (@NotBlank, @NotNull, @DecimalMin – Package jakarta.validation.constraints) sind in beiden Welten identisch; nur die Exception-Klasse, die sie am Ende auslösen, unterscheidet sich, weil Spring MVC seinen eigenen Wrapper um den Jakarta-Validation-Provider legt.

Wie eine Exception in PROCUREX zur HTTP-Antwort wird

Die Exception propagiert unverändert durch Service und Controller – erst GlobalExceptionHandler entscheidet über Status-Code und Antwortformat. Das hält die Fachlogik frei von HTTP-Details und macht neue Exceptions an einer einzigen Stelle ergänzbar.

Weitere Best Practices im PROCUREX-Code – und eine bewusste Lücke

• Nicht schlucken, sondern loggen und weitermachen: AbstractOutboxRelay.relay() fängt pro Event ein Exception e, loggt es mit vollem Stacktrace (log.error(..., e)) und lässt den Kafka-Versand beim nächsten Scheduler-Lauf erneut versuchen – ein defekter Event blockiert nicht die ganze Relay-Schleife, aber der Fehler verschwindet auch nicht spurlos.
• Aufräumen im finally: CorrelationIdFilter entfernt den MDC-Eintrag in einem finally-Block – notwendig, weil Tomcat-Threads aus einem Pool wiederverwendet werden und ein vergessener MDC.remove(...) sonst Correlation-IDs zwischen unabhängigen Requests vermischen würde.
• Fachliche und technische Fehler trennen: ForbiddenException wird bewusst nicht mit Spring Securitys eigenem 403 (fehlende Rolle am Endpunkt) vermischt, sondern signalisiert einen datenabhängigen Fachregel-Verstoß (z. B. Bestellwert über dem Schwellenwert der Rolle) – zwei verschiedene Ursachen, zwei verschiedene Exception-Typen.
• Bewusste Lücke: GlobalExceptionHandler hat keinen @ExceptionHandler(Exception.class)-Catch-all. Eine wirklich unerwartete RuntimeException (z. B. eine NullPointerException) fällt dadurch auf Spring Boots Standard-Fehlerbehandlung zurück statt auf ein konsistentes ProblemDetail mit Correlation-ID. Das ist kein Sicherheitsproblem – Spring Boot versteckt Stacktrace und Nachricht standardmäßig (server.error.include-stacktrace=never) –, aber ein inkonsistentes Antwortformat für genau den Fall, in dem Konsistenz am meisten zählt. Ein generischer Catch-all-Handler mit HTTP 500 wäre der naheliegende nächste Schritt.

Exceptions in asynchronen Kafka-Consumern: ein anderes Spiel als REST

Alles bisher Gezeigte gilt für synchrone REST-Aufrufe, bei denen am Ende ein HTTP-Client auf eine Antwort wartet. Sobald PROCUREX über Kafka kommuniziert, gibt es diesen Client nicht mehr – eine Exception kann nicht einfach in eine HTTP-Antwort übersetzt werden, weil keine offene Verbindung mehr existiert, in die sie zurückfließen könnte. NotificationConsumer.onEvent(...) (Modul procurex-notification) zeigt, wie PROCUREX damit umgeht:

@KafkaListener(groupId = "procurex-notification", topics = { ... })
@Transactional
public void onEvent(ConsumerRecord<String, String> record) {
    ...
    try {
        repository.save(new InAppNotification(eventId, ...));
    } catch (DataIntegrityViolationException ignored) {
        // Redelivery is expected; the unique event id makes the consumer idempotent.
    }
}

Der catch-Block hier verstößt bewusst gegen die übliche Regel „nicht pauschal fangen“ – aber richtig angewendet: Er fängt genau eine, sehr spezifische Exception (keine allgemeine Exception), die einen erwarteten Fall abbildet (Kafka liefert Nachrichten mindestens einmal, ggf. auch doppelt aus), und der Kommentar erklärt, warum das Verschlucken hier sicher ist – der eindeutige eventId-Constraint macht den Consumer idempotent, ein zweiter Insert-Versuch derselben Event-ID darf einfach verworfen werden. Für jeden anderen, nicht abgefangenen Fehler gibt es dagegen keinen eigenen Mechanismus wie GlobalExceptionHandler: Die Exception verlässt onEvent(...), Spring Kafka übernimmt mit seiner eigenen Fehlerbehandlung (CommonErrorHandler/DefaultErrorHandler) – standardmäßig wird die Nachricht mit Backoff erneut zugestellt.

Ohne Dead-Letter-Topic kann eine Nachricht, die bei jedem Verarbeitungsversuch dieselbe (nicht abgefangene) Exception auslöst, den Consumer dauerhaft blockieren („Poison Pill“) – ein bekanntes Risiko bei Kafka-Consumern ohne konfigurierten DeadLetterPublishingRecoverer, das für den aktuellen PROCUREX-Umfang bewusst noch nicht adressiert ist.

Weitere gängige Spring-/Jakarta-Exceptions und ihr Status in PROCUREX

Über die vier eigenen Domain-Exceptions hinaus wirft der Stack unter der Haube laufend weitere, framework-eigene Exceptions. Diese Übersicht zeigt ehrlich, welche davon GlobalExceptionHandler heute in ein konsistentes ProblemDetail übersetzt – und welche (noch) nicht.

Kein einziges dieser Zeilen ist ein Sicherheitsrisiko – Spring Boots Default-Fehlerbehandlung leckt keine internen Details. Es ist aber ein Konsistenz-Thema: Die Antwortform (RFC-7807-ProblemDetail mit Correlation-ID) gilt heute nur für die fünf explizit behandelten Fälle, nicht für den gesamten Fehlerraum der Anwendung.

Allgemeine Java-Faustregeln, unabhängig vom Framework

PROCUREX besteht aus sieben fachlichen Maven-Modulen, die nicht direkt REST-Aufrufe untereinander machen, sondern über Kafka lose gekoppelt sind: Ein Modul schreibt ein Event, ein anderes reagiert darauf, ohne dass beide gleichzeitig erreichbar sein müssen. Kern davon ist das Transactional-Outbox-Pattern in procurex-common/.../outbox/ (AbstractOutboxEvent, AbstractOutboxRelay), bereits im Entwurfsmuster-Exkurs als Template-Method-Beispiel gezeigt – dieser Exkurs geht auf die Messaging-Seite selbst ein: welche Events es gibt, wie sie serialisiert und versioniert werden, und wie Konsumenten mit doppelter Zustellung umgehen.

Das Transactional-Outbox-Pattern: Problem und Lösung

Ohne Outbox-Pattern entsteht ein klassisches verteiltes Konsistenzproblem: Schreibt ein Service zuerst in die Datenbank und danach auf Kafka, kann der Prozess zwischen beiden Schritten abstürzen – die fachliche Änderung ist da, das Event fehlt (oder umgekehrt bei vertauschter Reihenfolge). PROCUREX löst das, indem OrderService.publish(...) das Event nicht direkt an Kafka sendet, sondern als Zeile in einer outbox_event-Tabelle in derselben Transaktion wie die fachliche Änderung speichert:

private void publish(String topic, UUID aggregateId, Object event) {
    try {
        String payload = objectMapper.writeValueAsString(event);
        outboxRepository.save(new OrderingOutboxEvent(topic, aggregateId.toString(), payload));
    } catch (JsonProcessingException e) {
        throw new IllegalStateException("Event konnte nicht serialisiert werden: " + topic, e);
    }
}

Bemerkenswert: JsonProcessingException ist eine checked Exception (siehe Exception-Exkurs) – sie wird hier bewusst in eine unchecked IllegalStateException gewrappt, weil eine fehlgeschlagene Serialisierung eines internen Records ein Programmierfehler ist, den kein Aufrufer sinnvoll behandeln kann. Ein separater, per @Scheduled laufender OrderingOutboxRelay liest unveröffentlichte Zeilen alle zwei Sekunden aus und sendet sie erst dann an Kafka – Datenbank-Commit und Kafka-Versand sind damit entkoppelt, aber garantiert konsistent zueinander.

Der Themenkatalog: alle sechs PROCUREX-Topics

Namenskonvention: procurex.<produzierendes Modul>.<Ereignis in Vergangenheitsform>.v1. Die .v1-Endung ist PROCUREX' Versionierungsstrategie – ein inkompatibler Schema-Wechsel bekäme ein neues Topic (.v2) statt das bestehende stillschweigend zu ändern, sodass alte Konsumenten nicht plötzlich unlesbare Nachrichten erhalten.

Wie zwei Konsumenten dieselben Events unterschiedlich nutzen

procurex-notification und procurex-audit hören auf dieselben sechs Topics, aber mit komplett unterschiedlichem Zweck: Notification baut aus dem Topic-Namen eine rollenspezifische Benachrichtigung (NotificationText.from(topic, orderId)), Audit schreibt jedes Event unverändert und vollständig in ein Audit-Log – reines Event Sourcing „light“, ohne den fachlichen Ablauf zu beeinflussen. Beide lösen dieselbe Herausforderung – Kafka liefert Nachrichten mindestens einmal, nie exakt einmal – mit demselben Muster: einer eindeutigen Event-ID im Kafka-Header plus einem Unique-Constraint in der jeweiligen Konsumenten-Tabelle.

Zwischen Outbox-Tabelle und Kafka-Versand liegt bewusst eine Verzögerung von bis zu zwei Sekunden (Scheduler-Intervall) – das ist der Preis für die Konsistenzgarantie: lieber leicht verzögert als inkonsistent.

Alternativen zum Transactional Outbox

„Wir haben Tests“ sagt wenig darüber aus, was diese Tests eigentlich prüfen und wie teuer sie in Laufzeit und Wartung sind. PROCUREX nutzt sechs unterscheidbare Testarten, jede mit einem anderen Zweck, einer anderen Laufzeit und einer anderen Grenze dessen, was sie beweisen kann. Dieser Exkurs ordnet sie in die klassische Testpyramide ein und zeigt für jede Ebene ein reales PROCUREX-Beispiel.

Die sechs Ebenen im Überblick

Warum Ebene 1 und 2 ohne Spring-Kontext auskommen

CatalogItemTest braucht überhaupt keine Mocks, weil CatalogItem ein reines Domain-Objekt ohne Abhängigkeiten ist. CartSubmissionServiceTest braucht Mocks, aber keinen Spring-Kontext:

@ExtendWith(MockitoExtension.class)
class CartSubmissionServiceTest {
    @Mock private SupplierLookupPort supplierLookupPort;
    @Mock private CatalogLookupPort catalogLookupPort;
    @Mock private OrderCreationPort orderCreationPort;

    private CartSubmissionService service;

    @BeforeEach
    void setUp() {
        service = new CartSubmissionService(supplierLookupPort, catalogLookupPort, orderCreationPort);
    }
}

Das ist direkt eine Konsequenz aus dem Entwurfsmuster-Exkurs: Weil CartSubmissionService seine Abhängigkeiten über den Konstruktor bekommt (Dependency Injection) statt sie sich selbst über einen Service Locator zu besorgen, lässt sich der Service in Zeile new CartSubmissionService(...) direkt mit drei Mocks statt drei echten Modulen instanziieren – ganz ohne Spring, ohne Datenbank, ohne Netzwerk. Genau diese Testbarkeit ist der praktische Grund, warum Dependency Injection den Service Locator verdrängt hat.

Contract-Test und Web-Slice-Test in einem: BuyerContractBase

Spring Cloud Contract generiert aus shouldSubmitCart.groovy zur Build-Zeit sowohl einen JUnit-Test als auch einen WireMock-Stub. Der generierte Test läuft gegen eine reale, aber isolierte @WebMvcTest-Instanz von CartController – die fachliche Logik (CartSubmissionService) ist gemockt, aber HTTP-Routing, JSON-Serialisierung und die Spring-Security-Kette sind echt:

@WebMvcTest(CartController.class)
@Import(SecurityConfig.class)
public abstract class BuyerContractBase {

    @MockBean
    protected CartSubmissionService cartSubmissionService;

    @BeforeEach
    void setUpContractBase() {
        when(cartSubmissionService.submit(any(), any(), any(), any(), any())).thenReturn(ORDER_ID);
        RestAssuredMockMvc.mockMvc(MockMvcBuilders.webAppContextSetup(context)
            .apply(SecurityMockMvcConfigurers.springSecurity())
            .defaultRequest(MockMvcRequestBuilders.get("/").with(
                SecurityMockMvcRequestPostProcessors.jwt()
                    .authorities(new SimpleGrantedAuthority("ROLE_BUYER"))))
            .build());
    }
}

Bemerkenswert: JwtDecoder wird zwar als @MockBean für die Bean-Verdrahtung von SecurityConfig benötigt, aber nie tatsächlich aufgerufen – SecurityMockMvcRequestPostProcessors.jwt() speist die Authentifizierung direkt in den SecurityContext ein und umgeht damit den echten Token-Validierungspfad. Der Contract-Test prüft also „reagiert der Endpunkt für einen ROLE_BUYER korrekt“, nicht „funktioniert die Keycloak-Anbindung“ – dafür ist Ebene 5/6 zuständig.

Was jede Ebene NICHT beweist

Keine einzelne Ebene ersetzt eine andere – ein grüner mvn test-Lauf (Ebenen 1–4) beweist beispielsweise nicht automatisch die Datenbankintegration, wie auch im Build-Performance-Nachweis ausdrücklich festgehalten.

PROCUREX prüft jede API-Anfrage als OAuth2 Resource Server gegen Keycloak (SecurityConfig.java, procurex-app): zustandslos, per JWT, mit rollenbasierter Autorisierung pro Endpunkt. Dieser Exkurs erklärt den Unterschied zwischen OAuth2 und OIDC, ordnet Keycloak gegen kommerzielle Alternativen ein und zeigt zwei PROCUREX-spezifische Details, die in Tutorials selten vorkommen: die getrennten Issuer-/JWK-URLs wegen Docker-Netzwerken, und die eigene Rollen-Extraktion aus Keycloaks realm_access-Claim.

OAuth2 ist kein Login-Protokoll – OIDC macht es dazu

Ein verbreitetes Missverständnis: OAuth2 selbst definiert kein „Login“. Es beantwortet nur die Frage „darf dieser Client mit diesem Zugriffs-Token diese Aktion ausführen“ – über wen das Token ursprünglich ausgestellt wurde, macht der Standard keine verbindliche Aussage. OpenID Connect (OIDC, 2014) setzt exakt hier an: Es standardisiert zusätzlich ein ID-Token (ein JWT mit Identitätsclaims wie sub, email, name) und einen /userinfo-Endpunkt. PROCUREX nutzt beide Ebenen: Das Angular-Frontend führt den OIDC-Login durch (angular-oauth2-oidc, Authorization-Code-Flow mit PKCE), procurex-app selbst prüft anschließend nur noch das resultierende Access-Token als reiner OAuth2 Resource Server.

Zwei URLs für einen Identity-Provider: das Docker-„Zwei-Adressen-Problem“

Ein Detail, das in keinem Standard-Tutorial vorkommt, weil es rein aus der lokalen Docker-Topologie von PROCUREX entsteht:

security:
  oauth2:
    resourceserver:
      jwt:
        issuer-uri: ${PROCUREX_OIDC_ISSUER_URI:http://keycloak.localhost/realms/procurex}
        jwk-set-uri: ${PROCUREX_OIDC_JWK_SET_URI:.../protocol/openid-connect/certs}

issuer-uri validiert den iss-Claim im Token und muss exakt der öffentlichen, browserseitigen Adresse entsprechen (keycloak.localhost, über Traefik geroutet), weil der Browser das Token mit genau dieser Adresse als Aussteller bekommen hat. jwk-set-uri ist bewusst separat gesetzt, weil der Server-Container selbst *.localhost nicht auflösen kann – innerhalb von Docker gibt es dafür keinen automatischen DNS-Trick, weshalb procurex-app für den öffentlichen Schlüssel den internen Servicenamen (shared-keycloak) im gemeinsamen proxy-Netzwerk anspricht. Zwei URLs für denselben logischen Server, weil Browser und Server-Container unterschiedliche Netzwerksichten auf denselben Keycloak haben.

Rollen statt Scopes: Keycloaks realm_access-Claim

Spring Security erwartet standardmäßig OAuth2-scope-Claims für Autorisierung. Keycloak modelliert Berechtigungen aber primär über Realm-Rollen im Claim realm_access.roles – PROCUREX ersetzt deshalb den Standard-Converter durch einen eigenen:

private JwtAuthenticationConverter jwtAuthenticationConverter() {
    JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
    converter.setJwtGrantedAuthoritiesConverter(this::realmRolesFrom);
    return converter;
}

private Collection<GrantedAuthority> realmRolesFrom(Jwt jwt) {
    Map<String, Object> realmAccess = jwt.getClaim("realm_access");
    if (realmAccess == null || !(realmAccess.get("roles") instanceof List<?> roles)) {
        return List.of();
    }
    return roles.stream().map(Object::toString).map(SimpleGrantedAuthority::new).toList();
}

Wichtig dabei: Die Keycloak-Rollen heißen bereits ROLE_BUYER, ROLE_APPROVER usw. – der Converter fügt kein zusätzliches ROLE_-Präfix hinzu (Spring Security würde das bei der Standard-Scope-Konvertierung sonst tun), sonst entstünde ein doppeltes ROLE_ROLE_BUYER. Jeder Endpunkt bekommt danach eine explizite Least-Privilege-Regel:

.requestMatchers(HttpMethod.POST, "/api/v1/orders/*/approval/**").hasAnyAuthority("ROLE_APPROVER", "ROLE_ADMIN")
.requestMatchers(HttpMethod.POST, "/api/v1/orders/*/goods-receipts").hasAnyAuthority("ROLE_RECEIVING", "ROLE_ADMIN")
.requestMatchers(HttpMethod.POST, "/api/v1/orders/*/invoices").hasAnyAuthority("ROLE_FINANCE", "ROLE_ADMIN")

Sechs fachliche Rollen (ROLE_BUYER, ROLE_APPROVER, ROLE_SUPPLIER_ADMIN, ROLE_RECEIVING, ROLE_FINANCE) plus ein universeller ROLE_ADMIN-Zugriff pro Endpunkt bilden das komplette Autorisierungsmodell. Wichtig ist die Abgrenzung zum Exception-Exkurs: Ein 403 wegen fehlender Rolle an dieser Stelle ist ein technischer Security-Fehler (Spring Security selbst antwortet), während ForbiddenException einen fachlichen, datenabhängigen Regelverstoß signalisiert (z. B. ein Bestellwert über dem Schwellenwert der Rolle) – zwei verschiedene Schichten, bewusst nicht vermischt.

Keycloak im Vergleich zu SaaS-Alternativen

Technisch sind alle fünf OIDC-kompatibel – der von PROCUREX genutzte JwtDecoder/issuer-uri-Mechanismus in Spring Security funktioniert mit jedem davon nahezu unverändert. Der Unterschied liegt in Betriebsmodell, Kosten und Datenhoheit, nicht im Protokoll.