2. Query: основы

Что такое TanStack Query?

TanStack Query — библиотека для управления серверным состоянием в React-приложениях. В отличие от Redux или Zustand (которые управляют клиентским состоянием), TanStack Query решает задачи, специфичные для работы с сервером: кэширование, фоновое обновление, синхронизация, дедупликация запросов.

Серверное vs Клиентское состояние

Клиентское состояние — данные, которые живут только в браузере:

Открыт/закрыт модал
Выбранная вкладка
Значения формы (до отправки)

Серверное состояние — данные, хранящиеся на сервере:

Список пользователей из базы данных
Профиль текущего пользователя
Настройки из API

Серверное состояние имеет уникальные проблемы: оно может устареть, другие пользователи могут его изменить, его нужно синхронизировать. TanStack Query решает всё это автоматически.

QueryClient

QueryClient — это центральный объект, который управляет кэшем и конфигурацией. Создаётся один раз на приложение:

import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,    // 5 минут до устаревания
      gcTime: 1000 * 60 * 10,      // 10 минут до удаления из кэша
      retry: 3,                     // 3 попытки при ошибке
      refetchOnWindowFocus: true,  // Обновление при фокусе окна
    },
  },
})

QueryClientProvider

Чтобы хуки TanStack Query работали, нужно обернуть приложение в QueryClientProvider:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MyApp />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

DevTools

@tanstack/react-query-devtools — незаменимый инструмент для отладки. Показывает:

Все активные и неактивные запросы
Статус каждого запроса (loading, error, success, stale)
Данные в кэше
Конфигурацию запроса

Устанавливается отдельно: npm install @tanstack/react-query-devtools

Ключевые концепции

Концепция	Описание
`queryKey`	Уникальный ключ для идентификации запроса в кэше
`queryFn`	Функция, которая получает данные (должна возвращать Promise)
`staleTime`	Время, в течение которого данные считаются свежими
`gcTime`	Время хранения неиспользуемых данных в кэше
`enabled`	Флаг активации запроса

Установка

npm install @tanstack/react-query
npm install @tanstack/react-query-devtools  # для разработки