URL-Shortener – JSON-Export in Vaadin Flow

Exportfunktionen werden häufig als rein technische Nebenaufgabe betrachtet: ein Button, ein Download, fertig. In einer Vaadin-basierten Anwendung zeigt sich jedoch sehr schnell, dass der Export weit mehr ist als das Schreiben von Daten in eine Datei. Er ist eine direkte Verlängerung des UI-Zustands, ein infrastruktureller Vertrag zwischen Frontend und Backend – und ein entscheidender Faktor für Wartbarkeit und Vorhersagbarkeit.

Dieser Artikel zeigt, wie im URL-Shortener-Projekt ein JSON-basierter Export bewusst als UI-getriebener Workflow gestaltet wurde. Der Fokus liegt dabei nicht auf Dateiformaten oder komplexen Backend-Abstraktionen, sondern auf der sauberen Einbettung des Exports in eine Vaadin-Flow-Oberfläche: Filterkopplung, Download-Mechanik, Paging-Grenzen und klare Verantwortlichkeiten zwischen UI, Client und Server.

Der aktuelle Quelltext befindet sich auf GitHub unter https://github.com/svenruppert/url-shortener oder https://3g3.eu/url

Export aus UI-Sicht: mehr als ein Download-Button

In klassischen Webanwendungen wird Export oft als isolierter API-Endpunkt gedacht. Aus Sicht einer Vaadin-UI greift diese Betrachtung zu kurz. Für den Benutzer ist Export kein technischer Vorgang, sondern eine Konsequenz des aktuellen UI-Zustands: der gesetzten Filter, der Sortierung, der Paging-Grenzen.

Ein Export, der diese Kopplung ignoriert, führt sofort zu kognitiven Brüchen. Die Anzeige im Grid zeigt einen bestimmten Datenbestand, der Export liefert jedoch etwas anderes – sei es mehr, weniger oder schlicht andere Daten. Genau an dieser Stelle entscheidet sich, ob eine Anwendung als konsistent wahrgenommen wird oder nicht.

Der Anspruch im Projekt war daher klar: Der Export ist keine Sonderfunktion, sondern ein Spiegel des UI-Zustands.

Diese Entscheidung prägt alle weiteren Design-Schritte – von der Filtererzeugung über die Download-Mechanik bis hin zur Struktur der Exportdaten selbst.

Ausgangslage: funktionaler Export, aber UI-fremd

Vor der Überarbeitung war ein Export technisch bereits möglich. Daten konnten serverseitig gelesen und als JSON an den Client zurückgegeben werden, sodass die grundlegende Funktionalität formal erfüllt war. Aus Sicht der Benutzeroberfläche führte diese Implementierung jedoch eine Reihe struktureller Probleme mit sich, die sich erst bei näherer Betrachtung deutlich zeigten.

Die Response-Strukturen waren uneinheitlich und mussten vom Client jeweils kontextabhängig interpretiert werden. Bedeutung und Zusammenspiel von HTTP-Statuscodes und Response-Bodies waren nicht explizit festgelegt, sondern ergaben sich aus impliziten Annahmen im Client-Code. Gleichzeitig bestand keine klare Verbindung zwischen dem Export und den aktuell sichtbaren Filtern in der Oberfläche. Welche Daten tatsächlich exportiert wurden, ließ sich aus Sicht der UI nur indirekt nachvollziehen. Hinzu kam zusätzliche Sonderlogik für leere Ergebnisse oder Fehlerfälle, die sich nicht konsistent aus der Antwort selbst ableiten ließ, sondern an mehreren Stellen im Client verteilt war.

Aus Vaadin-Sicht war der Export damit kein integrierter UI-Workflow, sondern ein isolierter technischer Endpunkt. Die UI musste Wissen über Sonderfälle, Statuscodes und Antwortformate mitbringen, das nicht explizit durch einen vertraglich festgelegten Rahmen abgesichert war. Auch in der Testlandschaft spiegelte sich dieser Zustand wider: Tests orientierten sich häufig an konkreten String-Repräsentationen oder vollständigen JSON-Ausgaben, statt an klar definierten fachlichen Strukturen. Änderungen an Filtern, Sortierungen oder Antwortformaten mussten daher an mehreren Stellen nachgezogen werden und bargen ein erhöhtes Risiko unbeabsichtigter Seiteneffekte.

Kurz gesagt: Der Export funktionierte technisch, erfüllte jedoch nicht die Anforderungen an einen UI-fähigen, nachvollziehbaren und wartbaren Bestandteil einer Vaadin-Anwendung.

Designziel: Export als deterministischer UI-Workflow

Das zentrale Ziel der Neugestaltung lautete nicht „mehr Features“, sondern die Vorhersagbarkeit. Für die Vaadin-UI bedeutet das:

Der Export verwendet exakt dieselben Filter wie das Grid und folgt damit unmittelbar dem aktuellen UI-Zustand. Paging-Grenzen sind bewusst gesetzt und für Entwickler wie Benutzer nachvollziehbar, sodass Umfang und Charakter des Exports klar erkennbar bleiben. Erfolg, leere Ergebnisse und Fehlerfälle sind eindeutig unterscheidbar und lassen sich in der UI ohne Sonderlogik behandeln. Gleichzeitig verhält sich der Download browserkonform und UI-stabil, ohne auf den laufenden UI-Zustand Einfluss zu nehmen.

Ein Export darf aus Sicht der UI keinen eigenen Zustand haben. Er darf nichts „hinzudenken“, nichts erweitern, nichts implizit verändern. Er ist eine Momentaufnahme dessen, was der Benutzer sieht – nicht mehr und nicht weniger.

Einheitliche Responses als Voraussetzung für saubere UI-Logik

In einer Vaadin-Anwendung entfalten API-Responses ihre Wirkung unmittelbar im UI-Code, da jede Antwort typischerweise direkt in UI-Zustände, Komponentenlogik und Benutzerfeedback übersetzt wird. Anders als bei rein clientseitigen Frontends ist die UI-Logik eng mit der serverseitigen Verarbeitung verknüpft: Jede Antwort beeinflusst unmittelbar den Zustand der Komponenten, das Aktivieren oder Deaktivieren von Bedienelementen sowie die Darstellung von Rückmeldungen an den Benutzer.

Uneinheitliche Antwortformate führen in diesem Kontext zwangsläufig zu komplexen if-else-Kaskaden im UI-Code. Sonderbehandlungen für scheinbar triviale Fälle wie „leere“ Exporte oder unterschiedliche Fehlerzustände müssen explizit abgefragt werden. Der UI-Code beginnt damit, technische Details der API zu interpretieren – etwa bestimmte HTTP-Statuscodes oder das Vorhandensein einzelner JSON-Felder –, statt sich auf klar definierte fachliche Signale zu verlassen. Dies erhöht nicht nur die Komplexität des Codes, sondern erschwert auch das Verhalten der Oberfläche bei Erweiterungen und macht es schwerer nachvollziehbar und fehleranfälliger.

Im URL-Shortener-Projekt wurde dieses Problem durch die Einführung einer expliziten und stabilen Response-Struktur gelöst. Unabhängig davon, ob ein Exportdatensatz leer ist oder einen Fehler enthält, folgt die Antwort immer demselben strukturellen Aufbau. HTTP-Statuscodes werden weiterhin genutzt, um den groben Ausgang eines Requests zu signalisieren, übernehmen jedoch bewusst nicht die Rolle des alleinigen Bedeutungsträgers. Die eigentliche fachliche Information – etwa Kontext, Umfang und Inhalt des Exports – wird vollständig und konsistent im JSON-Format transportiert.

Ein vereinfachter, realer Export aus dem System verdeutlicht diesen Ansatz:

{
  "formatVersion": "1",
  "mode": "filtered",
  "exportedAt": "2026-02-05T11:28:54.582886239Z",
  "total": 9,
  "items": [ /* fachliche Datensätze */ ]
}

Daraus entsteht für die Vaadin-UI ein klarer und stabiler Vertrag. Der UI-Code kann sich darauf verlassen, dass Metadaten wie mode, exportedAt oder total immer vorhanden sind und in derselben Bedeutung interpretiert werden können. Die Oberfläche muss nicht mehr erraten, ob ein Export erfolgreich war oder ob besondere Sonderfälle vorliegen. Stattdessen lässt sich der Ablauf linear und deterministisch gestalten: Metadaten werden ausgewertet, der Umfang geprüft und anschließend die Nutzdaten verarbeitet oder dem Benutzer entsprechend zurückgemeldet.

Diese Struktur hat weitreichende Konsequenzen für die UI-Logik. Ladeindikatoren, Bestätigungsdialoge oder Fehlermeldungen lassen sich direkt aus der strukturierten Antwort ableiten, ohne zusätzliche Speziallogik oder kontextabhängige Prüfungen. Die Oberfläche bleibt dadurch übersichtlich, vorhersehbar und eng an die fachliche Bedeutung der Antwort gekoppelt, statt an technische Sonderfälle oder implizite Annahmen gebunden zu sein.

Filterlogik als gemeinsame Sprache zwischen Grid und Export

Ein entscheidender Vaadin-spezifischer Punkt ist die Wiederverwendung der Filterlogik. Im Projekt gibt es keinen separaten Export-Filter. Stattdessen wird der Export ausschließlich aus dem aktuellen UI-Zustand erzeugt.

Die SearchBar fungiert dabei als einzige Quelle der Wahrheit:

public UrlMappingListRequest buildFilter(int page, int size) {
  UrlMappingListRequest req = new UrlMappingListRequest();
  req.setPage(page);
  req.setSize(size);
  req.setActiveState(activeState);
  req.setCodePart(codeField.getValue());
  req.setUrlPart(urlField.getValue());
  req.setFrom(from);
  req.setTo(to);
  req.setSort(sort);
  req.setDir(dir);
  return req;
}

Dieses Request-Objekt wird sowohl für die Grid-Anzeige als auch für den Export verwendet. Damit ist garantiert:

Anzeige und Export liefern dadurch identische Ergebnisse, da beide auf exakt denselben Filterdefinitionen basieren. Änderungen an Filtern oder Sortierungen wirken sich automatisch und konsistent auf Anzeige und Export aus, ohne dass zusätzlicher Code gepflegt werden muss. Gleichzeitig existieren keine versteckten oder impliziten Export-Parameter, sodass das Verhalten des Exports vollständig aus dem UI-Zustand erklärt werden kann.

Aus Wartungssicht ist das ein massiver Vorteil: Wer die UI versteht, versteht den Export.

Download-Mechanik in Vaadin: Button ≠ Download

Ein häufiger Fehler in Vaadin-Anwendungen ist der Versuch, einen Datei-Download direkt aus einem Button-Click heraus zu starten. Technisch ist das problematisch, da ein Button-Click primär serverseitige Logik auslöst, während ein Download aus Sicht des Browsers eine Ressource ist.

In Vaadin ist ein Button-Klick primär ein serverseitiges UI-Event. Der Browser sendet dabei keinen „klassischen“ Download-Request, sondern Vaadin verarbeitet den Klick über seine UI/RPC-Kommunikation (Server-Roundtrip, Event-Listener, Komponenten-Update). Aus Sicht des Browsers ist das kein normaler Navigations- oder Ressourcenabruf. Und genau deshalb ist „Button klickt → Browser lädt Datei herunter“ nicht zuverlässig, weil der Browser einen Download typischerweise nur dann sauber startet, wenn er eine Ressource abruft (Link/Navigation) oder ein Formular absendet – also etwas, das im Browser als „echter Request auf eine Datei“ wahrgenommen wird.

Das Anchor (<a>) löst dieses Problem, weil es für den Browser eine normale Download-Quelle darstellt: Es hat eine href-Attribut auf eine Ressource, und mit dem download-Attribut signalisiert es dem Browser: „Das ist eine Datei“. In Vaadin bindest du diese href an eine StreamResource. Dadurch entsteht beim Klick auf den Anchor einen separaten HTTP-Request, der nicht Teil des Vaadin-UI-Event-Flows ist, sondern ein eigenständiger Ressourcenabruf. Erst in diesem Moment wird die StreamResource „gezogen“ und der Exportinhalt on demand erzeugt.

Praktisch hat dieses drei große Vorteile:

1. Browserkonformität und Zuverlässigkeit: Der Download wird über einen Mechanismus gestartet, den der Browser nativ unterstützt. Das reduziert Edge-Cases, in denen ein Download aus einem UI-Event heraus blockiert wird oder inkonsistent reagiert (Popup-/Download-Policies, Timing, UI-Updates).
2. Entkopplung vom UI-Lifecycle: Der Download erfolgt als eigener Request. Selbst wenn Vaadin parallel UI-Requests verarbeitet, der Benutzer weiterklickt oder die Oberfläche neu rendert, kann der Download stabil weiterlaufen. Das ist besonders wichtig, wenn die Exporterzeugung länger dauert oder gestreamt wird.
3. Saubere Verantwortlichkeit: Der Button ist rein UI/UX (Icon, Tooltip, Berechtigungen, Enable/Disable, visuelles Feedback). Das Anchor ist rein „Transport“ (Browser-Download). Die StreamResource ist rein „Datenlieferant“ (Der Export wird erzeugt, wenn er wirklich benötigt wird). Diese Trennung macht den Code wartbarer und reduziert die Seiteneffekte.

Button btnExport = new Button(VaadinIcon.DOWNLOAD.create());
btnExport.setTooltipText("Export current result set as ZIP");
btnExport.addClickListener(e ->
    exportAnchor.getElement().callJsFunction("click")
);

Das eigentliche Download-Verhalten liegt im Anchor, das mit einer StreamResource verbunden ist:

StreamResource exportResource =
    new StreamResource("export.zip", () -> {
      UrlMappingListRequest filter =
          searchBar.buildFilter(1, chunkSize);
      return urlShortenerClient.exportAllAsZipDownload(filter);
    });
exportAnchor.setHref(exportResource);
exportAnchor.getElement().setAttribute("download", true);

Dieses Muster trennt die Verantwortlichkeiten klar voneinander: Die UI-Interaktion bleibt auf den Button beschränkt, der ausschließlich als Auslöser für den Export dient. Der eigentliche Browser-Download erfolgt über das Anchor-Element und wird damit als regulärer Ressourcenzugriff behandelt. Die Bereitstellung der Daten erfolgt schließlich über die StreamResource, die den Exportinhalt erst beim tatsächlichen Download erzeugt.

Der Export wird erst dann erzeugt, wenn der Browser die Ressource tatsächlich abruft – nicht beim Klick selbst.

StreamResource: Export on demand statt vorab

Die Verwendung von StreamResource ist kein Detail, sondern eine bewusste Architekturentscheidung. Der Export wird on demand erzeugt, während der Browser den Stream liest.

Das hat mehrere Vorteile. Auf der UI-Seite bleibt der Speicherbedarf gering, da der Export nicht vollständig vorab erzeugt und gepuffert werden muss. Gleichzeitig wird der UI-Thread nicht blockiert, da die eigentliche Datenübertragung außerhalb des regulären UI-Lifecycles erfolgt. Der Download kann unabhängig vom aktuellen UI-Zustand weiterlaufen, selbst wenn der Benutzer währenddessen navigiert oder weitere Aktionen ausführt. Treten während der Erzeugung des Streams Fehler auf, lassen sich diese sauber über einen eigenen HTTP-Request propagieren, ohne den UI-Zustand in einen inkonsistenten zu versetzen.

Der Export ist damit technisch vom UI-Lifecycle entkoppelt, obwohl er logisch durch das UI ausgelöst wird.

Paging-Grenzen als Schutzmechanismus

Ein weiterer, explizit UI-naher Aspekt der Export-Implementierung ist die bewusste Begrenzung der Exportmenge. Der Export verwendet dieselbe chunkSize wie das Grid in der Oberfläche und ist zusätzlich durch eine feste Obergrenze limitiert. Diese Entscheidung stellt sicher, dass der Export stets in einem klar definierten Rahmen bleibt und sich unmittelbar aus dem aktuellen UI-Zustand ableiten lässt.

Aus architektonischer Sicht verhindert diese Begrenzung, dass der Export unkontrolliert große Datenmengen verarbeitet, nur weil ein Benutzer einen Export auslöst. Gerade in Vaadin-Anwendungen, in denen UI-Interaktionen typischerweise synchron mit serverseitiger Logik verbunden sind, ist diese Schutzmaßnahme entscheidend. Sie reduziert das Risiko hoher Speicherlasten, langer Laufzeiten oder blockierender Operationen, die sich negativ auf andere Benutzer oder den gesamten Server auswirken könnten.

Gleichzeitig vermittelt die Paging-Grenze eine klare fachliche Semantik nach außen. Der Export ist bewusst als Abbild des aktuell sichtbaren Ergebnissatzes definiert. Er spiegelt exakt das wider, was der Benutzer im Grid sehen kann, einschließlich Filterung, Sortierung und Paging-Konfiguration. Dadurch entsteht kein impliziter Anspruch auf Vollständigkeit, wie er typischerweise mit einem Backup assoziiert wird.

Diese Klarheit ist insbesondere für die Benutzererwartung relevant. Der Export liefert weder einen vollständigen Systemabzug noch einen historisch vollständigen Datenbestand, sondern einen gezielt ausgewählten Ausschnitt. Die Begrenzung macht diesen Charakter explizit und verhindert Fehlinterpretationen, etwa die Annahme, ein Export könne zur vollständigen Wiederherstellung des Systems verwendet werden.

Aus Wartungs- und Betriebssicht dient die Paging-Grenze zudem als natürliche Sicherheitslinie. Sie zwingt dazu, Export-Szenarien bewusst zu gestalten und gegebenenfalls separate Mechanismen für Backups oder Massendatenabzüge vorzusehen. Der Export bleibt dadurch ein kontrollierbares UI-Werkzeug und wird nicht schleichend zu einer infrastrukturellen Hintertür für unlimitierte Datenabfragen.

Zusammengefasst ist die Begrenzung der Exportmenge keine technische Nebenbedingung, sondern eine gezielte Designentscheidung. Sie verbindet UI-Zustand, Benutzererwartung und Systemstabilität zu einem konsistenten Gesamtbild und unterstreicht nochmals, dass der Export im URL-Shortener als UI-getriebener Ergebnissatz verstanden wird – und ausdrücklich nicht als Ersatz für ein Backup.

Realer JSON-Export aus dem laufenden System

Die zuvor beschriebenen architektonischen Entscheidungen lassen sich besonders gut anhand eines realen Exports aus dem laufenden System nachvollziehen. Der folgende JSON-Export wurde direkt aus der Vaadin-Oberfläche erzeugt und repräsentiert einen konkreten UI-Zustand zu einem definierten Zeitpunkt.

Bereits auf oberster Ebene enthält der Export alle notwendigen Kontextinformationen, um ihn eigenständig einordnen zu können. Das Feld formatVersion definiert explizit die Version des Exportformats und schafft damit eine stabile Grundlage für zukünftige Erweiterungen. Änderungen am internen Datenmodell erzwingen dadurch nicht automatisch Änderungen am Exportvertrag, solange diese Versionsgrenze respektiert wird.

Das Feld mode ist bewusst sprechend gewählt. Der Wert filtered macht unmissverständlich klar, dass es sich nicht um einen vollständigen Datenabzug handelt, sondern um einen durch UI-Filter eingeschränkten Ergebnissatz. Diese Information ist zentral, da sie verhindert, dass der Export fälschlicherweise als Backup interpretiert wird. Der Export beschreibt nicht den gesamten Systemzustand, sondern exakt den Ausschnitt, den der Benutzer im Grid gesehen hat.

Mit exportedAt wird der exakte Zeitpunkt der Snapshot-Erstellung festgehalten. Der Export bezieht sich damit eindeutig auf einen definierten Systemzustand. Spätere Änderungen an einzelnen Datensätzen sind bewusst nicht enthalten und lassen sich anhand dieses Zeitstempels klar abgrenzen. Ergänzt wird dieser Kontext durch das Feld total, das die Anzahl der exportierten Datensätze angibt und eine schnelle Plausibilisierung ermöglicht, ohne die eigentlichen Nutzdaten analysieren zu müssen.

Die eigentlichen fachlichen Daten befinden sich ausschließlich im Array items. Jeder Eintrag beschreibt einen einzelnen URL-Mapping-Datensatz mit seinen fachlich relevanten Eigenschaften wie shortCode, originalUrl, active sowie den zeitlichen Attributen createdAt und optional expiresAt. Auffällig ist, dass diese Objekte keinerlei UI- oder export-spezifische Metainformationen enthalten. Sie sind bewusst auf den fachlichen Kern reduziert und könnten in gleicher Form auch aus anderen Kontexten stammen.

Gerade diese klare Trennung zwischen Metadaten auf oberster Ebene und fachlichen Nutzdaten im items-Array macht den Export zu einem in sich erklärbaren Artefakt. Auch ohne Kenntnis des internen Codes oder der Vaadin-Oberfläche lässt sich nachvollziehen, wann der Export entstanden ist, unter welchen Bedingungen er erzeugt wurde, welchen Umfang er hat und wo die eigentlichen fachlichen Daten beginnen.

Der reale Export bestätigt damit die zuvor beschriebenen Designziele. Er ist reproduzierbar, kontextreich und eindeutig als UI-getriebener Ergebnissatz erkennbar. Statt lediglich Daten zu transportieren, übermittelt er auch deren Bedeutung und Entstehungskontext – eine Eigenschaft, die für Wartbarkeit, Analyse und langfristige Weiterverarbeitung entscheidend ist.

Auswirkungen auf Wartbarkeit und Verständlichkeit

Durch die enge Kopplung des Exports an den UI-Zustand entsteht ein Verhalten, das für Entwickler wie für Benutzer gleichermaßen vorhersehbar ist. Der Export folgt exakt denselben Regeln wie die Anzeige im Grid und enthält keine versteckten Sonderpfade oder impliziten Abweichungen. Dadurch entwickelt sich der Export automatisch mit der UI weiter: Jede Anpassung an Filtern, Sortierungen oder Paging-Mechanismen wirkt sich konsistent auf beide Pfade aus, ohne dass zusätzlicher Synchronisationscode notwendig wird.

Aus Entwicklersicht reduziert diese Architektur die kognitive Last erheblich. Es existiert kein separater mentaler Modellraum für den Export, da dessen Verhalten vollständig aus dem bekannten UI-Zustand ableitbar ist. Wer das Grid und seine Filterlogik versteht, versteht automatisch auch den Export. Das vereinfacht nicht nur die Einarbeitung neuer Entwickler, sondern reduziert auch das Risiko unbeabsichtigter Inkonsistenzen bei Refactorings oder funktionalen Erweiterungen.

Auch die Testbarkeit profitiert unmittelbar von dieser Klarheit. Da der Export keinen eigenen Zustand besitzt und auf stabilen Request- und Response-Strukturen basiert, lässt er sich isoliert testen. Tests können gezielt mit definierten Filterkombinationen arbeiten und die resultierenden Exporte prüfen, ohne die gesamte UI oder komplexe Interaktionsabläufe simulieren zu müssen. Gleichzeitig bleiben UI-Tests schlank, da sie sich auf die korrekte Erzeugung des Filterzustands konzentrieren können.

Auf lange Sicht wirkt sich diese Struktur positiv auf die Wartbarkeit des Gesamtsystems aus. Änderungen an der UI führen nicht zu versteckten Nebenwirkungen im Export, und umgekehrt erfordert die Weiterentwicklung des Exports keine parallelen Anpassungen an mehreren Stellen. Die Gefahr divergierender Logikpfade zwischen Anzeige und Export wird dadurch nicht nur reduziert, sondern systematisch eliminiert.

Zusammengefasst sorgt die enge Verzahnung von UI-Zustand und Exportlogik dafür, dass der Export kein Sonderfall im System bleibt. Er wird zu einem transparenten, erklärbaren und langfristig wartbaren Bestandteil der Anwendung, der sich nahtlos in die bestehende Vaadin-Architektur einfügt.

Fazit

Der Export im URL-Shortener ist kein isolierter API-Endpunkt, sondern ein integraler Bestandteil der Vaadin-UI-Architektur. Er folgt denselben Regeln wie das Grid, nutzt dieselben Filter und respektiert dieselben Grenzen.

Gerade in Vaadin-Flow-Anwendungen zeigt sich: Ein sauber integrierter Export ist weniger eine Frage des Dateiformats – und viel mehr eine Frage klarer Verantwortlichkeiten, expliziter Verträge und eines konsequent gedachten UI-Workflows.