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 раза) |
| Обновление при возврате на вкладку | Подписка на visibilitychange | refetchOnWindowFocus |
| Данные после мутации | Ручная перезагрузка | 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 → кеш. Инвалидация → повторная синхронизация.