Podstawy TanStack Query: zapytania, cache, mutacje i unieważnianie
Dowiedz się, jak useQuery, queryKey, staleTime, gcTime, useMutation oraz invalidation współpracują ze sobą, aby zarządzać stanem serwera w React bez konieczności pisania ręcznych efektów fetch.
Źródła: Started with React Query
TanStack Query, wcześniej React Query, zarządza danymi pochodzącymi z serwera. Nazwa uległa zmianie, ponieważ biblioteka ta teraz funkcjonuje również poza Reactem, w Svelte, Vue i Solid. Krótko mówiąc, jest to menedżer stanu służący do zarządzania stanem serwera.
Stan serwera versus stan klienta
Stan serwera to dane pochodzące z backendu lub zewnętrznej API: użytkownicy, produkty, wpisy, komentarze. Znajdują się one poza aplikacją, więc aplikacja nie ma nad nimi pełnej kontroli. Mogą ulegać zmianie bez wiedzy aplikacji, mogą stać się przestarzałe i można do nich dotrzeć jedynie za pomocą żądania asynchronicznego.
Stan klienta należy do samej aplikacji. Na przykład fakt, czy modala jest otwarta, istnieje tylko w przeglądarce, jak w const [isModalOpen, setIsModalOpen] = useState(false). Zustand, Redux i Jotai to typowe narzędzia do zarządzania takim rodzajem stanu.
Metoda ręczna i jej koszt
Bez biblioteki pobieranie użytkowników zazwyczaj rozpoczyna się od trzech stanów.
const [users, setUsers] = useState([])
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)
Następnie efekt zajmuje się ładowaniem.
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()
Użytkownicy są pobierani, przechowywani w stanie aplikacji, włączany jest flaga ładowania, a błędy są łapane. W miarę rozwoju aplikacji ten wzorzec powtarza się wszędzie, a każda jego wersja musi obsługiwać stany ładowania i błędów, cacheowanie, ponowne pobieranie danych, ich pobieranie w tle, synchronizację oraz próby ponowne. Gdy takie rozwiązanie stosuje się w dużym kodzie, rezultatem jest skomplikowany kod.
To samo z zapytaniem
Jedyny hook zastępuje całą rutynę początkową.
function Users() {
const {
data,
isLoading,
error
} = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Komponenta następnie rozgałęzia się w zależności od statusu.
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 zarządza infrastrukturą związaną z danymi serwera. Jego główną zaletą w porównaniu z useEffect w połączeniu z useState jest wbudowane cacheowanie. Gdy dane przyjdą, trafiają do cache’u i mogą być ponownie wykorzystane później, co zmniejsza liczbę niepotrzebnych żądań do API. Stany ładowania, sukcesu i błędu są automatycznie śledzone, więc nie trzeba ręcznie pisać ani utrzymywać żadnej logiki.
Ustawianie
Zainstaluj pakiet.
npm install @tanstack/react-query
Następnie utwórz QueryClient i przekaż go aplikacji.
const queryClient = new QueryClient();
root.render(
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
);
Czytanie danych za pomocą useQuery
Hook useQuery obsługuje operacje odczytu, czyli wszystko, co pobiera dane z serwera. Podstawowe wywołanie wygląda tak:
const { data,
isPending,
error } = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Wymaga obiektu opcji, przy czym najważniejsze są dwie właściwości: queryFn i queryKey.
queryFn to funkcja, do której odwołuje się TanStack Query w celu pobrania danych. Zwraca dane bezpośrednio lub jako Promise, a w przypadku błędu powinien rzucić błąd lub zwrócić odrzucony Promise.
async function fetchUsers() {
const res = await fetch("/api/users")
if (!res.ok) {
throw new Error("Failed to fetch users")
}
return res.json()
}
Następnie podłącza się do haczyka:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
queryKey w sposób unikalny identyfikuje zapytanie oraz jego zapisane w pamięci cache dane. Zmienne używane przez queryFn powinny zazwyczaj znaleźć się w tym kluczu. Na przykład ["users"] może oznaczać wszystkich użytkowników, ["todo", 1] zadanie o ID 1, a ["products", "laptops"] laptopy.
Hook zwraca obiekt zawierający stan zapytania (ładowanie, błąd lub sukces), dane oraz funkcje do ponownego pobrania.
Jak pomaga cache
Tutaj właśnie biblioteka pokazuje swoją wartość. Pobrane dane są automatycznie przechowywane i ponownie wykorzystywane, aby uniknąć zbędnych wywołań, co poprawia wydajność i skraca czas wyświetlania wyników.
Komponent A żąda ["users"]. TanStack Query pobiera i przechowuje ten wynik w pamięci cache. Później komponent B również żąda tej samej klucza, a biblioteka zauważa, że dane są już w cache. Zamiast aby każdy komponent przechowywał własną kopię, TanStack Query zarządza jedną wspólną kopią stanu serwera. To jeden z największych różnic pomiędzy zwykłym fetch() a tą biblioteką.
staleTime i gcTime
staleTime odpowiada na jedno pytanie: jak długo dane te powinny być uważane za świeże?
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60,000 // 60 seconds
})
Dzięki temu ustawieniu dane są aktualne przez pierwsze 60 sekund. Po minucie stają się przestarzałe, co umożliwia uruchomienie ponownego pobrania i tła aktualizacji. Przestarzałe nie oznacza usunięte, chociaż dane mogą być nieaktualne. Gdy staną się przestarzałe, można je ponownie pobrać, gdy coś to wywoła, na przykład gdy okno ponownie zyska uwagę użytkownika lub komponent zostanie załadowany.
Ignorowanie stanu przestarzałości powoduje niepotrzebne żądania, gdy użytkownicy wracają na stronę.
User visits page
↓
Fetch users
↓
User navigates away
↓
User comes back
↓
Fetch users again
Jeśli nic się nie zmieni, druga prośba jest bezużyteczna. Dłuższy okres ważności unika tego problemu:
staleTime: 5 * 60 * 1000
To oznacza, że dane są uznawane za świeże przez pięć minut. Pamiętaj, że staleTime kontroluje świeżość danych i nie jest interwałem ponownego pobierania.
Istnieje również gcTime – czas zbierania śmieci. Określa on, jak długo nieaktywne, nieweryfikowane dane w pamięci podręcznej pozostają w pamięci, zanim zostaną usunięte.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
gcTime: 60000
})
Podsumowując, staleTime określa, jak długo dane pozostają aktualne, natomiast gcTime wskazuje, jak długo pozostają nieużywane wpisy cache. Rozwiązują one różne problemy.
Odświeżanie danych
Zastarzałe zapytania mogą zostać ponownie wyświetlone, gdy komponent zostanie załadowany, okno ponownie uzyska fokus lub sieć się połączy, a te zachowania są konfigurowalne. Dostępne jest również ręczne odświeżanie danych.
const { refetch } = useQuery(...)
refetch()
Możliwe jest również przeprowadzanie ankiet.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchInterval: 30,000
})
Zapytanie jest ponownie wysyłane mniej więcej co 30 sekund, dopóki jest aktywne. To ponowne wysyłanie zastępuje przestarzałe dane nowymi danymi z serwera.
Zmiana danych za pomocą useMutation
Do tej pory wszystko dotyczyło odczytywania danych. Tworzenie, aktualizowanie lub usuwanie (POST, PUT, PATCH, DELETE) odbywa się za pośrednictwem hooka useMutation. Jako przykład przedstawiamy tutaj tworzenie użytkownika. Najpierw przychodzi funkcja mutacji.
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();
}
Następnie jest przekazywane do useMutation.
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;
Kliknięcie przycisku uruchamia mutację za pomocą mutation.mutate().
Button click
↓
mutation.mutate(user)
↓
createUser(user)
↓
POST request
↓
Server
Zauważ, że createUser() nigdy nie jest wywoływany bezpośrednio. Komponent wywołuje mutation.mutate(), a TanStack Query uruchamia tę funkcję.
Mutacje, podobnie jak zapytania, posiadają flagi stanu.
const {
mutate,
isPending,
isSuccess,
isError,
error,
data,
} = useMutation({
mutationFn: createUser,
});
Kierują interfejsem użytkownika.
<button
onClick={() => mutate({ userName: "delfina ghimire" })}
disabled={isPending}
>
{isPending ? "Creating..." : "Create user"}
</button>
Gdy zostanie wywołana funkcja mutate(), mutacja przechodzi przez kilka stanów:
isPending: mutacja jest w trakcie wykonywania.isSuccess: zakończyła się pomyślnie.isError: nie udała się.data: wynik pomyślnie zakończonej mutacji.error: szczegóły w przypadku niepowodzenia.mutate: funkcja inicjująca, która przyjmuje zmienne dla funkcji mutacji.
Dzięki temu udzielanie informacji zwrotnych podczas operacji tworzenia, aktualizacji lub usuwania jest proste.
QueryClient i unieważnianie
QueryClient to kluczowy obiekt, który zarządza pamięcią cache i koordynuje zachowanie zapytań oraz mutacji. Został utworzony wcześniej za pomocą new QueryClient(), a wewnątrz komponentu dostępny jest poprzez useQueryClient(). Umożliwia on unieważnianie zapytań, aktualizację danych z pamięci cache, usuwanie tych danych, resetowanie zapytań oraz ich wcześniejsze pobieranie. Typowym przykładem wywołania jest queryClient.invalidateQueries({ queryKey: ["users"] }).
Unieważnianie zapytań ma największe znaczenie po mutacjach. Gdy mutacja zmienia dane na serwerze, powiązane z nią zapytania mogą zawierać przestarzałe wyniki, a ich unieważnienie oznacza, że stają się nieskuteczne i mogą zostać ponownie pobrane. Załóżmy, że pamięć cache zawiera dwóch użytkowników:
[
{ id: 1, userName: "delfina ghimire" },
{ id: 2, userName: "spiderman ghimire" },
]
Następnie tworzony jest nowy użytkownik.
mutation.mutate({
userName: "ironman ghimire",
});
Server ma teraz trzech użytkowników, ale cache nadal pokazuje dwoje. Zapytanie ["users"] można oznaczyć jako przestarzałe. Najpierw uzyskuje się klienta:
const queryClient = useQueryClient();
Następnie mutacja zostaje unieważniona po pomyślnym wykonaniu.
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
});
},
});
Przepływ przebiega w następujący sposób:
Create Users (Mutation)
↓
Server data changes
↓
Invalidate ["users"]
↓
Query becomes stale
↓
Refetch
↓
UI gets fresh data
Aby jasno to rozróżnić: invalidate oznacza, że dane z pamięci cache są uznawane za przestarzałe, natomiast refetch natychmiast ładuje je ponownie. Unieważnienie aktywnej zapytania zazwyczaj powoduje automatyczne ponowne pobranie danych.
Cały obraz
Wszystkie elementy łączą się w jedną całość:
- TanStack Query zarządza danymi serwera.
- Czytanie danych odbywa się za pomocą
useQuery. - Pobrane dane trafiają do cache zapytań.
staleTimeokreśla, kiedy dane z cache są uważane za aktualne.gcTimedecyduje, jak długo pozostają nieużywane wpisy w cache.- Proces ponownego pobierania danych określa moment, w którym dane są ładowane ponownie.
- Tworzenie, aktualizacja i usuwanie danych odbywa się za pośrednictwem
useMutation. - QueryClient koordynuje zapytania, mutacje oraz cache.
- Unieważnienie zapytania sygnalizuje, że dane z cache są przestarzałe.
Gdy te zależności są jasne, znacznie łatwiej jest rozumieć strukturę biblioteki.
Literatura pokrewna
- Od prototypu do produkcji: AI-agenci z LangChain, LangGraph i Azure — wyszukiwanie hybrydowe, buforowanie embeddingów, routowanie w LangGraph, mechanizmy ochronne, testy regresji na zbiorach danych „złotych” oraz śledzenie działania agenta do dokumentów podatkowych, wraz z przedstawionymi wynikami.
- Przestań przekazywać AI-agentom wyobrażenia: proces oparty na specyfikacjach dla małych zespołów — jak mały zespół wprowadza w użycie AI-agenty: pisane specyfikacje, wzajemna weryfikacja przez dwie rodziny modeli, testy w czasie rzeczywistym, łączenie rozwiązań przez ludzi oraz orkiestrator, który pamięta wszystko.