Optimistische Muster mit React Query und Zustand

Der useMutation-Hook von React Query bietet eine integrierte Infrastruktur für optimistische Aktualisierungen durch drei Rückrufe im Lebenszyklus: onMutate (wird vor der Mutation ausgeführt und gibt ein Kontextobjekt zurück), onError (wird bei einem Fehler ausgeführt und erhält den Kontext) und onSettled (wird bei Erfolg oder Fehler ausgeführt). Diese Struktur wurde speziell für optimistische Muster entwickelt.

In onMutate führen Sie drei Schritte aus: Brechen Sie zunächst alle laufenden Abfragen für die betroffenen Daten ab (await queryClient.cancelQueries({ queryKey })), erstellen Sie anschließend einen Snapshot des aktuellen Caches (queryClient.getQueryData(queryKey)) und wenden Sie schließlich die optimistische Aktualisierung auf den Cache an (queryClient.setQueryData(queryKey, updater)). Geben Sie den Snapshot als Kontext zurück.

Der Rückruf onError erhält den Fehler, die Mutationsvariablen und den von onMutate zurückgegebenen Kontext. Verwenden Sie den Kontext für das Rollback: queryClient.setQueryData(queryKey, context.previousData). Der Kontext verbindet den in onMutate erstellten Snapshot mit dem Rollback in onError.

Der Rückruf onSettled wird unabhängig von Erfolg oder Fehler ausgeführt. Verwenden Sie ihn, um die Abfrage neu zu laden und mit dem Serverzustand zu synchronisieren: queryClient.invalidateQueries({ queryKey }). So stellen Sie sicher, dass Sie sich nach jeder Mutation – unabhängig davon, ob sie erfolgreich war (der Server kann die Daten verändert haben) oder fehlgeschlagen ist (das Rollback ist abgeschlossen) – letztendlich an den maßgeblichen Serverzustand annähern.

Ein praktisches Beispiel ist das Umschalten des Erledigt-Status einer Todo-Aufgabe. Erstellen Sie in onMutate einen Snapshot der Todo-Liste und aktualisieren Sie anschließend die betreffende Todo-Aufgabe im Cache. Stellen Sie in onError den Snapshot aus dem Kontext wieder her. Entwerten Sie in onSettled die Todo-Abfrage, um sie neu zu laden. Die Person sieht das Umschalten sofort; der Server wird im Hintergrund synchronisiert.

In einem Zustand-Store sind optimistische Aktualisierungen unkompliziert: Erstellen Sie eine Aktion updateItem(id, changes), die das Element sofort im Store aktualisiert und anschließend die API aufruft. Wenn die API fehlschlägt, rufen Sie eine weitere Aktion revertItem(id, previousState) auf. Durch die synchronen Zustandsaktualisierungen von Zustand erfolgt der optimistische Schritt sofort.

Verwenden Sie beim optimistischen Aktualisieren tief verschachtelter Zustände in Zustand immer's produce für übersichtliche Mutationen: set(produce(state => { state.items[id] = { ...state.items[id], ...changes } })). Immer übernimmt unveränderliche Aktualisierungen mit einer veränderlichen Syntax, wodurch komplexe Änderungen an verschachtelten Zuständen lesbar und sicher werden.

React 19 hat useOptimistic(state, updateFn) als integrierten Hook für optimistische Aktualisierungen innerhalb von Server Actions eingeführt. const [optimisticState, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]). Der Aufruf von addOptimistic(newItem) aktualisiert die Benutzeroberfläche sofort, während die Server Action asynchron ausgeführt wird.

useOptimistic übernimmt das Rollback automatisch. Wenn die Server Action abgeschlossen ist (erfolgreich oder mit einem Fehler), setzt React den optimistischen Zustand zurück und wendet den tatsächlichen Zustand vom Server an. Sie müssen keine manuelle Rollback-Logik schreiben – React verwaltet den Lebenszyklus der optimistischen Aktualisierung innerhalb der Suspense Boundary der Aktion.

Manuelle optimistische Aktualisierungen bieten vollständige Kontrolle, erfordern aber zusätzlichen Boilerplate-Code. React Query integriert mit onMutate/onError/onSettled den Abfrage-Cache in die automatische Synchronisierung. useOptimistic ist für Server Actions am einfachsten, erfordert jedoch React 19 und eine Server-Action-Architektur. Wählen Sie je nach Datenschicht: manuell für einfachen lokalen Zustand, React Query für REST-APIs und useOptimistic für RSC/Server Actions.

Berücksichtigen Sie bei der Auswahl eines optimistischen Musters Ihre Architektur. Wenn Sie React Query in Ihrer gesamten Anwendung verwenden, ist das onMutate-Muster konsistent und cachebewusst. Wenn Sie Zustand für den globalen Zustand verwenden, passt das aktionsbasierte Muster natürlich dazu. Wenn Sie React 19 mit Server Actions einsetzen, ist useOptimistic die idiomatische Wahl. Es ist üblich und akzeptabel, innerhalb einer Anwendung verschiedene Muster zu kombinieren.

Was sollte der Rückruf onMutate in React Query zurückgeben, damit ein Rollback in onError möglich ist?

React Query useMutation verwendet onMutate (Abfragen abbrechen, Snapshot erstellen, optimistische Aktualisierung anwenden, Kontext zurückgeben), onError (Snapshot aus dem Kontext wiederherstellen) und onSettled (Abfrage zur Aktualisierung entwerten). Optimistische Aktualisierungen mit Zustand rufen zuerst die Zustandsaktion und anschließend die API auf und machen die Änderung bei einem Fehler rückgängig. React 19 bietet mit useOptimistic ein automatisches Rollback innerhalb von Server Actions. Wählen Sie das Muster, das zur Architektur Ihrer Datenschicht passt.