Optimistic UI Updates mit GraphQL Mutations sauber umsetzen

1. Warum Optimistic UI mehr ist als kosmetisches Feintuning

Menschen nehmen Verzögerungen ab etwa hundert Millisekunden bewusst wahr, ab vierhundert Millisekunden wirkt eine Interaktion spürbar träge. Ein typischer GraphQL-Mutation-Roundtrip über mobiles Netz liegt oft in genau diesem kritischen Bereich. Optimistic UI Updates lösen dieses Problem nicht durch schnellere Server, sondern durch eine andere Reihenfolge: Das Interface zeigt das erwartete Ergebnis einer Mutation sofort an, während die tatsächliche Anfrage im Hintergrund läuft. Für den Nutzer fühlt sich jede Interaktion sofort an, unabhängig von der tatsächlichen Netzwerklatenz.

Der Denkfehler, den viele Teams beim ersten Einsatz von Optimistic UI Updates machen, ist die Annahme, es handle sich um eine rein kosmetische Optimierung. Tatsächlich verändert der Ansatz das Fehlerverhalten der gesamten Anwendung fundamental. Wenn eine Mutation fehlschlägt, nachdem das UI bereits das optimistische Ergebnis zeigt, muss die Anwendung diesen Zustand sauber zurückrollen, ohne dass der Nutzer verwirrt zurückbleibt. Ohne durchdachten Rollback-Mechanismus entstehen Interfaces, die kurzzeitig falsche Daten anzeigen und den Nutzer im Ungewissen lassen, was tatsächlich passiert ist.

Apollo Client bringt für Optimistic UI Updates mit GraphQL Mutations eingebaute Unterstützung mit, über den optimisticResponse-Parameter und die enge Kopplung an den normalisierten Cache. Die folgenden Abschnitte zeigen, wie sich dieser Mechanismus korrekt für einzelne Objekte, Listen und komplexere Szenarien mit temporären IDs einsetzen lässt, und wo die typischen Fallstricke liegen.

2. optimisticResponse: das erwartete Ergebnis vorwegnehmen

Der Kern von Optimistic UI Updates in Apollo Client ist der optimisticResponse-Parameter bei useMutation. Er beschreibt exakt die Form, die der Server voraussichtlich zurückgeben wird, inklusive __typename für jedes betroffene Objekt, damit Apollo Client das Ergebnis korrekt in den normalisierten Cache einordnen kann. Sobald die Mutation ausgelöst wird, wendet Apollo Client dieses vorweggenommene Ergebnis sofort an, jede Komponente, die die betroffenen Daten über useQuery liest, rendert sich augenblicklich neu.

Wichtig ist, dass optimisticResponse strukturell exakt dem tatsächlichen Mutation-Ergebnis entsprechen muss, inklusive aller angeforderten Felder. Fehlt ein Feld oder stimmt der Typ nicht, entstehen entweder Cache-Inkonsistenzen oder Laufzeitfehler beim Zusammenführen der echten Antwort. Für einfache Toggle-Aktionen wie ein Like ist das meist unkompliziert, weil sich das Ergebnis eindeutig aus dem aktuellen Zustand ableiten lässt.

// Optimistic response for a simple toggle mutation
const LIKE_POST = gql`
  mutation LikePost($postId: ID!) {
    likePost(postId: $postId) {
      id
      likedByMe
      likeCount
    }
  }
`;

function LikeButton({ post }: { post: { id: string; likedByMe: boolean; likeCount: number } }) {
  const [likePost] = useMutation(LIKE_POST, {
    variables: { postId: post.id },
    // The UI updates instantly, before the server actually responds
    optimisticResponse: {
      likePost: {
        __typename: 'Post',
        id: post.id,
        likedByMe: !post.likedByMe,
        likeCount: post.likedByMe ? post.likeCount - 1 : post.likeCount + 1,
      },
    },
  });

  return <button onClick={() => likePost()}>{post.likeCount} Likes</button>;
}

3. Cache-Updates: normalisierte Objekte konsistent halten

Der normalisierte Cache von Apollo Client speichert Objekte anhand einer Kombination aus __typename und id. Solange die optimistische Antwort exakt dasselbe Objekt referenziert, das bereits im Cache liegt, aktualisiert Apollo Client automatisch jede Komponente, die dieses Objekt über eine Query liest, unabhängig davon, über welchen Query-Pfad es ursprünglich geladen wurde. Diese automatische Normalisierung ist der Grund, warum Optimistic UI Updates mit GraphQL so gut funktionieren, ein Like auf einem Post aktualisiert gleichzeitig die Feed-Ansicht und die Detailansicht, ohne manuellen Synchronisationscode.

Komplexer wird es, wenn eine Mutation Felder betrifft, die nicht direkt im Rückgabewert enthalten sind, etwa ein abgeleiteter Zähler auf einem übergeordneten Objekt. Für solche Fälle bietet Apollo Client die update-Funktion, die direkten Zugriff auf den Cache erlaubt und beliebige zusätzliche Änderungen vornehmen kann, während die Mutation läuft. Diese Funktion wird sowohl für die optimistische Antwort als auch für die echte Serverantwort ausgeführt, was Konsistenz zwischen beiden Phasen sicherstellt.

// Manual cache update for a derived field not returned by the mutation
const [addComment] = useMutation(ADD_COMMENT, {
  optimisticResponse: {
    addComment: {
      __typename: 'Comment',
      id: `temp-${Date.now()}`,
      text: commentText,
      author: currentUser,
    },
  },
  update(cache, { data }) {
    // Increment the parent post's comment count, not returned by the mutation itself
    cache.modify({
      id: cache.identify({ __typename: 'Post', id: postId }),
      fields: {
        commentCount: (existing: number) => existing + 1,
      },
    });
  },
});

4. Optimistic Updates bei Listen: Einfügen, Löschen, Sortieren

Einzelne Objekte optimistisch zu aktualisieren ist der einfache Fall, Listen sind schwieriger, weil Apollo Client Listenfelder standardmäßig nicht automatisch verändert, wenn ein neues Element hinzukommt. Für Optimistic UI Updates bei Listen ist deshalb fast immer eine explizite update-Funktion nötig, die das neue Element in die bestehende Listen-Referenz im Cache einfügt, an der richtigen Position, mit korrekter Sortierung.

Beim Löschen ist der umgekehrte Fall zu beachten: Ein optimistisch gelöschtes Element muss aus allen Listen entfernt werden, in denen es referenziert wird, nicht nur aus der Liste, über die die Löschaktion ausgelöst wurde. Wenn ein Kommentar sowohl in einer paginierten Übersicht als auch in einer gefilterten Ansicht erscheint, müssen beide Cache-Referenzen synchron aktualisiert werden, sonst erscheint das gelöschte Element kurzzeitig noch in einer der beiden Ansichten, was Nutzer als Bug wahrnehmen.

// Optimistically inserting a new item into a cached list
const [addTodo] = useMutation(ADD_TODO, {
  optimisticResponse: {
    addTodo: {
      __typename: 'Todo',
      id: `temp-${Date.now()}`,
      text: newTodoText,
      completed: false,
    },
  },
  update(cache, { data }) {
    if (!data) return;
    cache.modify({
      fields: {
        todos(existingTodos = []) {
          const newTodoRef = cache.writeFragment({
            data: data.addTodo,
            fragment: gql`
              fragment NewTodo on Todo {
                id
                text
                completed
              }
            `,
          });
          // Prepend, matching where the real server response will place it
          return [newTodoRef, ...existingTodos];
        },
      },
    });
  },
});

5. Rollback: was bei einem Fehler wirklich passiert

Der wichtigste Unterschied zwischen einer naiven und einer sauberen Implementierung von Optimistic UI Updates zeigt sich im Fehlerfall. Apollo Client rollt eine fehlgeschlagene optimistische Mutation automatisch zurück, das UI kehrt zum letzten bekannten, tatsächlich vom Server bestätigten Zustand zurück, sobald die Mutation mit einem Fehler abgeschlossen wird. Dieser Rollback passiert ohne zusätzlichen Code, solange die Fehlerbehandlung nicht versehentlich den optimistischen Zustand manuell fixiert.

Ein häufiger Fehler ist, im onCompleted-Callback zusätzliche lokale State-Updates vorzunehmen, die beim Rollback nicht automatisch rückgängig gemacht werden, weil sie außerhalb des Apollo-Caches liegen, etwa in lokalem Component-State. Für konsistentes Verhalten sollte jeder UI-Zustand, der von einer optimistischen Mutation abhängt, direkt aus dem Apollo-Cache gelesen werden, statt in separatem State dupliziert zu werden. Zusätzlich lohnt sich eine sichtbare Fehlerbenachrichtigung im onError-Callback, damit der Nutzer den Rollback nicht als unerklärliches Verschwinden seiner Aktion wahrnimmt.

6. Temporäre IDs und das Problem generierter Schlüssel

Beim Erstellen neuer Objekte kennt der Client die endgültige, vom Server vergebene ID noch nicht, wenn die optimistische Antwort angewendet wird. Eine clientseitig generierte temporäre ID, meist mit einem klar erkennbaren Präfix wie temp-, überbrückt diese Lücke. Für Optimistic UI Updates ist entscheidend, dass Apollo Client beim Eintreffen der echten Serverantwort das temporäre Objekt korrekt durch das echte Objekt mit der finalen ID ersetzt, nicht als zweiten, doppelten Eintrag hinzufügt.

Dieser Austausch funktioniert zuverlässig, solange die update-Funktion die Liste anhand einer stabilen Referenz statt anhand der ID manipuliert, Apollo Client kümmert sich dann selbst um die Umschreibung der Referenz von der temporären auf die finale ID. Fehlt dieser Mechanismus oder wird die ID manuell in lokalem State verglichen, entstehen sichtbare Duplikate, die erst beim nächsten vollständigen Neuladen der Liste verschwinden, ein klassischer, schwer zu findender Bug in Produktion.

7. UX-Feedback: optimistisch heißt nicht unsichtbar

Optimistic UI Updates bedeuten nicht, dass der Netzwerkstatus komplett unsichtbar bleiben sollte. Für unkritische, häufige Aktionen wie ein Like ist keinerlei zusätzliches Feedback nötig, der optimistische Zustand ist selbsterklärend. Für Aktionen mit größerer Tragweite, etwa das Löschen eines Datensatzes oder eine finanzielle Transaktion, sollte trotz optimistischer Anzeige ein dezenter Hinweis erkennbar bleiben, dass die Aktion noch nicht endgültig serverseitig bestätigt ist, etwa ein kleines Sync-Icon oder eine reduzierte Deckkraft, bis die Bestätigung eintrifft.

Diese Balance ist wichtig, weil zu viel sichtbares Ladefeedback den Vorteil von Optimistic UI Updates wieder zunichtemacht, während zu wenig Feedback bei kritischen Aktionen Vertrauen kostet, wenn ein Fehler tatsächlich eintritt und der Nutzer keinerlei Vorwarnung hatte. Die Faustregel: Je größer die Konsequenz eines möglichen Fehlschlags, desto sichtbarer sollte der vorläufige Charakter der Anzeige bleiben.

8. Optimistic Updates gezielt testen

Optimistic-UI-Logik ist notorisch schwer manuell zu testen, weil der interessante Fall, ein Serverfehler nach erfolgreicher optimistischer Anzeige, in der Entwicklungsumgebung selten von selbst auftritt. Für Optimistic UI Updates lohnt sich deshalb eine gezielte Testumgebung mit Apollo Clients MockedProvider, die einen fehlschlagenden Mutation-Response simuliert und prüft, ob das UI korrekt zum vorherigen Zustand zurückkehrt.

Ein sinnvolles Testmuster deckt drei Fälle ab: den optimistischen Zwischenzustand direkt nach dem Auslösen der Mutation, den Endzustand nach erfolgreicher Serverantwort, und den Rollback-Zustand nach einem simulierten Fehler. Diese drei Snapshots zusammen stellen sicher, dass die Optimistic-UI-Logik nicht nur im Erfolgsfall funktioniert, sondern auch im für Nutzer sichtbaren Fehlerfall korrekt reagiert.

9. Optimistic UI im Vergleich zu anderen Lade-Strategien

Optimistic UI ist eine von mehreren Strategien, um wahrgenommene Latenz zu reduzieren. Die folgende Übersicht ordnet die Ansätze nach Reaktionsgeschwindigkeit und Implementierungsrisiko.

Der Aufwand für Optimistic UI Updates steigt deutlich, sobald Listen, temporäre IDs und Rollback-Logik zusammenkommen, der Wahrnehmungsgewinn für Nutzer rechtfertigt diesen Aufwand aber bei häufig genutzten, interaktiven Elementen fast immer.

10. Zusammenfassung

Optimistic UI Updates mit GraphQL Mutations lassen Interfaces sofort reagieren, indem der optimisticResponse-Parameter das erwartete Ergebnis vorwegnimmt und Apollo Client den normalisierten Cache entsprechend aktualisiert. Für einzelne Objekte reicht dieser Mechanismus meist aus, für Listen braucht es zusätzlich eine explizite update-Funktion, die neue Elemente korrekt einfügt und gelöschte Elemente aus allen betroffenen Cache-Referenzen entfernt.

Der entscheidende Unterschied zwischen einer robusten und einer fragilen Implementierung liegt im Fehlerfall: Automatischer Rollback funktioniert nur, wenn UI-Zustand konsequent aus dem Apollo-Cache gelesen wird statt in separatem lokalem State dupliziert zu sein. Temporäre IDs für neu erstellte Objekte, sichtbares aber dezentes Feedback bei kritischen Aktionen und gezielte Tests für den Rollback-Fall runden eine saubere Implementierung von Optimistic UI Updates ab.

11. FAQ: Optimistic UI Updates mit GraphQL Mutations