Mit Quarkus 4 steht das nächste Major-Release des Java-Frameworks vor der Tür. Gerade ist die dritte Betaversion erschienen, das finale Release ist für Ende November geplant. Version 4 bringt auch eine Reihe von Major-Updates in seinen Abhängigkeiten mit: Jackson 3, Hibernate ORM 8, Jakarta REST 4, CDI 5, Vert.x 5. Entsprechend umfangreich fällt auch der Migration Guide aus.
Wir schauen uns das Update etwas genauer an und migrieren dazu eine Beispielanwendung von Quarkus 3.40 LTS auf Quarkus 4 (Beta 3). Was macht quarkus update automatisch, wo muss manuell nachgearbeitet werden und welche Änderungen fallen vielleicht erst zur Laufzeit auf?
Als Beispiel dient eine kleine Bücherverwaltung mit Quarkus REST, Jackson, Hibernate ORM und einigen Features, die sich mit Quarkus 4 ändern. Ausgangspunkt für das Update ist die aktuelle Version 3.40 LTS. Der Code zum Beispielprojekt liegt auf GitHub. Der Branch quarkus-3 enthält den Ausgangsstand, der Branch main die Migration in mehreren Commits.
Was ist neu in Quarkus 4?
- Java 21 ist Minimum, Java 25 wird empfohlen. Virtual Threads rücken damit stärker in den Mittelpunkt.
- Update der Netzwerk-Basis: Netty 4.2 und Vert.x 5, QUIC-Support und HTTP/3 als Opt-in.
- Major-Updates: Jackson 3, Hibernate ORM 8 (Jakarta Persistence 4.0, Jakarta Data 1.1), Jakarta REST 4 und CDI 5.0.
- Observability:
@Observed(Micrometer Observation API), die Dev UI bekommt einen eigenen Observability-Bereich, OpenTelemetry-Metriken und -Logs sind keine Preview mehr. - Weiteres: eine JMS-Erweiterung,
@ExactlyOncefür Kafka-Transaktionen, UBI 10 als Basis-Image und höhere Mindestversionen diverser Datenbanken (z. B. PostgreSQL 16).
Automatische Anpassungen mit quarkus update
Der erste Schritt ist der Aufruf von quarkus update:
quarkus update --stream=4.0
Das erledigt bereits einige Anpassungen wie das Anheben der Versionen. Auch die Jackson-Imports werden automatisch von com.fasterxml.jackson.* auf tools.jackson.* umgestellt, JsonProcessingException wird zur unchecked JacksonException und überflüssige throws-Deklarationen verschwinden. Sogar das Ausschalten von SerializationFeature.WRITE_DATES_AS_TIMESTAMPS wird entfernt, da es nun standardmäßig ausgeschaltet ist. Da @DefaultBean als deprecated markiert wurde wird automatisch auf das neue CDI-5-Pendant @Reserve inklusive @Priority(0) umgestellt.
Wie erwartet ist die Arbeit damit aber noch nicht ganz getan.
Manuelle Anpassungen
Jackson 3
In Jackson 3 ist der ObjectMapper unveränderlich, konfiguriert wird nun über den Builder. Quarkus stellt statt eines ObjectMapper dessen Subtyp JsonMapper bereit, daher wird aus ObjectMapperCustomizer ein JsonMapperBuilderCustomizer. Annotationen (wie das hier referenzierte JsonInclude) bleiben übrigens im Paket com.fasterxml.jackson.annotation.
// Quarkus 3
@Singleton
public class JacksonConfig implements ObjectMapperCustomizer {
@Override
public void customize(ObjectMapper objectMapper) {
objectMapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
objectMapper.setDefaultPropertyInclusion(JsonInclude.Include.NON_NULL);
}
}
// Quarkus 4
@Singleton
public class JacksonConfig implements JsonMapperBuilderCustomizer {
@Override
public void customize(JsonMapper.Builder builder) {
builder.changeDefaultPropertyInclusion(
inclusion -> inclusion.withValueInclusion(JsonInclude.Include.NON_NULL)
);
}
}
JSON Merge Patch
JSON Merge Patch funktionierte prinzipiell bereits mit Quarkus 3, zumindest in dieser Form mit Jackson. Jakarta REST 4 standardisiert das Ganze und bringt unter anderem die Konstante MediaType.APPLICATION_MERGE_PATCH_JSON mit:
@PATCH
@Path("{id}")
@Transactional
@Consumes(MediaType.APPLICATION_MERGE_PATCH_JSON)
public Book patch(@PathParam("id") long id, String mergePatch) {
return objectMapper.readerForUpdating(get(id)).readValue(mergePatch);
}
CDI 5
quarkus update stellt @DefaultBean bereits auf @Reserve um. Optional sind zwei weitere Umstellungen auf CDI-5-Standards. @Eager kann an vielen Stellen anstelle von @Startup eingesetzt werden und @AutoClose macht eine Disposer-Methode überflüssig, die nur close() aufruft. Einen kleinen Blick auf CDI 5 hat Markus Pauer bereits in seinem Blog-Beitrag geworfen.
Stille Fallen: kompiliert, verhält sich aber anders
Unsere Anwendung kompiliert wieder, die Tests zeigen aber, dass sich das Verhalten an einigen Stellen geändert hat:
| Eingabe | Quarkus 3.40 | Quarkus 4 | Altes Verhalten über |
|---|---|---|---|
Body mit nachfolgenden Tokens: {...} {...} | wird akzeptiert, Rest ignoriert | 400 Bad Request | quarkus.jackson.fail-on-trailing-tokens=false |
"pages": null für primitiven int | wird zu 0 | 400 Bad Request | quarkus.jackson.fail-on-null-for-primitives=false |
?author=Frank%20Herbert;sort=title | zwei Parameter | ein Wert: Frank Herbert;sort=title | quarkus.http.use-semicolon-as-query-param-delimiter=true |
Die ersten beiden Punkte sind strengere Defaults in Jackson 3. Clients, die bisher fehlerhafte Requests geschickt haben, bekommen nach der Migration dadurch Fehler. Die Semikolon-Änderung ist subtiler: Hier gibt es keinen Fehler, die Anwendung liefert einfach ein anderes Ergebnis.
Zwei kleinere Bugs im von Quarkus standardmäßig genutzten reflection-free Jackson-Deserializer, die beim Schreiben dieses Beitrags aufgefallen sind, wurden nach einer Meldung bereits schnell behoben.
Wer bestehende Dashboards oder Alerts auf Basis der Prometheus-Metriken betreibt, sollte nach der Migration /q/metrics vergleichen. So wird z. B. aus jvm_info_total nun jvm_total und Counter werden als Ganzzahl statt als Double ausgegeben.
Neue Features nutzen
Metriken mit @Observed
Die neue Erweiterung quarkus-observation bringt Unterstützung für die @Observed-Annotation der Micrometer Observation API:
@Observed(name = "books.export", contextualName = "export-books")
public CompletionStage<String> exportAll() {
return CompletableFuture.supplyAsync(this::export, exportExecutor);
}
Im Dev-Modus lassen sich die Werte direkt im neuen Observability-Dashboard der Dev UI verfolgen:

Fazit
Quarkus 4 soll Ende November rauskommen. Bis dahin werden noch die letzten Ecken und Kanten glatt gezogen. Die Version bringt einige Neuerungen und quarkus update ist bereits ein guter Startpunkt für die Migration. Der Migration Guide muss allerdings natürlich trotzdem noch manuell für das eigene Projekt durchgearbeitet werden.
In der Betaphase sind Probleme noch zu erwarten, die kleinen Bugs bei unserer Beispielanwendung wurden aber schnell behoben und stellen keine Hürde dar. Eile ist bei der Umstellung noch nicht geboten: Quarkus 3.40 LTS erhält 12 Monate Updates. Gerade bei größeren Anwendungen muss vorher geprüft werden, ob für alle Erweiterungen kompatible Versionen bereitstehen. Vieles funktioniert allerdings bereits und bis zum finalen Release kommen noch weitere Bugfixes und neue Versionen von Erweiterungen dazu.