Szczegółowy przewodnik TanStack Query: zapytania, pamięć podręczna, mutyacje oraz optymistyczne interfejsy użytkownika

Dzisiejszym tematem jest TanStack Query (wcześniej React Query): biblioteka, która przekształca chaotyczne pobieranie danych z serwera w przewidywalne procesy zarządzania pamięcią cache, świeżością danych oraz ich modyfikacją. Analogia z ekskluzywnym restauracją ułatwia zapamiętanie poszczególnych elementów – sala jadalna to interfejs użytkownika, kuchnia to warstwa backendowa, kelnerzy to klienty HTTP, a menedżer to TanStack Query.

Czym jest TanStack Query?

W typowej aplikacji interfejs użytkownika żąda danych od warstwy backendowej za pomocą fetch lub Axios. Te narzędzia nie są zbyt sprytnie zarządzane pod względem koordynacji. Jeśli pięć komponentów jednocześnie poprosi o ten sam menu, może dojść do pięciu oddzielnych wyjazdów do kuchni. Jeśli jeden gość poprosi o zupę dnia, a drugi dziesięć sekund później, naiwny kelner ponownie wraca do kuchni. To przeciąża serwer i spowalnia pracę w restauracji.

TanStack Query pełni rolę głównego kelnera i menedżera restauracji: koordynuje pobieranie, przechowywanie w pamięci cache, synchronizację oraz aktualizację stanu serwera, dzięki czemu kuchnia nie jest nękana identycznymi zapytaniami.

Axios / Fetch vs. TanStack Query

Początkujący często myślą, że TanStack Query zastępuje Axios lub fetch. Tak nie jest.

• Fetch i Axios to kelnerzy. Przenoszą zapytanie do kuchni i przywożą odpowiedź. Nie pamiętają poprzednich zadań, nie oceniają świeżości ani nie koordynują działań innych pracowników.
• TanStack Query to menedżer. Zatrudnia kelnerów do wykonywania zadań. Pamięta, co wróciło, czy dane są nadal uważane za świeże, które stoliki korzystają z tego samego notatnika oraz kiedy wysłać kogoś z powrotem po zmianie dania w kuchni.

Nadal piszesz ciała funkcji queryFn, które wywołują Axios lub fetch. TanStack Query otacza te wywołania kluczami cache, mechanizmami eliminacji duplikatów, powtórnymi próbami oraz hookami związanymi z cyklem życia aplikacji.

Czym jest TanStack Query? (mapa funkcji)

Sześć funkcji jest najważniejszych w codziennej pracy z React:

1. Zapytania (useQuery): pobieranie danych

Czytania deklaratywne, które są identyfikowane za pomocą queryKey i realizowane przez queryFn.

2. Cacheowanie: „mózg” menedżera

Wyniki są przechowywane w pamięci pod kluczem query key, dzięki czemu kilka komponentów może korzystać z jednej transmisji sieciowej.

3. Świeżość: staleTime vs gcTime

staleTime określa, kiedy dane z cache są uznawane za na tyle przestarzałe, by je ponownie pobrać. gcTime (zbieranie śmieci) decyduje o tym, jak długo nie używane wpisy cache pozostają przed ich usunięciem.

4. Mutacje (useMutation): zmiana danych

Zapisy — tworzenie, aktualizacja, usuwanie — są wykonywane na żądanie, a nie przy uruchomieniu.

5. Unieważnianie zapytań: usuwanie menu

Po pomyślnej mutacji zaznacza się powiązane zapytania jako przestarzałe, aby interfejs ponownie zsynchronizował się z serwerem.

6. Aktualizacje optymistyczne: doświadczenie na miarę gwiazdek Michelin

Niezwłocznie aktualizuje się pamięć cache, w przypadku błędu cofa się zmiany i dokonuje ostatecznej synchronizacji.

Pozostała część tego przewodnika omawia każdą z tych funkcji przy użyciu przykładów z restauracji oraz konkretnych struktur kodu.

1. Zapytania (useQuery): pobieranie menu

Zapytanie określa, czego chcemy i w jaki sposób to uzyskać:

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';

// The waiter function (Axios)
const fetchMenu = async () => {
  const response = await axios.get('/api/menu');
  return response.data;
};

function MenuComponent() {
  // The Manager (TanStack Query) orchestrating the process
  const { data: menu, isLoading, isError, error } = useQuery({
    queryKey: ['menu'], // The label for this specific data
    queryFn: fetchMenu,  // The waiter doing the fetching
  });

  if (isLoading) return <div>Waiter is walking to the kitchen... Loading Menu...</div>;
  if (isError) return <div>The kitchen is on fire! Error: {error.message}</div>;

  return (
    <ul>
      {menu.map((item) => (
        <li key={item.id}>{item.name} - ${item.price}</li>
      ))}
    </ul>
  );
}

queryKey to nazwa pliku w notatniku menedżera — ['menu'], ['soup'], ['allergies', tableId]. Klucze identyczne dzielą się pamięcią cache i eliminują duplikaty w trakcie wysyłanych żądań. queryFn to procedura obsługująca żądanie: musi zwrócić obietnicę otrzymania danych.

Gdy trwa pierwsze pobieranie, flagi isPending / loading pozwalają interfejsowi wyświetlać tymczasowe elementy. Błędy są rejestrowane za pomocą isError i error. Udane dane pojawiają się w polu data i są dostępne dla wszystkich komponentów obserwujących ten klucz.

Czym jest warunek wyścigu?

Analogia restauracyjna

Załóżmy, że dwóch gości prosi o zupę, podczas gdy kuchnia pracuje powoli. Opóźniona odpowiedź dla stolika A nie może nadpisać nowszego żądania z stolika B. Bez koordynacji zwycięża to, które żądanie zostanie sfinalizowane jako ostatnie — nawet jeśli dane są przestarzałe.

Jak to działa w React (useEffect)

Ręczne pobieranie danych za pomocą useEffect często pomija logikę anulowania zapytań. Szybkie przeglądanie stron może spowodować, że starsza odpowiedź zaktualizuje stan po rozpoczęciu nowszego żądania.

Jak TanStack Query rozwiązuje ten problem

Biblioteka śledzi trwające zapytania według klucza, może je anulować za pomocą AbortSignal, gdy jest to możliwe, i zapewnia, że elementy interfejsu widzą spójne zmiany w pamięci cache, a nie przypadkowe konkurencje przy użyciu setState.

2. Cacheowanie: notatnik menedżera

// Waiter function
const fetchMenu = async () => {
  console.log("Waiter is walking to the kitchen!"); // We can track how many times this runs
  const response = await axios.get('/api/menu');
  return response.data;
};

// Component 1: The Sidebar
function MenuSidebar() {
  const { data } = useQuery({ queryKey: ['menu'], queryFn: fetchMenu });
  return <div>We have {data?.length} items today!</div>;
}

// Component 2: The Main Display
function MenuMainDisplay() {
  const { data } = useQuery({ queryKey: ['menu'], queryFn: fetchMenu });
  return <div>{data?.map(item => <p>{item.name}</p>)}</div>;
}

Gdy pierwszy komponent jest ładowany z parametrem ['menu'], menedżer wysyła odpowiedni proces do wykonania zapytania. Gdy kilka milisekund później ładowany jest drugi komponent z tym samym kluczem, menedżer czyta dane z notatnika zamiast ponownie wysyłać żądanie. To właśnie dzięki temu usuwaniu duplikatów panele sterowania z wieloma elementami wyświetlającymi dane użytkownika lub konfiguracji działają szybko, bez potrzeby stosowania specjalnych globalnych zasobów pamięci.

Menedżer w działaniu (krok po kroku)

1. Komponent A jest ładowany → brak danych w pamięci cache → połączenie sieciowe.
2. Nadchodzi odpowiedź → zapisanie do pamięci cache → komponent A jest renderowany.
3. Komponent B jest ładowany przy użyciu tej samej klucza → dane znajdują się w pamięci cache → komponent B jest renderowany natychmiast.
4. Zgodnie z zasadami świeżości, później może nastąpić tło ponownego pobierania danych bez blokowania pierwszego renderowania komponentu B.

Stan serwera powinien być przechowywany w TanStack Query; prawdziwy stan interfejsu klienta (otwarty moduł, wybrana karta) może znajdować się w stanie React lub w lekkim magazynie danych klienta.

3. Świeżość: konfiguracja staleTime i gcTime

1. staleTime: czy te dane są nadal dokładne?

const { data } = useQuery({
  queryKey: ['soup'],
  queryFn: fetchSoup,
  staleTime: 1000 * 60 * 30, // 30 minutes
});

Dzięki ustawieniu staleTime: 10_000 dane młodsze niż dziesięć sekund są uważane za aktualne: przy ponownym załadowaniu są wykorzystywane bez konieczności ponownego pobierania. Gdy staną się przestarzałe, obserwatory mogą uruchomić tło do ponownego pobierania danych (przy ponownym załadowaniu, przy skupieniu uwagi na oknie lub po ponownym połączeniu — w zależności od ustawień domyślnych i opcji). Wartość staleTime powinna być dobrana pod kątem zmienności danych w danym domenie: lista dań dnia może być krótka, natomiast listy krajów mogą być długie.

2. gcTime: czy mogę wyrzucić te dane?

const { data } = useQuery({
  queryKey: ['allergies', 'table4'],
  queryFn: fetchAllergies,
  gcTime: 1000 * 60 * 60 * 24, // Keep in memory for 24 hours
});

gcTime określa, jak długo wpis w pamięci cache pozostaje po tym, jak wszyscy obserwatorzy przestaną go używać. Krótki czas gcTime szybciej zwalnia pamięć, natomiast dłuższy czas sprawia, że ponowne odwiedzanie stron następuje natychmiastowo. Nie należy go mylić z staleTime: dane przestarzałe mogą nadal pozostawać w pamięci aż do ich usunięcia przez mechanizm zbierania śmieci.

Ostateczna tajemnica: stale-while-revalidate

TanStack Query z przyjemnością pokazuje przestarzałe dane podczas ponownego pobierania ich w tle. Użytkownicy natychmiast widzą ostatni dostępny menu; gdy kuchnia potwierdzi aktualizacje, notatnik się odświeża. To właśnie dzięki takiemu podejściu biblioteka wydaje się szybsza niż ikony spinające przy każdej wizycie.

4. Mutacje (useMutation): dodawanie nowego dania

Czym jest mutacja?

Mutacja zmienia stan serwera – składanie zamówienia, edycja profilu, usuwanie komentarza.

Analogia z restauracją: składanie zamówienia

Kelnerzy nie składają automatycznie zamówień, gdy gość się usadawia; czekają na wyraźną prośbę. Mutacje działają podobnie – są wykonywane, gdy wywołuje się funkcje mutate lub mutateAsync.

Kod: tworzenie formularza zamówień

import { useMutation } from '@tanstack/react-query';
import axios from 'axios';
import { useState } from 'react';

// 1. The Waiter Function (The actual network request)
const placeOrder = async (orderData) => {
  // We are using POST because we are creating a new order
  const response = await axios.post('/api/orders', orderData);
  return response.data;
};

function OrderForm() {
  const [dish, setDish] = useState('');

  // 2. The Manager orchestrating the mutation
  const mutation = useMutation({
    mutationFn: placeOrder,
    // We can also trigger side effects right here!
    onSuccess: (data) => {
      console.log("Chef says: Order confirmed!", data);
    },
    onError: (error) => {
      console.log("Chef says: We have a problem.", error.message);
    }
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    // 3. Triggering the mutation and passing the variables
    mutation.mutate({ dishName: dish, tableNumber: 4 });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={dish}
        onChange={(e) => setDish(e.target.value)}
        placeholder="What would you like?"
      />

      {/* Notice how we use isPending to disable the button so they don't double-order! */}
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Sending to Kitchen...' : 'Place Order'}
      </button>

      {/* Handling the feedback */}
      {mutation.isError && <p style={{ color: 'red' }}>Failed: {mutation.error.message}</p>}
      {mutation.isSuccess && <p style={{ color: 'green' }}>Order placed successfully!</p>}
    </form>
  );
}

Podłącz onSuccess do wyświetlania komunikatów potwierdzenia, informacji o nawigacji lub sygnałów o nieważności. Użyj mutateAsync, gdy musisz czekać na zakończenie operacji w obsługiwaczach wysyłania.

Szczegóły dla zaawansowanych programistów

1. Nie uruchamia się automatycznie

W odróżnieniu od zapytań, mutacje pozostają nieaktywne dopóki nie zostaną wywołane – co zapobiega przypadkowym zapisom podczas renderowania.

2. isPending vs isLoading

W wersji v5 lepiej używać isPending do reprezentowania stanu trwającej mutacji. Skonfiguruj wyłączanie interfejsu zgodnie z tym flagiem.

3. Zapobieganie problemowi podwójnego kliknięcia

Wyłącz przycisk wysyłania, gdy isPending ma wartość true, aby goście nie mogli wysyłać podwójnych zamówień.

5. Nieważnienie zapytań: poinformowanie menedżera o aktualizacji notatnika

Problem: przestarzały notatnik

Po dodaniu dania przez szefa kuchni, stoliki wciąż wyświetlające zapisane menu widzą listę z wczorajszego dnia, dopóki coś nie pobraje jej ponownie.

Rozwiązanie: unieważnianie zapytań

import { useMutation, useQueryClient } from '@tanstack/react-query';
import axios from 'axios';

function AddDishForm() {
  // 1. Get access to the Manager's office
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: async (newDish) => {
      const response = await axios.post('/api/menu', newDish);
      return response.data;
    },
    // 2. The magic happens HERE in the onSuccess callback
    onSuccess: () => {
      // 3. Tell the Manager to rip up the menu notepad
      queryClient.invalidateQueries({ queryKey: ['menu'] });
      console.log("Menu invalidated! The Manager is getting a fresh copy.");
    },
  });

  // ... form code
}

invalidateQueries oznacza odpowiadające im wpisy jako przestarzałe i wyzwalaje ponowne pobieranie danych dla aktywnych obserwatorów.

Co dokładnie się dzieje, gdy wywołuje się invalidateQueries?

Odpowiadające zapytania stają się przestarzałe; zamontowane obserwatory pobierają dane ponownie; niezamontowane wpisy czekają do następnego zamontowania (w zależności od gcTime). Kuchnia pozostaje źródłem prawdy; notatnik otrzymuje polecenie odświeżenia.

Zaawansowane pojęcie: dopasowanie nieprecyzyjne

Ograniczone unieważnianie:

queryClient.invalidateQueries({ queryKey: ['menu', 'lunch'] });

Lub unieważnienie całego prefiksu:

// This rips up the breakfast, lunch, and dinner notepads all at once!
queryClient.invalidateQueries({ queryKey: ['menu'] });

Matching przy użyciu zaawansowanych wzorców niszczy notatniki z informacjami o śniadaniach, obiadowych i kolacyjnych posiłkach, gdy szeroko unieważniasz ['menu'] — co jest potężne, ale też niebezpieczne. Lepiej używać jak najwęższego kryterium, które zapewni poprawność interfejsu.

Złota zasada mutacji

Każda udana operacja zapisu powinna albo unieważnić operacje odczytu, które od niej zależą, albo dokonać precyzyjnej aktualizacji pamięci podręcznej. Pozostawianie operacji odczytu bez zmian powoduje, że interfejs pokazuje błędne dane po zapisaniu.

6. Optymistyczne aktualizacje: doświadczenie na miarę gwiazdek Michelin

Analogia: zaufanie menedżera

Zaufany menedżer może zapisać nowe piwo na rachunku, zanim kuchnia to potwierdzi — a następnie je usunąć, jeśli butelka jest pusta.

Trzy filary optymistycznej aktualizacji

Wewnątrz useMutation:

1. onMutate: zatrzymaj sprzeczne żądania, zrób kopię pamięci podręcznej i natychmiast zapisz dane w formie optymistycznej.

onError: przywróć zrzut stanu, jeśli serwer odrzuci żądanie.

onSettled: unieważnij (lub w inny sposób zsynchronizuj) dane, aby cache odpowiadał bazie danych niezależnie od tego, czy operacja się udała, czy nie.

Kod: dodawanie dania w sposób optymistyczny

import { useMutation, useQueryClient } from '@tanstack/react-query';
import axios from 'axios';

function AddDishForm() {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: async (newDish) => {
      const response = await axios.post('/api/menu', newDish);
      return response.data;
    },

    // 1. The millisecond the user clicks submit...
    onMutate: async (newDish) => {
      // A. Cancel any outgoing refetches so they don't overwrite our optimistic update
      await queryClient.cancelQueries({ queryKey: ['menu'] });

      // B. Take a snapshot of the current menu (The Eraser Backup)
      const previousMenu = queryClient.getQueryData(['menu']);

      // C. Optimistically update the Manager's notepad right now!
      queryClient.setQueryData(['menu'], (oldMenu = []) => {
        // We fake an ID for now, the real ID comes from the database later
        return [...oldMenu, { ...newDish, id: Math.random().toString() }];
      });

      // D. Return the snapshot so onError can use it if things go wrong
      return { previousMenu };
    },

    // 2. If the Kitchen catches on fire...
    onError: (err, newDish, context) => {
      // Use the eraser! Roll back to the snapshot we saved in onMutate
      if (context?.previousMenu) {
        queryClient.setQueryData(['menu'], context.previousMenu);
      }
      console.error("Chef says no! Rolling back.", err);
    },

    // 3. Always run this at the very end, success or fail...
    onSettled: () => {
      // Tell the Manager to get the real, final menu from the database
      queryClient.invalidateQueries({ queryKey: ['menu'] });
    },
  });

  // ... form code
}

Należy zwrócić uwagę na anulowanie trwających zapytań, strukturę zrzutów stanu oraz ścieżki odwracania działań. Interfejs optymistyczny sprawia wrażenie natychmiastowej reakcji, ale nie może pozostawić cache’u w niewygodnej sytuacji, gdy kuchnia odrzuci żądanie.

Łączenie kluczowych elementów

• TanStack Query to menedżer stanu asynchronicznego, a nie narzędzie do pobierania danych. Otacza on Axios/fetch, aby ułatwić przewidywanie problemów sieciowych.
• Klucz zapytania jest najważniejszy. On determinuje proces usuwania duplikatów, przechowywania w cache’u oraz udostępniania danych pomiędzy komponentami.

Zadaniem użytkownika jest synchronizacja pamięci cache po zapisach. Należy używać invalidateQueries lub starannie zaprojektowanych aktualizacji optymistycznych, aby notatnik klienta był zgodny z danymi w serwerze.

Praktyczne domyślne ustawienia dla rzeczywistych aplikacji

Należy zacząć od rozsądnego wartości staleTime dla zasobów w większości statycznych (w minutach) oraz krótkiego lub zerowego staleTime dla danych zmiennej natury specyficznych dla użytkownika. queryFn powinien być prosty i możliwy do przerwania. Klucze należy centralizować w funkcjach fabrycznych (menuKeys.list(), menuKeys.detail(id)), aby proces unieważniania pozostawał spójny i typowany. W fazie rozwoju należy rejestrować zdarzenia pamięci cache podczas diagnozowania dublowanych żądań. Lepiej stosować unieważnianie danych niż skomplikowane ręczne modyfikacje pamięci cache, chyba że ekran naprawdę wymaga specjalnych rozwiązań optymistycznych.

Częste przyczyny awarii

• Używanie niestabilnych kluczy (nowe literalne obiekty przy każdym renderowaniu) niszczy pamięć cache.
• Zaniedbanie unieważnienia danych po mutacjach powoduje pokazywanie się starych informacji.
• Ustawienie nieskończonego wartości staleTime bez strategii mutacji zamyka interfejsy użytkownika.
• Umieszczanie wszystkich flag interfejsu klienta w pamięci cache zapytań zamazuje granice stanu serwera.
• Zbyt szerokie unieważnianie danych (błędy typu queryKey: ['']) powoduje ponowne pobieranie całej zawartości.

Unikaj tych problemów, a restauracja będzie funkcjonować sprawnie: kelnerzy będą poruszać się w razie potrzeby, notatnik menedżera pozostanie spójny, a goście będą mogli oglądać gorące jedzenie bez konieczności obserwowania drzwi kuchni co dziesięć sekund.

Zakończenie

TanStack Query zyskuje uznanie dzięki kontrolowaniu cykli życia stanu serwera – odczytów, aktualności danych, zapisów oraz synchronizacji – pozostawiając natomiast kwestie transporту Axios lub fetch. Poznaj narzędzia do konfiguracji (klawisze), ustawienia dotyczące aktualności (staleTime, gcTime) oraz procedury zapisu (mutacje, unieważnianie danych, aktualizacje optymistyczne). Dzięki temu aplikacje React przestają na nowo tworzyć mechanizmy cacheowania żądań w każdym useEffect i zaczynają funkcjonować jak dobrze zarządzana jadalnia.

Dlaczego metafora restauracji nadal się sprawdza

Struktury typu network waterfall wydają się abstrakcyjne, dopóki nie wyobrażymy sobie pięciu kelnerów pędzących po tę samą zupę. Proces eliminacji duplikatów to jak menedżer podnoszący rękę – jedna wizyta, obsłużenie wielu stolików. Zasada „stale-while-revalidate” polega na podawaniu ostatniej wydrukowanej karty menu, podczas gdy ktoś sprawdza tablicę z aktualnościami. Unieważnianie danych to usuwanie stron, gdy szef kuchni zmienia przepisy. Optymistyczne aktualizacje to zapisywanie zamówienia gościa na rachunku przed potwierdzeniem – z gumką w pogotowiu. Podczas wprowadzania nowych pracowników należy najpierw pokazać im te przykłady, zanim przedstawi się generyki w TypeScript – w ten sposób lepiej zapadnie w pamięć.

Integracja z routery i mechanizmami autoryzacji

Klucze powinny zawierać identyfikator najemcy lub użytkownika, gdy dane nie są globalne: ['menu', restaurantId] lub ['allergies', userId]. Po wylogowaniu należy oczyścić pamięć cache, aby uniknąć wycieku stron notatnika między różnymi użytkownikami. Z użyciem React Router lub podobnych narzędzi należy uruchamiać procedurę unieważniania po takich działaniach, które już wiedzą, które zasoby uległy zmianie, zamiast ponownie ładować wszystko przy każdej nawigacji.

Strategie testowania

Niezależnie przeprowadzaj testy jednostkowe dla mapowników queryFn. W testach komponentów otocz je QueryClientProvider, używając nowego klienta oraz ustawiając retry: false dla zapewnienia determinizmu. Sprawdź, czy mutacje wywołują invalidateQueries z oczekiwanymi kluczami. W przypadku podejścia optymistycznego symuluj błędy serwera i upewnij się, że nastąpi powrót do stanu zrobionego wcześniej. Unikaj dzielenia się jednym obiektem QueryClient pomiędzy niepowiązanymi testami bez uprzedniego sformatowania.

Uwagi dotyczące wydajności

Długie listy powinny być przechowywane za pomocą paginacji lub zapytań nieskończonych, a nie w ramach jednego mega-klucza. Selektory (select) umożliwiają komponentom monitorowanie określonych fragmentów bez ponownego renderowania na podstawie niepowiązanych pól cache. Upewnij się, że wyniki queryFn są serializowalne i stabilne. Mierz intensywność ponownych pobierania danych, gdy refetchOnWindowFocus działa przy bardzo krótkim czasie ważności staleTime na intensywnie używanych panelach — dostosowuj ustawienia indywidualnie dla każdego zapytania, a nie globalnie.

Sposób myślenia przy migracji z surowego useEffect

Zastąp efekty montażu, które ustawiają trójki typu loading/error/data, funkcją useQuery. Zastąp imperatywne obsługi POST funkcją useMutation. Usuń własnoręcznie stworzone cache’y. Zachowaj instancje Axios do interceptorów i nagłóweków autoryzacyjnych; przekaż je do queryFn. Migracja odbywa się stopniowo: praca po jednym ekranie nadal szybciej zapobiega błędom wynikającym z konkurencji.

Ostateczna lista kontrolna przed wdrożeniem funkcji

1. Stabilny, hierarchiczny queryKey.
2. Jasno określony staleTime wybrany dla domeny.
3. Mutacja połączona z unieważnieniem lub strategią optymizmu.
4. Czekająca na zatwierdzenie interfejs użytkownika uniemożliwia podawanie duplikatów.
5. Komunikaty o błędach lub mechanizmy ograniczeń są skonfigurowane.
6. Klucze o zakresie autoryzacji są usuwane po zakończeniu sesji.

Jeśli spełnisz te sześć warunków, TanStack Query przestanie być „jeszcze jedną biblioteką” i stanie się cichym menedżerem, którego potrzebował twój salon.

Przebieg: ładowanie menu w trzech komponentach

Załóżmy nagłówek pokazujący dzisiejszy zupę, panel boczny z listą specjalności obiadowych oraz główną przestrzeń, która wyświetla pełny menu. Bez TanStack Query każda z tych przestrzeni mogłaby uruchomić własny useEffect i wysłać żądanie do /api/menu. Dzięki wspólnemu queryKey: ['menu', restaurantId] pierwsze uruchomienie pokrywa koszt połączenia z siecią; pozostałe czytają dane już z pamięci podręcznej. Gdy szef kuchni aktualizuje zawartość zupy za pomocą formularza administracyjnego przy użyciu useMutation, unieważnienie wartości ['menu', restaurantId] odświeża wszystkie przestrzenie nadal widoczne na ekranie. Goście nigdy nie zobaczą trzech różnych wersji zupy tylko dlatego, że trzej kelnerzy się nie porozumieli.

To proste rozwiązanie obejmuje mechanizmy eliminacji duplikatów, wspólnej pamięci cache, aktualizacji danych oraz unieważniania starych informacji. Większość ekranów używanych w produkcji to jedynie wariacje tego schematu: nagłówek profilu z formularzem ustawień, ikona koszyka z listą produktów do opłacenia oraz dzwonek powiadomień z stroną z informacjami.

Projektowanie kluczy zapytań jak ścieżek plików

Traktuj klucze jako hierarchiczne ścieżki:

• ['menu', restaurantId]
• ['menu', restaurantId, 'lunch']
• ['menu', restaurantId, 'item', itemId]
• ['allergies', restaurantId, tableId]

Fabryki pomagają:

Anulowanie ważności ['menu', restaurantId] może umożliwić nieprecyzyjne dopasowanie głębszych kluczy, jeśli jest to skonfigurowane w ten sposób – dzięki temu można przechowywać raz listy aktualizacji, a raz widoki szczegółowe. Unikaj umieszczania wartości niemogących zostać zserializowanych (funkcji, instancji klas) wewnątrz kluczy. Wolij prymitywne identyfikatory oraz stabilne enumy.

Wybór wartości staleTime zgodnie z językiem produktu

Zapytaj właścicieli produktów, jak błędna może być interfejs użytkownika przez N sekund. Teksty marketingowe, które zmieniają się co miesiąc, mogą tolerować dłuższy okres aktualności. Liczby zapasów podczas szybkich sprzedaży mogą wymagać niemal zerowego staleTime w połączeniu z unieważnieniem danych przy każdej modyfikacji zakupu. Zapisz tę decyzję obok zapytania, aby przyszli edytorzy nie „optymalizowali” niestabilnego zapytania tak, by okno jego aktualności było zbyt długie.

gcTime to parametr regulujący użycie pamięci. Aplikacje mobilne z wieloma ścieżkami korzystają z krótkotrwałego przechowywania ostatnich ekranów, dzięki czemu nawigacja wsteczna wydaje się natychmiastowa. Bardzo duże bufory pamięci na urządzeniach o ograniczonej ilości pamięci wymagają krótszego gcTime lub stronicowania.

Modyfikacje, które wydają się bezpieczne

Zawsze uwzględniaj stany oczekujące i błędów. Wyłącz przyciski niszczące, gdy istnieje stan oczekujący. W przypadku usuwania, optymistyczne usunięcie powinno przywrócić zrzut stanu, jeśli serwer zwróci błędy 409 lub 500. W przypadku tworzenia, wiersze utworzone w trybie optymistycznym wymagają, aby tymczasowe ID klienta zostały zastąpione ID serwera po pomyślnym działaniu – albo unikaj tego podejścia i zamiast tego unieważnij dane, gdy mapowanie ID sprawia trudności.

Paralelne modyfikacje tej samej klucza mogą się wzajemnie blokować; ułóż je w kolejce lub wyłącz odpowiednie elementy sterujące. Funkcja mutateAsync w bibliotekach form powinna znajdować się w obsługiwaczach przesłania danych z blokami try/catch, a nie w funkcjach renderowania.

Wzorce unieważniania, które są skalowalne

Po zalogowaniu należy unieważnić klucze specyficzne dla użytkownika, zamiast usuwać cały klient, jeśli treści publiczne mają pozostać dostępne. Po wylogowaniu zazwyczaj właściwe jest użycie queryClient.clear(). Gdy websocket poinformuje o „zmianie menu”, należy wywołać te same funkcje unieważniania, które są używane przy mutacji HTTP, aby obie ścieżki stosowały tę samą strategię synchronizacji.

Należy przewidywanie ładować prawdopodobne strony szczegółowe po nadaniu kursora: queryClient.prefetchQuery({ queryKey, queryFn }) przekształca wyczuwalną opóźnienie w udane dostępy do pamięci cache, bez konieczności zmiany kodu na ekranie.

Aktualizacje optymistyczne bez mityków

Optymizm nie jest obowiązkowy przy każdym zapytaniu typu POST. Należy go stosować, gdy prosty scenariusz działania jest powszechny, korzyści dla interfejsu są oczywiste, a odwrócenie działań jest łatwe do zrealizowania. Należy go pominąć, gdy walidacja na serwerze jest skomplikowana lub gdy treść odpowiedzi jest konieczna do wyświetlenia (identyfikatory generowane przez serwer, ceny, podatki). Powolny spinner może być lepszy niż pokaz błędnych danych.

Gdy używasz optymizmu, utrzymuj zrzuty stanu w niezmienionej formie, anuluj sprzeczne zapytania w funkcji onMutate, a synchronizację zawsze wykonywaj w funkcji onSettled. Rejestruj odwołania w fazie rozwoju; ciche odwołania mylą zespół testowy.

Jak to się porównuje z globalnymi magazynami danych klienta

Redux lub Zustand mogą przechowywać dane serwera, ale będziesz musiał ponownie tworzyć pamięci cache, prosić o usunięcie duplikatów oraz aktualizować dane w tle. TanStack Query specjalizuje się właśnie w tej dziedzinie. Trzymaj tymczasową interfejs użytkownika w lokalnym stanie lub małym magazynie danych klienta; dane serwera przechowuj w cache zapytań. Mieszanie tych źródeł danych prowadzi do powstania podwójnych źródeł prawdy.

Szkolenie zespołu

Zorganizuj sesję szkoleniową: stwórz małe aplikację z menu, wykorzystując zapytania do listy, szczegółów, operacje tworzenia i unieważniania, a także mechanizm optymistycznego tworzenia. Wymagaj użycia specjalnych funkcji do generowania kluczy oraz mechanizmu wylogowania. Gdy ten wzorzec stanie się nawykiem, większe aplikacje przestaną gromadzić błędy związane z funkcją useEffect.

Tabela podsumowująca w prozie

Zapytania służą do odczytu. Mutacje służą do zapisu. Klucze określają wiersze pamięci cache. staleTime odpowiada na pytanie „Czy mogę to ponownie użyć bez pytania kuchni?”. gcTime odpowiada na pytanie „Czy mogę wyrzucić tę stronę notatnika?”. Mechanizm unieważniania odpowiada na pytanie „Kuchnia się zmieniła – odśwież dane”. Optymizm odpowiada na pytanie „Zaktualizuj rachunek teraz, usuń go w razie odrzucenia”. Do przesyłania danych używa się albo Axios, albo fetch. To podział zadań stanowi cały produkt.

Scenariusz od początku do końca: tablica specjalności obiadowych

Restauracja rozpoczyna zmianę obiadową. W zapytaniu dotyczącym specjalności używane jest queryKey: ['menu', restaurantId, 'lunch'] z wartością staleTime wynoszącą dwie minuty, ponieważ tablice informacyjne zmieniają się powoli w trakcie jednej zmiany. W komponencie z zupą na górze strony stosuje się ['menu', restaurantId, 'soup'] z oknem ważności trzydziestu sekund. Obie funkcje queryFn wywołują tę samą instancję Axios z interceptorami autoryzacyjnymi. Gdy administrator zapisuje nową zupę za pomocą useMutation, funkcja onSuccess unieważnia oba klucze – lub unieważnia wspólny prefiks ['menu', restaurantId], jeśli zamierzone jest dopasowanie nieprecyzyjne. Goście na wszystkich aktywnych tabletach widzą aktualizacje bez konieczności ręcznego odświeżania.

Gdyby formularz administracyjny używał ręcznie napisanej funkcji fetch bez mechanizmu unieważniania, tablety pokazywałyby przestarzałe dane aż do ponownego załadowania. To właśnie takie błędy ma na celu wyeliminowanie TanStack Query.

Fabryki kluczy zapytań w TypeScript

Centralizacja kluczy:

• menuKeys.all(restaurantId)
• menuKeys.lunch(restaurantId)
• menuKeys.item(restaurantId, itemId)

Fabryki zapobiegają błędom pisowni i umożliwiają wyszukiwanie nieprawidłowych wartości w bazie kodu. Wolno preferować tablice z elementami prymitywnymi. Gdy istnieją filtry, należy dołączyć zserializowane obiekty filtrów z ustalonym porządkiem kluczy. Nigdy nie umieszczaj całego obiektu opcji z props do klucza, chyba że jest on zapamiętywany i zserializowalny.

Opcje useQuery, z którymi faktycznie będziesz pracować

Poza queryKey i queryFn: flaga enabled blokuje pobieranie danych dopóki nie pojawią się identyfikatory; retry określa zasady radzenia sobie z tymczasowymi błędami; refetchOnWindowFocus można wyłączyć w przypadku kosztownych paneli kontrolnych; placeholderData lub initialData zapewniają stabilność układu; funkcja select ogranicza ilość pobieranych danych, by zmniejszyć liczbę ponownych renderowań. Domyślne ustawienia nadają się na początek; należy je dostosować do poszczególnych zapytań, gdy profile wykazują intensywne ponowne pobieranie danych.

Rozumienie mechanizmu stale-while-revalidate z perspektywy UX

Pokazywanie w ciągu 100 ms sumy koszyka z wczoraj podczas ponownego pobierania danych może być nie do przyjęcia; pokazywanie artykułu z centrum pomocy z wczoraj przez minutę jest w porządku. Należy to uwzględnić w wartości staleTime, a nie w ad hoc flagach. Błąd przy tle podczas ponownego pobierania danych nie powinien usuwać poprawnych, starszych danych, chyba że wyraźnie to zdecydujesz; użytkownicy wolą nieco starsze dane niż błąd w postaci ikony spinującej podczas pracy offline.

Mutacje: anatomia procesu wysyłania danych w stałej formie

Zdezaktywuj przycisk w przypadku zadań w oczekiwaniu; wyświetl błędy inline z pola error; po pomyślnym działaniu unieważnij lub zaktualizuj cache; po rozstrzygnięciu sprawy, w razie potrzeby, usuń lokalny stan formularza. Użyj funkcji mutateAsync w połączeniu z blokami try/catch w obsłudze wysyłki formularza w bibliotece. Nie wywołuj funkcji mutate w pętlach bez kontroli równoczesności. W przypadku przesyłania plików pokazuj postęp oddzielnie — TanStack Query śledzi status mutacji, a nie postęp przesyłania danych w bajtach.

Historie granularności unieważniania danych

Zbyt wąska granularność: zaktualizowano listę, ale zapomniano o szczegółach → strona z danymi szczegółowymi jest przestarzała. Zbyt szeroka granularność: każda kluczowa wartość pod ['menu'] jest ponownie pobierana → ogromny obciążenie systemu. Dobierz granularność tak, aby odpowiadała ekranom, które mogą pokazać niezgodności. W razie wątpliwości unieważnij listę oraz identyfikator szczegółów, które zmieniłeś. Przedrostek „unieważnienie” służy do celowego rozprzestrzeniania efektu unieważnienia na więcej elementów.

Potknięcia przy optymistycznym aktualizowaniu

Zdjęcie stanu musi dokonać głębokiej klonacji wystarczającej struktury, aby przywrócić nawiasowane listy. Tymczasowe identyfikatory klientów nie mogą wyciekać na serwer. Jeśli kilka optymistycznych mutacji zachodzi jednocześnie, operacje cofania mogą się wzajemnie zakłócać — zserializuj interfejs użytkownika dla takich przypadków. Zawsze sprawdzaj dane z serwerem nawet po pomyślnym zakończeniu, ponieważ serwer może znormalizować pola, których nie wysłałeś.

Strict Mode w React i podwójne montowanie

W fazie rozwoju Strict Mode dwukrotnie uruchamia efekty. TanStack Query usuwa duplikaty na podstawie klucza, więc nie powinieneś widzieć dwóch żądań sieciowych dla tego samego klucza w trakcie działania aplikacji. Jeśli tak się dzieje, twój klucz jest niestabilny lub problemy z identyfikatorem queryFn zakłócają mechanizmy usuwania duplikatów. Rejestruj klucze podczas debugowania.

SSR i uwagi dotyczące hydratacji

Dla Next.js i podobnych narzędzi należy odwodnić klient zapytań na serwerze, a następnie nawodnić go po stronie klienta, aby notatnik funkcjonował podczas nawigacji. Należy upewnić się, że funkcje queryFn działają w obu środowiskach, albo użyć funkcji server-prefetch, która uzupełni pamięć cache przed renderowaniem. Różnice w strukturze danych między serwerem a klientem powodują ostrzeżenia związane z procesem nawadniania, które wyglądają jak błędy frameworka, ale w rzeczywistości są wynikiem błędów w załadunku danych do cache.

Porównanie z ręcznie implementowanymi wzorcami SWR

Wiele zespołów ponownie wymyśla podzbiory tej biblioteki: mapy cache, funkcje ponownego pobierania danych, mechanizmy mutacji i ponownej walidacji. TanStack Query standaryzuje te rozwiązania dzięki standardom społeczności oraz narzędziom Devtools. Ręczna implementacja ma sens tylko w przypadku małych aplikacji lub nietypowych środowisk działania. W pozostałych sytuacjach korzyści wynikają z oszczędzenia czasu.

Narzędzia Devtools i możliwości obserwacji

Narzędzia deweloperskie React Query pokazują klucze, stopień przestarzałości danych, obserwatorów oraz status zapytań fetch. Nauč zespół, jak je analizować przed dodawaniem logów do konsoli. W środowisku produkcyjnym usuwaj dane wrażliwe z raportów błędów; gdy wymaga tego ochrona prywatności, rejestruj błędy zapytań podając tylko nazwy kluczy, a nie pełne dane.

Lista antypatronów

Niestabilne klucze; brak procedury unieważniania danych; nieskończona przestarzałość bez synchronizacji zmian; umieszczanie flag interfejsu użytkownika w pamięci serwera; zbyt szerokie unieważnianie danych; aktualizacje optymistyczne bez możliwości cofnięcia; ignorowanie parametru enabled dopóki nie istnieją identyfikatory; używanie operacji mutacji do odczytu danych. Unikaj tych praktyk, aby wszystko funkcjonowało sprawnie.

Podsumowanie dla szybkich czytelników

Kelnerzy przewożą towary. Menedżerowie pamiętają i koordynują działania. Klucze są zapisywane na stronach notatnika. Regulatory świeżości kontrolują ponowne użycie danych. Mutacje służą do zapisywania zmian. Unieważnianie danych i optymizm zapewniają uczciwość notatnika. To właśnie jest TanStack Query w jednym zdaniu – i dlaczego obejmuje Axios zamiast go zastępować.

Dodatkowe ćwiczenia kuchenne do praktyki

Odbuduj małą aplikację: zapytanie listowe, zapytanie szczegółowe, mutacja tworząca z unieważnianiem danych, a następnie optymistyczna operacja tworzenia z wymuszoną ścieżką błędu. Dodaj funkcję wylogowania, która usuwa dane na stronie klienta. Dodaj funkcję wcześniejszego pobierania danych przy nadpisywaniu elementu listy. Pomiierz wywołania sieciowe w Devtools przed i po użyciu wspólnych kluczy. Te ćwiczenia lepiej pomagają zrozumieć bibliotekę niż samo czytanie tabel opisujących API.

Podczas przeglądania propozycji zmian zadawaj pytania: jaki jest klucz? Co to jest staleTime i dlaczego istnieje? Co unieważnia dane po zapisaniu? Czy funkcja pending UI zapobiega podwójnym wysyłkom danych? Jeśli odpowiedzi są jasne, funkcja będzie poprawnie działać nawet przy jednoczesnych operacjach i intensywnym przeglądaniu.

Wzory preładowania, które wydają się natychmiastowe

Przedładowuj dane przy przewijaniu strony, po skupieniu uwagi na karcie przed kliknięciem użytkownika lub po zalogowaniu dla domyślnej zapytania panelu sterowania. Preładowanie uzupełnia pamięć cache bez konieczności uruchamiania obserwatora. Gdy użytkownik przegląda treść, useQuery znajduje już przygotowane dane i pomija etap ładowania szkieletu. Jeśli przedładasz niewłaściwy klucz, zużyjesz zasoby łączności; jeśli przedładasz właściwy klucz, wydajność wzrośnie bez konieczności zmiany kodu queryFn.

Łącz preładowanie z realistycznym wartością staleTime. Przedładowywanie danych, które natychmiast stają się przestarzałe, powoduje natychmiastowe ponowne ładowanie w tle – to nadal lepsze niż start od zera, ale nie jest bezkosztowe. Przedładowuj zapytania kluczowe; pomijaj rzadko używane ekrany ustawień.

Zapytania zależne i kontrola sekwencji wykonywania

Gdy szczegóły wymagają identyfikatora z listy wyboru, użyj bramy z enabled: !!selectedId. Gdy drugie zapytanie potrzebuje danych z pierwszego, łącz je ostrożnie: albo umieść drugi identyfikator wewnątrz pierwszego ID wyniku, albo użyj pojedynczej funkcji queryFn, która zwraca obie struktury, jeśli API to obsługuje. Zapytania sekwencyjne pogarszają czas odpowiedzi; zaleca się zapytania równoległe z wspólnymi nagłówkami autoryzacji, gdy to możliwe.

Tryb Suspense zmienia sposób kompozycji granic ładowania. Jeśli zespół używa Suspense, dostosuj granice błędów i upewnij się, że błędy zapytań są rzucane zgodnie z oczekiwaniami. Mieszanie Suspense z klasycznymi flagami ładowania myli recenzentów — wybierz jeden styl na drzewo tras.

Paginacja, zapytania nieskończone i strony w pamięci cache

Strony listy często używają parametrów strony w klawiszowaniu: ['orders', { page, pageSize, status }]. Zmiana strony tworzy nowy wpis w pamięci cache; zachowaj poprzednie dane za pomocą placeholderData: keepPreviousData (lub odpowiednika w aktualnej API), aby tabela nie wyświetlała się pusta. Zapytania nieskończone dodają strony; unikaj nieostrożnego unieważniania wpisów, aby przypadkowo nie usunąć pozycji przewijania. Gdy mutacja edytuje jedną wiersz, zaktualizuj odpowiedni wpis strony lub unieważnij całą listę w zależności od wrażliwości na kolejność sortowania.

Odbudowa błędów i interfejs ponownej próby

Standardowe próby ponownego wysłania pomagają w radzeniu sobie z niestabilnymi sieciami mobilnymi. W przypadku błędów 401/403 wyłącz próby ponownego wysłania i skieruj użytkownika na ekran logowania. W przypadku błędu 404 przy wyświetlaniu szczegółów zadziałaj szybko. Dla zaawansowanych użytkowników wyświetl w oknach wsparcia wartości failureCount oraz failureReason. Słuchacze globalnego QueryCache mogą wyświetlać komunikaty o błędzie raz na klucz, a nie raz na obserwatora – w ten sposób uniknie się nadmiernego wyświetlania komunikatów, gdy pięć komponentów korzysta z tej samej nieudanej zapytania.

Strategie testowania

W testach jednostkowych użyj nowego obiektu QueryClient z ustawieniem retry: false oraz krótkiego procesu zbierania śmieci. Zaimituuj funkcję queryFn lub użyj narzędzia MSW. Sprawdź stany ładowania, sukcesu i błędu. W przypadku mutacji upewnij się, że została wywołana funkcja invalidateQueries z oczekiwanym kluczem. Testy integracyjne powinny weryfikować, że dwa komponenty korzystające z tego samego klucza nie dokonują podwójnego pobierania danych. Niestabilne testy często wynikają z pozostałości w pamięci cache między poszczególnymi testami – twórz nowy obiekt klienta dla każdego testu.

Wersjonowanie i zmiany w API

Przejście z TanStack Query v4 na v5 spowodowało zmianę nazw niektórych opcji oraz modyfikację domyślnych ustawień. Podczas aktualizacji należy przeczytać przewodnik migracyjny, zaktualizować pakiet Devtools oraz ponownie sprawdzić użycie keepPreviousData / placeholderData. Zapisz wersje w plikach lockfile. Zmiany w strukturze kluczy zapytań traktuj jako problematyczne – stare, przetworzone kody cache mogą nie pasować do nowych kluczy po wdrożeniu; zaakceptuj jednorazowe użycie chłodnego cache lub zmodyfikuj prefiks klucza.

Uwagi z incydentów w produkcji

Jedna z drużyn zaobserwowała duplikaty zapytań POST, ponieważ przycisk wysyłania pozostawał aktywny, gdy na innej instancji mutacji wartość isPending była prawdziwa. Inna drużyna błędnie usunęła całą pamięć cache po wylogowaniu, tworząc nowego klienta bez usunięcia starej referencji dostawcy. Trzecia drużyna zakodowała obiekty użytkowników w kluczach, co doprowadziło do problemów z współdzieleniem struktury danych. Zapisz te historie w dokumentacji wprowadzającej, aby nowi pracownicy mogli się z nimi zapoznać bez konieczności ponownego odkrywania ich problemów.

Zdokumentuj domyślne ustawienia swojego systemu: domyślną wartość staleTime, te zapytania, które są dostępne tylko dla konkretnego użytkownika, sposób usuwania stanu po wylogowaniu oraz warunki, w których dozwolone są optymistyczne aktualizacje. Spójność jest ważniejsza od pomysłowości.

Zapiski z incydentów w produkcji

Jedna z drużyn zaobserwowała duplikaty zapytań POST, ponieważ przycisk wysyłania pozostawał aktywny, gdy na innej instancji mutacji wartość isPending była prawdziwa. Inna drużyna błędnie usunęła całą pamięć cache po wylogowaniu, tworząc nowego klienta bez usunięcia starej referencji dostawcy. Trzecia drużyna zakodowała obiekty użytkowników w kluczach, co doprowadziło do problemów z współdzieleniem struktury danych. Zapisz te historie w dokumentacji wprowadzającej, aby nowi pracownicy mogli się z nimi zapoznać bez konieczności ponownego odkrywania ich problemów.

Zdokumentuj domyślne ustawienia swojego systemu: domyślną wartość staleTime, te zapytania, które są dostępne tylko dla konkretnego użytkownika, sposób usuwania stanu po wylogowaniu oraz warunki, w których dozwolone są optymistyczne aktualizacje. Spójność jest ważniejsza od pomysłowości.

Zapiski z incydentów w produkcji

Jedna z drużyn zaobserwowała duplikaty zapytań POST, ponieważ przycisk wysyłania pozostawał aktywny, gdy na innej instancji mutacji wartość isPending była prawdziwa. Inna drużyna błędnie usunęła całą pamięć cache po wylogowaniu, tworząc nowego klienta bez usunięcia starej referencji dostawcy. Trzecia drużyna zakodowała obiekty użytkowników w kluczach, co doprowadziło do problemów z współdzieleniem struktury danych. Zapisz te historie w dokumentacji wprowadzającej, aby nowi pracownicy mogli się z nimi zapoznać bez konieczności ponownego odkrywania ich problemów.

Zdokumentuj domyślne ustawienia swojego systemu: domyślną wartość staleTime, te zapytania, które są dostępne tylko dla konkretnego użytkownika, sposób usuwania stanu po wylogowaniu oraz warunki, w których dozwolone są optymistyczne aktualizacje. Spójność jest ważniejsza od pomysłowości.

Literatura pokrewna

• TanStack Query dla React: Caching, Refetching i Mutacje — Zastąp standardowy kod useEffect fetch funkcjami TanStack Query: klucze zapytań, staleTime, gcTime, operacje mutacji oraz okoliczności, gdy biblioteka jest niepotrzebna.
• TanStack Query w 2026 roku: adapter Lit, Solid v6 beta oraz stabilne klucze zapytań — Co nowego w adapterach TanStack Query – obsługa Lit, Solid Query v6 beta, ulepszone narzędzia deweloperskie oraz typowanie persister – oraz dlaczego stabilne klucze zapytań wciąż są ważne.