4. Query Functions и работа с API

queryFn — асинхронная функция, которая фактически получает данные. В v5 она всегда вызывается с объектом контекста:

type QueryFunctionContext<TQueryKey = QueryKey, TPageParam = never> = {
  queryKey: TQueryKey;
  signal: AbortSignal;
  meta: Record<string, unknown> | undefined;
  pageParam?: TPageParam;
};

Базовый пример

async function fetchTodos({ queryKey, signal }: QueryFunctionContext) {
  const [_key, { userId }] = queryKey;
  const res = await fetch(`/api/users/${userId}/todos`, { signal });
  if (!res.ok) throw new Error('Не удалось загрузить задачи');
  return res.json() as Promise<Todo[]>;
}

useQuery({
  queryKey: ['todos', { userId }],
  queryFn: fetchTodos,
});

Лайфхаки

Всегда деструктурируйте queryKey внутри queryFn, чтобы не терять типы.
Возвращайте «сырые» данные, а форматирование/селекторы выносите в select, иначе кеш будет раздуваться.
Добавляйте meta: { requestId: crypto.randomUUID() }, если хотите трекать запросы в логах.

Обработка отмены (`AbortSignal`)

TanStack Query отменяет активный запрос, если:

компонент размонтировался до завершения;
ключ изменился;
был инициирован новый запрос с fetchType: 'replace'.

Поэтому важно прокидывать signal во все fetch/axios. Например, для Axios:

import axios from 'axios';

const fetchUser = async ({ signal, queryKey }) => {
  const [, id] = queryKey;
  const { data } = await axios.get(`/api/users/${id}`, { signal });
  return data;
};

Если вы вручную бросаете исключение при отмене, используйте throw new DOMException('Aborted', 'AbortError'). Это позволит Query не считать отмену ошибкой и не запускать retry.

В v5 также можно установить networkMode: 'offlineFirst' и получать signal даже когда запрос «медленно» прогружается: Query отменит запрос при переходе оффлайн/онлайн автоматически.

Доступ к `meta`

meta удобно использовать для трассировки или выбора клиента.

const githubQuery = (username: string) => ({
  queryKey: ['github', username],
  queryFn: ({ meta }) => meta!.client.get(`/users/${username}`),
  meta: { client: githubClient },
});

Дополнительно через meta можно прокинуть:

suspenseKey — для объединения нескольких запросов в useSuspenseQuery.
cacheBuster или tenantId, если один и тот же queryFn работает в разных контекстах.
кастомный логгер (meta.logger?.info(...)) без глобальных синглтонов.

Паттерн «контекста запроса»

export const queries = {
  article: (slug: string) => ({
    queryKey: ['article', slug],
    queryFn: ({ signal }) => api.articles.get(slug, { signal }),
    staleTime: 5 * 60_000,
  }),
};

Такой объект удобно использовать и на сервере для prefetchQuery.

Совет: держите все фабрики в одном файле (queries.ts). Тогда prefetchQuery(queries.article(slug)) в getServerSideProps или React Server Components будет полностью типобезопасен, и вы не забудете включить те же staleTime/gcTime.

Обработка ошибок

Бросайте исключения (throw new Error), а не возвращайте null.
Добавьте errorFormatter, если используете zod/superstruct.
Для REST предпочтительно заворачивать ответ в zod-схему до return.

const todosSchema = z.array(
  z.object({
    id: z.string(),
    title: z.string(),
    completed: z.boolean(),
  }),
);

async function fetchTodos(ctx: QueryFunctionContext) {
  const data = await client.getTodos(ctx);
  return todosSchema.parse(data);
}

Лайфхаки

Настройте retry(failureCount, error) прямо в query options, чтобы не ретраить 4xx.
Для GraphQL удобно кидать кастомный GraphQLError, а в onError уже решать, что показывать пользователю.
Чтобы обогащать ошибки, добавляйте Object.assign(error, { meta: ctx.meta }).

Повторное использование `queryFn`

export const todoQueryOptions = (id: string) => ({
  queryKey: ['todo', id],
  queryFn: (ctx) => api.todo.get({ id, signal: ctx.signal }),
});

// Хук
export const useTodo = (id: string) => useQuery(todoQueryOptions(id));

Единая функция исключает ошибки при гидратации (dehydrate/Hydrate).

Можно добавить общий билдер:

const buildQueryFn =
  <TResult>(fetcher: (ctx: QueryFunctionContext) => Promise<TResult>) =>
  (overrides: Partial<QueryOptions<TResult>> = {}) => ({
    queryFn: fetcher,
    staleTime: 30_000,
    gcTime: 5 * 60_000,
    ...overrides,
  });

export const userQuery = (id: string) =>
  buildQueryFn(({ signal }) => api.user.get(id, { signal }))({
    queryKey: ['user', id],
  });

Так вы стандартизируете staleTime/gcTime/retry и минимизируете опечатки.

Параметры запроса

Используйте сериализуемые объекты ({ page, filter }), а не строки с конкатенацией.
Внутри queryFn делайте деструктуризацию: const [{ page, filter }] = queryKey.slice(1);
Если параметры сложные, введите helper createKey('todos', { ... }).

Работа с `pageParam` и бесконечными списками

type PostsPage = { items: Post[]; nextCursor?: string };

export const postsInfiniteQuery = (cursor?: string) => ({
  queryKey: ['posts', { cursor }],
  queryFn: ({ pageParam = cursor, signal }) =>
    api.posts.list({ cursor: pageParam, signal }),
  initialPageParam: null as string | null,
  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
});

const { data, fetchNextPage, isFetchingNextPage } =
  useInfiniteQuery(postsInfiniteQuery());

Тонкости

pageParam живёт только внутри queryFn, поэтому обязательно передавайте его в API.
Если API возвращает пустой массив, но hasMore=true, храните отдельное поле nextCursor, иначе Query перестанет запрашивать новые страницы.
Для синхронизации с роутером сохраняйте cursor в queryKey: так можно делать queryClient.invalidateQueries({ queryKey: ['posts'] }) без доп. параметров.

Idempotency и кеш

queryFn должен быть чистым: один и тот же queryKey -> один и тот же результат. Побочные эффекты (запись) выполняйте в мутациях.

Проверочный чек-лист перед созданием queryFn:

Нет ли глобального стейта/рандома внутри queryFn.
Возвращает ли функция тот же объект (по содержимому) для одинаковых входных данных — иначе structuralSharing не сработает.
Используется ли select, чтобы срезать лишние поля перед выдачей в компонент.

Типизация

type TodosQueryKey = ReturnType<typeof todosQueryOptions>['queryKey'];

const fetcher: QueryFunction<Todo[], TodosQueryKey> = async ({ queryKey }) => {
  const [_key, { userId }] = queryKey;
  return client.getTodos(userId);
};

Дополнительно

Вы можете типизировать queryFn через InferQueryOptions<typeof todoQueryOptions>.
Для RSC используйте Awaited<ReturnType<typeof queryFn>>, чтобы избегать any при dehydrate.
Если нужно переиспользовать тип ответа, экспортируйте type TodoQueryData = Awaited<ReturnType<typeof fetcher>>;.

Prefetch, SSR и RSC

// сервер
await queryClient.prefetchQuery(todoQueryOptions(id));
const dehydratedState = dehydrate(queryClient);

// клиент
<Hydrate state={dehydratedState}>
  <TodoPage />
</Hydrate>

На сервере всегда передавайте один и тот же queryFn, что и на клиенте (см. «паттерн контекста»).
В Next.js App Router можно вызвать await queryClient.ensureQueryData(...) прямо в серверном компоненте.
В RSC удобно пробрасывать headers/cookies через meta, чтобы один и тот же queryFn использовал правильный fetch.

Placeholder, Initial Data и синхронизация с API

initialData задаёт готовый кеш и влияет на dataUpdatedAt.
placeholderData отображается мгновенно, но не попадает в кеш. Идеально для списков: placeholderData: keepPreviousData.
Используйте queryClient.setQueryData после мутации, чтобы не ждать полного refetch.

Пример «теплого» кеша:

const useTodoList = (filters: Filters) =>
  useQuery({
    ...todoListQuery(filters),
    placeholderData: (prev) =>
      prev ? { ...prev, isPlaceholder: true } : undefined,
    select: (data) => data.items,
  });

Диагностика и отладка API

queryClient.getQueryCache().findAll({ queryKey: ['todos'] }) — быстрый способ увидеть все вариации ключей.
В Devtools включите showQueryKey, чтобы ловить опечатки в фильтрах.
Используйте onSuccess для логирования, а не queryFn: так не исказится кеш.

Тестирование

В юнит-тестах мокайте queryFn и вызывайте queryClient.fetchQuery.
Для MSW: переносите queryFn в отдельный модуль, а в тесте подключайте setupServer.

test('fetches profile once', async () => {
  const queryClient = new QueryClient();
  server.use(rest.get('/profile', ...));

  const result = await queryClient.fetchQuery(profileQueryOptions());
  expect(result).toMatchObject({ id: 'user_1' });
  expect(server.handledRequests('/profile')).toHaveLength(1);
});

При тестировании отмены пользуйтесь AbortController и queryClient.fetchQuery(..., { signal }).
Для e2e можно провалидировать, что при переходе на другую страницу запрос отменили (server.events в MSW).