TanStack Query Grundlagen: Abfragen, Caching, Mutationen und Invalidation
Erfahren Sie, wie useQuery, queryKey, staleTime, gcTime, useMutation und invalidation zusammenwirken, um den Serverzustand in React ohne manuell geschriebene Fetch-Effekte zu verwalten.
Quellen: Started with React Query
TanStack Query, früher React Query, verwaltet Daten, die von einem Server stammen. Der Name änderte sich, weil die Bibliothek nun auch außerhalb von React in Svelte, Vue und Solid funktioniert. Kurz ausgedrückt handelt es sich um einen Zustandsmanager für Serverzustände.
Serverzustand versus Clientzustand
Serverzustand sind Daten, die aus einem Backend oder einer externen API stammen: Benutzer, Produkte, Beiträge, Kommentare. Er befindet sich außerhalb der Anwendung, sodass die Anwendung ihn nicht vollständig kontrollieren kann. Er kann sich ohne Wissen der Anwendung ändern, veralten und ist nur über eine asynchrone Anfrage erreichbar.
Clientzustand gehört zur Anwendung selbst. Ob beispielsweise ein Modal geöffnet ist, existiert nur im Browser, wie in const [isModalOpen, setIsModalOpen] = useState(false). Zustand, Redux und Jotai sind die üblichen Werkzeuge für diese Art von Zustand.
Der manuelle Ansatz und seine Kosten
Ohne Bibliothek beginnt das Abrufen von Benutzern in der Regel mit drei Zustandswerten.
const [users, setUsers] = useState([])
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)
Dann führt ein Effekt das Laden durch.
useEffect(() => {
async function fetchUsers() {
try {
setLoading(true) const res = await fetch(
"https://jsonplaceholder.typicode.com/users"
) const data = await res.json() setUsers(data)
} catch (err) {
setError(err)
} finally {
setLoading(false)
}
} fetchUsers()
Die Benutzer werden abgerufen, im Zustand gespeichert, ein Ladeflagge wird gesetzt und Fehler werden erfasst. Wenn eine App wächst, wiederholt sich dieses Muster überall, und jede Kopie muss mit Lade- und Fehlerzuständen, Caching, Neuabruf, Hintergrundneuabruf, Synchronisierung und Wiederholungsversuchen umgehen. Wenn man das auf eine große Codebasis anwendet, entsteht verworrener Code.
Das Gleiche mit einer Abfrage
Ein einziger Hook ersetzt den Boilerplate-Code.
function Users() {
const {
data,
isLoading,
error
} = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Dann geht die Komponente je nach Status eine Abzweigung ein.
if (isLoading) {
return <p>Loading...</p>
} if (error) {
return <p>Something went wrong</p>
} return (
<ul>
{data.map(user => (
<li key={user.id}>
{user.name}
</li>
))}
</ul>
)
}
TanStack Query übernimmt die Infrastruktur rund um Serverdaten. Sein Hauptvorteil gegenüber useEffect zusammen mit useState ist das eingebaute Caching. Sobald die Daten ankommen, werden sie in einem Cache gespeichert und können später wiederverwendet werden, wodurch unnötige API-Anfragen vermieden werden. Die Lade-, Erfolgs- und Fehlerzustände werden automatisch überwacht, sodass keine Logik manuell geschrieben und gewartet werden muss.
Einrichtung
Installieren Sie das Paket.
npm install @tanstack/react-query
Erstellen Sie anschließend einen QueryClient und stellen Sie ihn der Anwendung zur Verfügung.
const queryClient = new QueryClient();
root.render(
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
);
Daten abrufen mit useQuery
Der Hook useQuery kümmert sich um Lesevorgänge, also um alles, was Serverdaten abruft. Ein einfacher Aufruf sieht so aus:
const { data,
isPending,
error } = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Es wird ein Options-Objekt benötigt, wobei zwei Eigenschaften am wichtigsten sind: queryFn und queryKey.
queryFn ist die Funktion, die von TanStack Query aufgerufen wird, um die Daten zu erhalten. Sie gibt die Daten direkt oder als Promise zurück, und bei einem Fehler sollte sie entweder einen Fehler auslösen oder ein abgelehntes Promise zurückgeben.
async function fetchUsers() {
const res = await fetch("/api/users")
if (!res.ok) {
throw new Error("Failed to fetch users")
}
return res.json()
}
Dann wird es in den Haken eingesteckt:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Der queryKey identifiziert eindeutig eine Abfrage sowie ihre im Cache gespeicherten Daten. Variablen, die von queryFn verwendet werden, sollten in der Regel im Schlüssel enthalten sein. Beispielsweise könnte ["users"] alle Benutzer darstellen, ["todo", 1] den Todo mit ID 1 und ["products", "laptops"] Laptops.
Der Hook gibt ein Objekt zurück, das den Status der Abfrage (Laden, Fehler oder Erfolg), die Daten sowie Funktionen zum Neuladen enthält.
Wie der Cache hilft
Hier zeigt sich der Nutzen der Bibliothek. Die heruntergeladenen Daten werden automatisch gespeichert und wiederverwendet, um überflüssige Aufrufe zu vermeiden. Dadurch wird die Leistung verbessert und die Zeit bis zur Anzeige der Ergebnisse verkürzt.
Sagen wir, Komponente A fragt nach ["users"]. TanStack Query lädt das Ergebnis herunter und speichert es im Cache. Später fragt Komponente B nach derselben Schlüsselangabe, und die Bibliothek erkennt, dass die Daten bereits im Cache sind. Anstatt dass jede Komponente ihre eigene Kopie behält, verwaltet TanStack Query nur eine einzige, im Cache gespeicherte Kopie des Serverzustands. Das ist einer der größten Unterschiede zwischen dem einfachen fetch() und dieser Bibliothek.
staleTime und gcTime
staleTime beantwortet eine Frage: Wie lange sollen diese Daten als aktuell gelten?
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60,000 // 60 seconds
})
Durch diese Einstellung sind die Daten in den ersten 60 Sekunden aktuell. Nach einer Minute werden sie veraltet, was es ermöglicht, eine erneute Abfrage auszulösen und einen Hintergrund-Neuabruf durchzuführen. Veraltet bedeutet jedoch nicht gelöscht, obwohl die Daten möglicherweise veraltet sein können. Sobald sie veraltet sind, können sie erneut abgerufen werden, wenn etwas dies auslöst, wie zum Beispiel wenn das Fenster wieder den Fokus erhält oder ein Komponente geladen wird.
Wenn man die Veraltetheit ignoriert, entstehen unnötige Anfragen, wenn Benutzer eine Seite erneut aufrufen.
User visits page
↓
Fetch users
↓
User navigates away
↓
User comes back
↓
Fetch users again
Falls sich nichts ändert, ist die zweite Anfrage sinnlos. Ein längeres Frischefenster vermeidet das:
staleTime: 5 * 60 * 1000
Dadurch wird die Daten als frisch für fünf Minuten markiert. Denken Sie daran, dass staleTime die Frische steuert und kein Intervall für ein Neuladen ist.
Ebenfalls vorhanden ist gcTime, die Zeit für die Müllsammlung. Sie legt fest, wie lange inaktive, nicht überwachte gecachte Daten im Speicher verbleiben, bevor sie gesammelt werden.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
gcTime: 60000
})
Zusammenfassend lässt sich sagen, dass staleTime angibt, wie lange Daten frisch bleiben, und gcTime angibt, wie lange ungenutzte Cache-Einträge bestehen bleiben. Sie lösen unterschiedliche Probleme.
Aufrufen neu
Veraltete Abfragen können neu aufgerufen werden, wenn eine Komponente geladen wird, das Fenster wieder den Fokus erhält oder die Verbindung zum Netzwerk wiederhergestellt wird – und diese Verhaltensweisen sind konfigurierbar. Ein manuelles Neuaufrufen ist ebenfalls möglich.
const { refetch } = useQuery(...)
refetch()
Auch das Abfragen ist möglich.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchInterval: 30,000
})
Während die Abfrage aktiv ist, wird sie in etwa alle 30 Sekunden erneut abgerufen. Durch diese erneute Abfrage werden veraltete Daten durch aktuelle Daten aus dem Backend ersetzt.
Daten mit useMutation ändern
Bis jetzt wurde nur Daten abgerufen. Das Erstellen, Aktualisieren oder Löschen von Daten (POST, PUT, PATCH, DELETE) erfolgt über den useMutation-Hook. Als Beispiel: Hier wird ein Benutzer erstellt. Zuerst kommt die Mutationsfunktion.
async function createUser(user) {
const response = await fetch(
"https://jsonplaceholder.typicode.com/users",
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(user),
}
);
if (!response.ok) {
throw new Error("Failed to create user");
}
return response.json();
}
Danach wird es an useMutation weitergeleitet.
import { useMutation } from "@tanstack/react-query";
function CreateUser() {
const mutation = useMutation({
mutationFn: createUser,
});
return (
<button
onClick={() =>
mutation.mutate({
name: "John Doe",
email: "john@example.com",
})
}
disabled={mutation.isPending}
>
{mutation.isPending ? "Creating..." : "Create User"}
</button>
);
}
export default CreateUser;
Ein Klick auf die Schaltfläche löst die Mutation über mutation.mutate() aus.
Button click
↓
mutation.mutate(user)
↓
createUser(user)
↓
POST request
↓
Server
Beachten Sie, dass createUser() niemals direkt aufgerufen wird. Die Komponente ruft mutation.mutate() auf, und TanStack Query führt diese Funktion aus.
Mutationen verfügen genauso wie Abfragen über Statusflaggen.
const {
mutate,
isPending,
isSuccess,
isError,
error,
data,
} = useMutation({
mutationFn: createUser,
});
Sie steuern die Benutzeroberfläche.
<button
onClick={() => mutate({ userName: "delfina ghimire" })}
disabled={isPending}
>
{isPending ? "Creating..." : "Create user"}
</button>
Sobald mutate() ausgeführt wird, durchläuft die Mutation mehrere Zustände:
isPending: Die Mutation ist im Lauf.isSuccess: Sie wurde erfolgreich abgeschlossen.isError: Sie ist fehlgeschlagen.data: Das Ergebnis einer erfolgreichen Mutation.error: Details im Falle eines Fehlschlags.mutate: Der Auslöser, der die Variablen für die Mutationsfunktion entgegennimmt.
Dadurch wird das Geben von Feedback während eines Erstellens, Aktualisierens oder Löschens unkompliziert.
QueryClient und Invalidation
Der QueryClient ist ein zentrales Objekt, das den Cache verwaltet und koordiniert, wie Abfragen und Mutationen funktionieren. Er wird ursprünglich mit new QueryClient() erstellt und innerhalb eines Components über useQueryClient() zugänglich. Er unterstützt die Ungültigmachung von Abfragen, das Aktualisieren von im Cache gespeicherten Daten, das Entfernen solcher Daten, das Zurücksetzen von Abfragen sowie das Vorausladen. Eine typische Aufrufweise ist queryClient.invalidateQueries({ queryKey: ["users"] }).
Die Ungültigmachung ist insbesondere nach Mutationen wichtig. Wenn eine Mutation die Serverdaten ändert, können damit verbundene Abfragen veraltete Ergebnisse enthalten; ihre Ungültigmachung markiert sie als veraltet, sodass sie neu geladen werden können. Angenommen, der Cache enthält zwei Benutzer:
[
{ id: 1, userName: "delfina ghimire" },
{ id: 2, userName: "spiderman ghimire" },
]
Dann wird ein neuer Benutzer erstellt.
mutation.mutate({
userName: "ironman ghimire",
});
Der Server hat jetzt drei Benutzer, aber der Cache zeigt immer noch zwei an. Die Abfrage ["users"] kann als veraltet markiert werden. Zuerst wird der Client abgerufen:
const queryClient = useQueryClient();
Dann wird die Mutation bei Erfolg ungültig.
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
});
},
});
Der Ablauf verläuft wie folgt:
Create Users (Mutation)
↓
Server data changes
↓
Invalidate ["users"]
↓
Query becomes stale
↓
Refetch
↓
UI gets fresh data
Zur Klarstellung der Begriffe: invalidate markiert gespeicherte Daten als veraltet, während refetch sie umgehend erneut lädt. Die Invalidation einer aktiven Abfrage löst in der Regel eine automatische Neuladung aus.
Das Gesamtbild
Alle Komponenten bilden ein zusammenhängendes Bild:
- TanStack Query verwaltet Serverdaten.
- Das Lesen erfolgt mit
useQuery. - Die geladenen Daten landen im Abfragespeicher.
staleTimebestimmt, wann gespeicherte Daten als aktuell gelten.gcTimelegt fest, wie lange ungenutzte Cache-Einträge erhalten bleiben.- Durch Refetching wird entschieden, wann Daten erneut geladen werden.
- Erstellen, Aktualisieren und Löschen geschehen über
useMutation. - Der QueryClient koordiniert Abfragen, Mutationen und den Cache.
- Die Invalidation einer Abfrage signalisiert, dass die gespeicherten Daten veraltet sind.
Sobald diese Beziehungen klar sind, wird es viel einfacher, sich die Bibliothek vorzustellen.