Освоение React Query: Переход от ручного управления данными к эффективному кэшированию и синхронизации

Категория: Статьи • 30 June 2025 • 6 мин чтения

Код комментирован: Я прекращаю использовать state и useEffect для каждой операции с данными в моём приложении.

Если вы работаете с React и периодически обновляетесь, скорее всего вы столкнулись с огромным количеством кода, посвящённого обработке асинхронных операций: useState, useEffect, условные рендеры загрузки и ошибок, ручная синхронизация обновлений. Когда я впервые перешёл с Redux Thunk на React Query, количество кода в проекте сократилось примерно на 30%. Давайте разберёмся почему.

Проблема ручного управления данными

Представим типичный сценарий: компонент для отображения списка пользователей. Классическая реализация:

jsx
const UserList = () => {
  const [users, setUsers] = useState([]);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchUsers = async () => {
      setIsLoading(true);
      try {
        const response = await fetch('/api/users');
        const data = await response.json();
        setUsers(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setIsLoading(false);
      }
    };

    fetchUsers();
  }, []);

  if (isLoading) return <Spinner />;
  if (error) return <Error message={error} />;

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
};

Проблемы этого подхода:

  • Повторяющийся boilerplate для каждого запроса
  • Отсутствие кэширования между компонентами
  • Нет механизма автоматического обновления
  • Неоптимальная обработка параллельных запросов
  • Трудности с инвалидацией кэша

React Query решает эти проблемы с помощью декларативного подхода к обработке данных сервера.

Основные концепции React Query

Запросы (Queries)

Ключевая абстракция библиотеки — использование уникальных ключей запросов. Перепишем наш пример:

jsx
import { useQuery } from '@tanstack/react-query';

const fetchUsers = async () => {
  const response = await fetch('/api/users');
  return response.json();
};

const UserList = () => {
  const { 
    data: users, 
    isLoading, 
    isError, 
    error 
  } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers
  });

  if (isLoading) return <Spinner />;
  if (isError) return <Error message={error.message} />;

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
};

Какие преимущества мы получили кроме сокращения кода?

  • Автоматическое кэширование результатов с использованием ключа ['users']
  • Фоновая ревалидация при переходе между вкладками браузера
  • Сборка параллельных запросов в один реальный запрос
  • Автоматический повтор запросов при ошибках (настраиваемый)

Мутации (Mutations)

Для операций, изменяющих данные, используем useMutation. Рассмотрим создание нового пользователя:

jsx
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

const createUser = async (userData) => {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(userData)
  });
  return response.json();
};

const AddUserForm = () => {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: createUser,
    onSuccess: () => {
      // Инвалидируем запрос с ключом ['users'] для повторной загрузки данных
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
    onError: (error) => {
      console.error('Failed to create user:', error);
    }
  });

  const handleSubmit = (event) => {
    event.preventDefault();
    const formData = new FormData(event.target);
    const userData = Object.fromEntries(formData);
    mutation.mutate(userData);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" placeholder="Name" required />
      <input name="email" placeholder="Email" required />
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Creating...' : 'Create User'}
      </button>
      {mutation.isError && <div>Error: {mutation.error.message}</div>}
    </form>
  );
};

Критически важный элемент здесь — invalidateQueries. Это сообщает React Query что данные по ключу ['users'] устарели и должны быть обновлены при следующем обращении. Альтернативный подход с оптимистичным обновлением:

jsx
mutation.mutate(newUser, {
  optimisticData: (currentUsers) => [...currentUsers, newUser],
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['users'] });
  }
});

Расширенное использование

Преимущества React Query

  1. Автоматическое кэширование данных
    Запросы кэшируются с использованием ключей, и при повторном вызове с тем же ключом в другом компоненте данные поступают из кэша, а не с сервера.

  2. Дедупликация параллельных запросов
    Если два компонента используют одинаковый запрос одновременно, запросит данные только первый, второй получит те же данные из кэша.

  3. Интеллектуальное обновление данных
    Данные обновляются при возвращении на страницу, когда окно получает фокус, таймауте кэша или с помощью исторических методов для комплексных сценариев.

  4. Автоматическое повторение
    По умолчанию React Query выполняет 3 попытки с экспоненциальными задержками при сетевых ошибках.

  5. Контекстная загрузка/ошибка
    Возможность управлять состоянием запроса на уровне компонента.

Оптимальные практики

  1. Контроль времени кэширования
    Подберите параметры актуальности данных в зависимости от бизнес-логики:

    jsx
    useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  staleTime: 5 * 60 * 1000, // 5 минут
  cacheTime: 30 * 60 * 1000 // 30 минут - время жизни в кэше
});

  2. Использование ключей запросов с зависимостями
    Ключи запросов могут динамически изменяться на основе зависимостей:

    jsx
    const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUserById(userId),
  enabled: !!userId // запрос выполняется только при наличии userId
});

  3. Пакетная инвалидация
    Инвалидация нескольких запросов одновременно повышает эффективность:

    jsx
    queryClient.invalidateQueries({
  predicate: query => 
    query.queryKey[0] === 'projects' || 
    query.queryKey[0] === 'users'
});

  4. Продвинутые паттерны запросов
    Для пагинации или бесконечной прокрутки используйте специализированные хуки:

    jsx
    const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
  queryKey: ['projects'],
  queryFn: ({ pageParam = 0 }) => 
    fetchProjects(pageParam),
  getNextPageParam: (lastPage) => lastPage.nextPage,
});

Интеграция с TypeScript

React Query с высокой точностью типизирует возвращаемые данные с помощью обобщений:

typescript
interface User {
  id: string;
  name: string;
  email: string;
}

const { data } = useQuery<User[]>({
  queryKey: ['users'],
  queryFn: () => fetchUsers() as Promise<User[]>
});

// data теперь автоматически типизируется как User[] | undefined

Для мутаций:

typescript
const addUserMutation = useMutation<void, Error, UserData>({
  mutationFn: (newUser) => api.createUser(newUser),
});

Когда не стоит использовать React Query

Эта библиотека не является универсальной заменой менеджеров состояний. Она отлично решает задачи работы с серверными состояниями. Для управления локальными состояниями продолжаем использовать useState, useReducer или другие решения.

Рекомендуется сочетать с контекстом для разделения зон ответственности: React Query заботится о данных с сервера, контекст - о локальных компонентных состояниях.

Производительность в реальных приложениях: На крупном проекте с более чем 50k активных пользователей использование React Query сократило сетевой трафик на 38% и уменьшило количество действий в Redux на 75%. Клиентская логика тривиально проста, фрагменты рапортов об ошибках выдаются на 45% реже.

Рекомендации к интеграции в существующие проекты

  1. Не требуется "революционная" миграция. Начните с добавления React Query для недавно разрабатываемых функций.

  2. Для ускоренного перехода переносим существующие запросы без регистрации и смс:

    • Изолируем функции запросов
    • Заменяем useState/useEffect на useQuery
    • Обработку ошибок переносим на интегрированный механизм

  3. Настройте централизованный клиент с общепринятыми конфигурациями:

    jsx
    const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,
      retry: (failureCount, error) => 
        failureCount < 3 && error.status !== 401,
    },
  },
});

<QueryClientProvider client={queryClient}>
  <App />
</QueryClientProvider>

Итог

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

Советую экспериментировать на проектах с такой архитектурой — с вероятностью эффективность занимаяемого времени на разработку упадет на 25%, сопровождать код станет менее болезненно, а пользовательский опыт заметно улучшится благодаря умелой оптимизации подступе к данным.