re:re:actable
Урок 094 минуты чтения

TanStack Query

На этой странице
Кратко

TanStack Query управляет серверным состоянием: загрузкой, кешем, свежестью, повторами и синхронизацией данных с интерфейсом.

Вопрос

Что решает TanStack Query и чем серверное состояние отличается от локального?

Основная идея

Открытое меню принадлежит интерфейсу: приложение полностью контролирует это значение. Каталог книг принадлежит серверу: его могут изменить другие пользователи, он может устареть, а получение требует сети. Поэтому хранить оба вида данных одинаковым способом не всегда удобно.

TanStack Query связывает ключ запроса с асинхронной функцией. Компоненты с одинаковым ключом наблюдают общую запись кеша. Библиотека знает, появились ли данные, выполняется ли фоновый запрос, нужно ли повторить неуспешную загрузку и когда устаревшую запись проверить заново.

Библиотека не заменяет API-клиент: queryFn всё ещё должна правильно отправить запрос, проверить статус и вернуть данные либо выбросить ошибку. Мутации описывают запись на сервер, но затронутые ключи кеша обычно нужно обновлять или инвалидировать явно.

Пример

Пример для клиентского React-приложения с поддержкой JSX. API в примере возвращает JSON; его адрес замените на адрес своего сервера.

import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query';
 
const client = new QueryClient();
async function getBooks({ signal }) {
  const response = await fetch('/api/books', { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}
function Books() {
  const query = useQuery({
    queryKey: ['books'],
    queryFn: getBooks,
    staleTime: 60_000,
  });
  if (query.isPending) return <p role="status">Загрузка...</p>;
  if (query.isError) return <p role="alert">Не удалось получить книги</p>;
  return <>
    {query.isFetching && <small>Обновляем...</small>}
    <ul>{query.data.map(book => <li key={book.id}>{book.title}</li>)}</ul>
  </>;
}
export default function App() {
  return <QueryClientProvider client={client}><Books /></QueryClientProvider>;
}

Пример использует v5: QueryClientProvider даёт компонентам доступ к клиенту, useQuery наблюдает books, а signal позволяет отменять поддерживающий отмену запрос.

Что библиотека делает вместо тебя

ЗадачаВручную (useEffect + useState)TanStack Query
Состояния загрузки и ошибкиСвои флагиisPending, isError, isFetching
Два компонента с одинаковыми даннымиДва запроса или подъём stateОдин запрос по ключу, общий кэш
Гонка при смене параметровAbortController вручнуюКлюч + signal
Повтор при сбое сетиПисать самомуretry (по умолчанию 3 раза)
Обновление при возврате на вкладкуПодписка на visibilitychangerefetchOnWindowFocus
Данные после мутацииРучная перезагрузкаinvalidateQueries
Пагинация, бесконечная лентаСложный кодplaceholderData, useInfiniteQuery
SSR—prefetchQuery + HydrationBoundary

Жизненный цикл записи кэша

запрос ──▶ fresh ──(staleTime)──▶ stale ──(все подписчики ушли)──▶ inactive ──(gcTime)──▶ удалена
            │                       │
   новые useQuery берут        при монтировании/фокусе окна:
   из кэша без запроса         показать кэш + обновить в фоне

По умолчанию staleTime: 0 (данные сразу считаются устаревшими), gcTime: 5 минут.

Мутация и инвалидация

import { useMutation, useQueryClient } from "@tanstack/react-query";
 
function AddBook() {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: (title) =>
      fetch("/api/books", { method: "POST", body: JSON.stringify({ title }), headers: { "Content-Type": "application/json" } })
        .then((r) => { if (!r.ok) throw new Error("Не удалось сохранить"); return r.json(); }),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["books"] }), // список перезагрузится
  });
 
  return (
    <form onSubmit={(e) => { e.preventDefault(); mutation.mutate(new FormData(e.currentTarget).get("title")); }}>
      <input name="title" aria-label="Название" />
      <button disabled={mutation.isPending}>{mutation.isPending ? "Сохраняем…" : "Добавить"}</button>
      {mutation.isError && <p role="alert">{mutation.error.message}</p>}
    </form>
  );
}

Ключи и queryOptions

import { queryOptions } from "@tanstack/react-query";
 
export const bookQuery = (id) => queryOptions({
  queryKey: ["books", id],         // все параметры — в ключе
  queryFn: ({ signal }) => getBook(id, signal),
  staleTime: 5 * 60_000,
});
 
useQuery(bookQuery(id));                       // в компоненте
queryClient.prefetchQuery(bookQuery(id));      // prefetch по наведению
queryClient.invalidateQueries({ queryKey: ["books"] }); // инвалидирует ["books"] и ["books", id]

Что важно помнить

  • queryKey должен содержать все переменные, от которых зависит результат.
  • Стабильный QueryClient создают один раз для клиентского приложения; при SSR — отдельно для запроса.
  • isFetching может быть true при уже показанных данных. Не скрывайте весь экран при любом refetch.
  • Меню, незавершённый текст поля и другие локальные детали обычно остаются в React state.

Мини-шпаргалка

Query → чтение. Mutation → запись. Query key → кеш. Инвалидация → повторная синхронизация.

Документация

TanStack Query: запросы.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам