Для чего нужны queryKey и queryFn в TanStack Query и почему параметры, влияющие на запрос, должны входить в queryKey?

TanStack Query (ранее React Query) управляет серверным состоянием в React-приложениях. Два ключевых параметра хука useQuery — это queryKey и queryFn. Они работают в паре: ключ определяет, где в кэше хранятся данные, а функция — как эти данные получить.

Роль queryKey

queryKey — это массив, который уникально идентифицирует запрос. Он используется как ключ в кэше, для дедупликации одновременных запросов, для инвалидации и для подписки на изменения. Ключ должен быть сериализуемым (строки, числа, объекты, массивы).

Роль queryFn

queryFn — это асинхронная функция, которая возвращает промис с данными. Она получает контекст с queryKey, что позволяет строить запрос на основе ключа.

Почему параметры должны входить в queryKey

Если параметр влияет на результат запроса, но не входит в ключ, TanStack Query будет считать, что данные те же самые, и вернёт устаревший кэш. Например, при смене userId без изменения ключа пользователь увидит данные предыдущего пользователя.

// Правильно: userId входит в queryKey
function useUser(userId) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
  });
}

// Неправильно: ключ не зависит от userId
function useUserBad(userId) {
  return useQuery({
    queryKey: ['user'],
    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
  });
}

Практические следствия

• Кэш разделяется по ключу: разные ключи — разные записи.
• Инвалидация работает по префиксу ключа: queryClient.invalidateQueries({ queryKey: ['user'] }) сбросит все запросы пользователей.
• Дедупликация: одновременные вызовы с одинаковым ключом выполнят один запрос.
• Автоматический рефетч при изменении ключа.

Итог: включайте в queryKey все параметры, от которых зависит результат запроса — это гарантирует корректное кэширование, инвалидацию и отсутствие багов с устаревшими данными.