Jakarta REST und HTTP-Schnittstellen migrieren

Jakarta REST und HTTP-Schnittstellen migrieren

0:00 Jetzt wird übertragen. Wir beginnen mit der Schnittstelle nach außen, und das aus gutem Grund: Sie ist der Vertrag mit allen, die die Anwendung nutzen. Die gute Nachricht vorweg — die Ressource selbst ist schnell übertragen, denn die Annotationen der Spezifikation gelten unverändert. Die eigentliche Frage lautet: Merkt der Aufrufer den Unterschied?

0:20 Und dort liegen die Fallen, denn sie stecken in Details, die niemand bewusst entschieden hat: Datumsformate, Nullwerte, Statuscodes im Fehlerfall. Wir sehen uns an, wie man überträgt, was querschnittlich dazugehört, und wie man Kompatibilität nicht behauptet, sondern prüft.

Jakarta REST und HTTP-Schnittstellen migrieren

0:37 Wir sind mitten im Umsetzungstag. Der Pilot steht, jetzt kommt sein erstes Stück: die HTTP-Schnittstelle. Was Sie hier lernen — insbesondere die Methode des feldweisen Vergleichs —, wenden wir in den folgenden Modulen auf Datenzugriff, Messaging und Sicherheit an. Die Technik wechselt, das Vorgehen bleibt.

Ressourcen übernehmen

0:57 Fangen wir mit dem einfachen Teil an. Und ja, dieser Teil ist wirklich einfach — genau deshalb ist er gefährlich. Denn wenn das Übertragen schnell geht, entsteht der Eindruck, man sei fertig. Die eigentliche Arbeit beginnt danach. Quarkus REST ist eine eigenständige Implementierung von Jakarta REST. Die Annotationen der Spezifikation gelten unverändert: Path, GET, POST, Produces, Consumes, PathParam, QueryParam.

1:23 Ergänzend gibt es kürzere Formen wie RestPath oder RestQuery, die den Parameternamen übernehmen. Das ist der Vorteil einer Spezifikation: Sie können Ihre Ressourcenklasse in vielen Fällen kopieren, und sie funktioniert. Der Haken liegt eine Ebene tiefer — bei allem, was der Server bisher zusätzlich erledigt hat, ohne dass es jemand in den Code schreiben musste.

1:46 Worauf es hier ankommt: Diese Klasse sieht aus wie Ihre bestehende Ressource, und das ist gewollt. Übertragen Sie zunächst so nah am Original wie möglich — keine Umbenennungen, keine Verbesserungen, keine Umstellung auf reaktive Signaturen. Denn jede Änderung, die Sie jetzt einbauen, müssen Sie später vom eigentlichen Migrationsergebnis unterscheiden.

2:06 Und beachten Sie die Fußzeile: Die JSON-Abbildung liefert die Erweiterung — Jackson oder JSON-B, aber nicht beide. Das ist eine der Entscheidungen, die im Application Server vorgegeben war und die Sie jetzt bewusst treffen müssen. Vier Punkte, und der erste ist der, der die meisten Überraschungen liefert: Die Serialisierung entscheidet über Feldnamen, Nullwerte und Datumsformate.

2:29 Dieselben Java-Objekte, eine andere Bibliothek — und plötzlich steht ein Datum als Zeitstempel statt als Zeichenkette in der Antwort. Punkt drei betrifft alle, die absolute Adressen zurückgeben: Der Kontextpfad des Servers fällt weg. Wenn Ihre Antworten Links enthalten, zeigen die danach ins Leere. Und Punkt vier ist die Zusammenfassung des ganzen Moduls: Verhalten, das der Application Server ergänzt hat, fehlt jetzt ersatzlos — und zwar ohne Fehlermeldung.

2:57 Die Logik dieser Tabelle: eine Basis, eine JSON-Bindung, optional ein Client. Die Fußzeile enthält den praktischen Rat für Migrationen: Wer bisher JSON-B genutzt hat, bleibt zunächst dabei. Jackson ist verbreiteter und in vielen Projekten die spätere Wahl — aber ein Wechsel der JSON-Bindung ändert Ausgaben, und zwar in Details, die Sie erst im Vergleich sehen.

3:19 Machen Sie den Wechsel später, als eigenen Schritt, mit eigenem Vergleich. Eine Änderung nach der anderen: Das ist das durchgehende Prinzip dieses ganzen Tages. Punkt eins ist der, der zu unerklärlichen Unterschieden führt: Jackson und JSON-B liegen gleichzeitig im Projekt. Dann entscheidet die Reihenfolge, welche Bindung greift — und Sie bekommen Ausgaben, die niemand bestellt hat.

3:42 Punkt drei ist ein Leistungsproblem mit unangenehmem Verlauf: Ein blockierender Aufruf ohne Markierung hängt den Event Loop. Das merkt man nicht im Einzeltest, sondern erst unter Last, wenn plötzlich alle Anfragen langsam werden. Und Punkt vier ist der stille: Absolute Adressen im Antwortkörper zeigen weiter auf den alten Kontextpfad — technisch korrekt, fachlich falsch.

Querschnitt und Clients

4:04 Kommen wir zu dem, was um die Ressourcen herum liegt: Fehlerabbildung, Filter — und der Weg nach außen zu anderen Systemen. Diese Schicht war im Application Server oft unsichtbar, weil er vieles davon mitgeliefert hat. Jetzt gehört sie ausdrücklich in die Anwendung. Querschnittliches Verhalten wird in Quarkus REST über Methoden beschrieben: eine mit ServerExceptionMapper für die Fehlerabbildung, andere mit ServerRequestFilter und ServerResponseFilter für Ein- und Ausgang.

4:31 Ausgehende Aufrufe laufen über typisierte Schnittstellen — Sie beschreiben, was der andere Dienst anbietet, und bekommen eine fertige Implementierung. Das ist eine deutliche Vereinfachung gegenüber handgeschriebenen HTTP-Aufrufen, und es hat einen angenehmen Nebeneffekt: Der Vertrag mit dem Fremdsystem steht als Java-Schnittstelle im Code, statt in URL-Zeichenketten verstreut zu sein.

4:53 Zwei Muster auf einer Folie. Links die Fehlerabbildung: eine Ausnahme kommt herein, eine definierte Antwort geht hinaus — mit Statuscode und Fehlerschlüssel. Rechts der Client als Schnittstelle, ohne Implementierung. Worauf es ankommt, steht in der Fußzeile: Die Adresse des Fremdsystems gehört in die Konfiguration, nicht in den Code.

5:12 Das klingt selbstverständlich, ist es aber nicht — in gewachsenen Anwendungen stehen solche Adressen erstaunlich oft als Konstante irgendwo in einer Hilfsklasse. Beim Umzug ins Image wird das zum Problem, weil sich die Adresse je Umgebung unterscheidet. Der erste Punkt ist die zentrale Einsicht: Fehlerantworten sind Teil des Vertrags — und sie werden häufiger ausgewertet, als man denkt.

5:36 Aufrufer unterscheiden zwischen „nicht gefunden" und „gerade nicht erreichbar", zwischen „ungültige Eingabe" und „interner Fehler". Punkt zwei erklärt, warum das bei Migrationen so oft schiefgeht: Der Application Server hat unbehandelte Fehler in eigene Seiten oder Standardantworten verwandelt, und niemand hat das je aufgeschrieben.

5:55 Fällt das weg, ändern sich Statuscode und Antwortkörper stillschweigend. Und Punkt vier ist der praktische Rat: Aufrufer prüfen Fehlerschlüssel, nicht Freitexte — der Schlüssel muss also unverändert bleiben. Hier geht es um ein Werkzeug, das sich in Migrationen doppelt auszahlt. Die OpenAPI-Erweiterung erzeugt aus Ihren Ressourcen ein Schema und stellt es unter einem eigenen Pfad bereit; dazu gibt es eine Oberfläche zum Ausprobieren.

6:21 Für den Vergleich alter und neuer Antworten ist das ausgesprochen praktisch. Der wichtigste Punkt ist aber der dritte: Das Schema lässt sich beim Build in ein Verzeichnis schreiben und versionieren. Damit wird jede Vertragsänderung im Diff sichtbar — und aus einer Frage, die man vergessen kann, wird eine, die im Review auffällt.

6:40 Punkt eins ist der häufigste konkrete Schaden dieses Moduls: Unbehandelte Fehler liefern jetzt 500 statt der bisherigen fachlichen Antwort. Ein Aufrufer, der bei 404 eine Meldung anzeigt und bei 500 einen Wiederholungsversuch startet, verhält sich danach völlig anders. Punkt drei ist die stille Lücke: Filter aus dem Bestand wirken nicht mehr, weil sie am Server hingen — etwa ein Filter, der jede Anfrage protokolliert oder eine Kopfzeile ergänzt.

7:06 Prüfen Sie das gezielt anhand der Serverkonfiguration aus Modul zwei. Und Punkt vier: Ein Schema, das nie verglichen wird, ist nur eine weitere Datei.

Kompatibilität sichern

7:16 Und jetzt zum eigentlichen Maßstab dieses Moduls. Nicht der Code entscheidet, ob die Migration gelungen ist — der Aufrufer entscheidet das. Wir sehen uns an, wo Unterschiede typischerweise entstehen — und wie man sie findet, bevor es jemand anderes tut. Abwärtskompatibilität heißt: Ein bestehender Aufrufer funktioniert nach der Migration unverändert.

7:38 Das betrifft Pfade, Statuscodes, Feldnamen, Formate, Reihenfolgen und Fehlerschlüssel. Und geprüft wird das nicht durch Lesen, sondern durch Vergleich echter Antworten. Das ist der wichtigste Satz dieses Moduls. Denn beim Lesen sieht alles richtig aus — Sie haben es ja selbst übertragen. Erst wenn zwei Antworten nebeneinanderliegen und Sie Feld für Feld durchgehen, sehen Sie die Kleinigkeiten, die einen Aufrufer brechen.

8:04 Der Ablauf ist bewusst simpel: Antwort des Bestands, Antwort des neuen Dienstes, feldweiser Vergleich, Befundliste. Vier Schritte, die man automatisieren kann und sollte. Wichtig ist der letzte Kasten: eine Befundliste, kein sofortiges Angleichen. Der Reflex ist nämlich, jede Abweichung gleich zu korrigieren. Aber manche Abweichungen sind gewollt oder unvermeidbar — und andere sind Symptome eines tieferliegenden Unterschieds, den Sie beim schnellen Angleichen zudecken würden.

8:33 Erst sammeln, dann entscheiden. Diese vier Zeilen sind die üblichen Verdächtigen, und die dritte ist bei Zählwerk die gefährlichste: Datum mit Zeitzone oder abweichendem Format. Wenn ein Ablesezeitpunkt um zwei Stunden verschoben interpretiert wird, kann daraus ein anderer Abrechnungstag werden — und niemand sieht es im Test, weil dort alle Zeitstempel mittags liegen.

8:55 Die zweite Zeile ist die tückischste im Zusammenspiel: Ein Feld fehlt, statt null zu sein. Manche Auswertungen kommen damit klar, andere brechen ab. Und wie die Fußzeile sagt: Jede dieser Abweichungen ist ein Befund, keine Geschmacksfrage. Vier Dinge, die bisher der Server geliefert hat und die jetzt niemand liefert. Zeichenkodierung und Standardsprache waren Servereinstellungen — bei Adressdaten mit Umlauten fällt das sofort auf, bei einem selten genutzten Feld erst Monate später.

9:24 Fehlerseiten und Weiterleitungen kamen aus der Serverkonfiguration. Größenbegrenzungen und Zeitlimits ebenfalls; wenn dort andere Werte gelten, scheitert plötzlich ein großer Upload, der jahrelang funktioniert hat. Nichts davon steht in Ihrem Code, und deshalb findet es auch keine Codeprüfung. Es steht in der Serverkonfiguration — die Sie in Modul zwei aufgenommen haben.

9:46 Punkt eins ist der methodische Kernfehler: Verglichen wird gegen die Dokumentation statt gegen die tatsächliche Antwort. Die Dokumentation beschreibt, was gelten sollte. Der Aufrufer verlässt sich auf das, was tatsächlich kommt — inklusive aller Eigenheiten. Punkt zwei ist die häufigste Lücke: Nur der Erfolgsfall wird geprüft, weil Fehlerfälle mühsam auszulösen sind. Genau deshalb sind sie später Überraschungen.

10:11 Und Punkt vier ist der, den man für harmlos hält: Ein neues Feld wird ergänzt. Für die meisten Aufrufer folgenlos — für einen streng validierenden Aufrufer ein Abbruch.

Übung

10:21 In der Übung übertragen Sie die Ableseauftrags-Schnittstelle. Und Sie machen den Vergleich, der aus einer Vermutung einen Beleg macht. Verglichen wird gegen den laufenden Bestand, nicht gegen die Schnittstellenbeschreibung. Dieser Unterschied entscheidet über die Aussagekraft. Sie übertragen die Ressource so, dass bestehende Aufrufer keine Änderung bemerken. Das Lernziel ist genau das: nicht Code zu bewegen, sondern Verhalten zu erhalten.

10:47 Erfolgreich sind Sie, wenn für jeden geprüften Aufruf Statuscode, Feldnamen und Formate mit dem Bestand übereinstimmen und jede Abweichung mit Entscheidung in der Befundliste steht. Wichtig ist der Hinweis: Der Vergleich läuft gegen die laufende Altanwendung, nicht gegen die Schnittstellenbeschreibung. Die Beschreibung ist eine Absicht — der laufende Bestand ist die Wirklichkeit, an der die Aufrufer hängen.

11:10 Der rote Faden: übertragen, Fehler abbilden, aufzeichnen, vergleichen, entscheiden. Schritt drei ist der, den man nicht überspringen darf — Antworten aus beiden Systemen aufzeichnen, und zwar für dieselben Eingaben. Schritt fünf ist der interessante: Je Abweichung entscheiden Sie bewusst zwischen angleichen und als Bruch dokumentieren. Beides ist zulässig.

11:32 Nicht zulässig ist, eine Abweichung unbemerkt in Produktion zu geben. Und wie die Fußzeile sagt: Die Befundliste ist die Grundlage für die Contract Tests in Modul dreizehn — Sie arbeiten hier schon für übermorgen. Punkt eins ist die häufigste Abkürzung: Der Vergleich beschränkt sich auf zwei Beispielaufrufe. Zwei Aufrufe finden die groben Fehler, aber die groben Fehler hätten Sie ohnehin gefunden.

11:55 Punkt zwei ist der methodisch wichtigste: Abweichungen werden angeglichen, ohne die Ursache zu verstehen. Wenn ein Datum anders formatiert ist, können Sie das an einer Stelle korrigieren — oder Sie verstehen, dass die JSON-Bindung anders konfiguriert ist, und lösen es einmal für alle Felder. Und Punkt vier ist eine Frage der Zusammenarbeit: Ein bewusst hingenommener Bruch muss beim Aufrufer ankommen, nicht nur in Ihrer Liste stehen.