5. Параллельные и зависимые запросы

В реальных приложениях часто нужно загружать несколько ресурсов одновременно или дожидаться завершения одного запроса перед запуском другого. TanStack Query v5 предлагает специализированные API.

Параллельные запросы через useQueries

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

const userDashboardQueries = (id: string) => [
  { ...userQuery(id) },
  { ...postsQuery(id), staleTime: 60_000 },
  { ...statsQuery(id), enabled: id !== 'guest' },
];

export function Dashboard({ userId }: { userId: string }) {
  const results = useQueries({ queries: userDashboardQueries(userId) });
  const [user, posts, stats] = results;

  if (user.isPending || posts.isPending) return <Skeleton />;
  return <DashboardView user={user.data} posts={posts.data} stats={stats.data} />;
}

• Каждый элемент массива — объект с полным набором QueryOptions.
• useQueries возвращает массив состояний в том же порядке.
• Для 10+ запросов подумайте о комбинировании данных в одном REST-эндпоинте.
• Старайтесь мемоизировать массив queries, иначе каждый ререндер создаёт новые ссылки и заставляет хук перезапускать работу.
• Если нужно остановить цепочку при первой ошибке, используйте combine и бросайте исключение, когда results.some(r => r.error).
• В v5 есть useSuspenseQueries — та же идея, но сразу дружит с React Suspense.
• queryClient разделяет кеш между всеми хуками, поэтому параллельные useQueries мгновенно пересоберут состояние при повторном посещении экрана.

combine для единого результата

const { data, pending, error } = useQueries({
  queries: [{ ...userQuery(id) }, { ...teamQuery(id) }],
  combine: results => ({
    data: {
      user: results[0].data,
      team: results[1].data,
    },
    pending: results.some(r => r.isPending),
    error: results.find(r => r.error)?.error,
  }),
});

combine вызывается при каждом изменении какого-либо результата, что упрощает мемоизацию.

• Возвращайте полностью новый объект, чтобы React корректно детектировал изменения. Если хотите сохранить ссылки, оборачивайте в useMemo.
• Можно агрегировать ошибки: const errors = results.flatMap(r => r.error ? [{ key: r.queryKey, error: r.error }] : []);.
• Если в combine вернуть null, компонент рендерится как будто данных нет. Удобно скрывать виджеты, пока не загрузилось всё.

Зависимые запросы (enabled)

const { data: user } = useQuery(userQuery(id));

const projects = useQuery({
  ...projectsQuery(user?.teamId),
  enabled: Boolean(user?.teamId),
});

enabled гарантирует, что второй запрос стартует только после получения параметров из первого. Нет нужды вручную проверять status.

• Используйте функцию: enabled: () => Boolean(user?.teamId) — лениво вычисляется в момент вызова queryFn.
• В критичных сценариях добавьте retry: false, чтобы зависимый запрос не блокировал UI при повторных падениях.
• Вместо enabled можно передавать queryFn: user ? () => fetchProjects(user.teamId) : skipToken, но булевый флаг читается проще.

suspense + зависимые запросы

При использовании useSuspenseQuery комбинируйте с useMemo, чтобы не запускать скрытых запросов:

const projectsQueryOptions = useMemo(() => {
  if (!user?.teamId) return undefined;
  return projectsQuery(user.teamId);
}, [user?.teamId]);

const projects = useSuspenseQuery(projectsQueryOptions);

• Если Suspense-граница общая, передавайте suspense: false в зависимом запросе и вручную отображайте skeleton — так не “заморозите” весь экран.
• placeholderData для зависимых запросов помогает избежать “прыжков” в UI, пока приходит новый teamId.

Последовательные цепочки

const { data: sessionToken } = useQuery(sessionTokenQuery(), { gcTime: 0 });

const { data: profile } = useQuery({
  ...profileQuery(),
  enabled: Boolean(sessionToken),
  meta: { sessionToken },
});

meta можно использовать для проброса результата предыдущей операции во второй queryFn.

• Через meta также удобно логировать, какие зависимые запросы запускались и сколько заняли.
• Если цепочка длинная, рассмотрите useMutation с onSuccess внутри: в onSuccess можете дергать queryClient.ensureQueryData для следующих шагов.
• Для последовательного шага без компонента есть await queryClient.fetchQuery({...}) — удобно в роутерах и при серверном пререндере.

Отмена и координация

• Если зависимый запрос больше не нужен (проп userId поменялся), первый queryFn отменится автоматически, а второй даже не стартует.
• Для сложных цепочек рассмотрите Promise.all внутри одного queryFn, если данные должны приходить единовременно.
• При использовании AbortController из queryFn не забывайте прокидывать signal в дочерние fetch’и — TanStack Query сам завершит их при unmount.
• queryClient.cancelQueries({ queryKey: ['user', id] }) помогает ручным образом остановить первую часть цепочки (например, при закрытии модалки).
• refetchOnWindowFocus в параллельных запросах можно индивидуально выключать (например, статистика рефрешится, а heavy-репорт — нет).

Примеры использования

1. Dashboard — useQueries для получения виджетов параллельно.
2. Форма редактирования — основной объект + справочники (selectOptionsQuery).
3. Мастер-детейл — детальный запрос включается enabled: Boolean(selectedId).
   • Динамический список идов — useQueries({ queries: ids.map(id => orderQuery(id)) }) + combine для нормализации.
   • Персональные рекомендации — основной пользователь, список интересов и отдельный запрос на офферы, включается только когда оба первые готовы.

Рекомендации

• Не используйте useEffect для вызова refetch при смене зависимостей — лучше включайте их в queryKey.
• При рендере списка карточек избегайте вложенного useQuery внутри .map. Вынесите в дочерний компонент или аггрегируйте запрос.
• Для «ленивой» загрузки секций используйте enabled: isOpen.
• Добавляйте keepPreviousData: true в зависимых запросах со списками, чтобы не мигала таблица при смене фильтра.
• select и structuralSharing: false помогают уменьшить количество лишних ререндеров, когда параллельных запросов много.
• При серверном рендере (Next, Remix) используйте queryClient.prefetchQuery для всех параллельных запросов — клиент сразу получит готовые данные.
• Для тестов мокайте QueryClient и передавайте defaultOptions: { queries: { retry: false } }, чтобы не ждать повторных попыток.