Strona główna / Artykuły

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.

Wydawca: REACTAPP.TOP7 min czytania1663 słów

Ź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ść:

  1. TanStack Query zarządza danymi serwera.
  2. Czytanie danych odbywa się za pomocą useQuery.
  3. Pobrane dane trafiają do cache zapytań.
  4. staleTime określa, kiedy dane z cache są uważane za aktualne.
  5. gcTime decyduje, jak długo pozostają nieużywane wpisy w cache.
  6. Proces ponownego pobierania danych określa moment, w którym dane są ładowane ponownie.
  7. Tworzenie, aktualizacja i usuwanie danych odbywa się za pośrednictwem useMutation.
  8. QueryClient koordynuje zapytania, mutacje oraz cache.
  9. 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