Query-библиотеки: идентичность queryKey, два таймера и что TanStack Query реально экономит

queryKey — идентичность кеша, а не подпись

Сдвиг в голове: серверные данные — не ваше состояние, а кеш чужого состояния. TanStack Query делает это явным. Каждый запрос идентифицируется своим queryKey — массивом, хешируемым структурно (порядок ключей объекта не важен, порядок массива важен): ['todos', { status, page }]. Ключ — это адрес в кеше. Каждый компонент, зовущий useQuery с тем же ключом, читает ту же запись кеша — шесть компонентов, просящих ['me'], дают один запрос, дедуплицированный в полёте, и один общий ответ. Отсюда дисциплина: каждая переменная, которую читает queryFn, обязана быть в ключе — ровно как массив зависимостей useEffect. Забудьте page в ключе — и страница 2 перезапишет страницу 1 по тому же адресу; симптом — «мелькают чужие данные», диагноз почти всегда — ключ, недоописывающий запрос.

function Todos({ status, page }) {
  const { data, isPending, isError, error } = useQuery({
    queryKey: ["todos", { status, page }],   // идентичность = все входы
    queryFn: ({ signal }) =>
      fetchTodos({ status, page, signal }),  // abort подключён бесплатно
    staleTime: 30_000,                        // свежо 30 секунд
  });
  // isPending → первая загрузка, кеша ещё нет
  // data может быть и показана, и устаревшей: отдана мгновенно, перезапрошена сзади
}

function AddTodo() {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: createTodo,
    onSuccess: () =>
      queryClient.invalidateQueries({ queryKey: ["todos"] }), // по префиксу
  });
  return <button onClick={() => mutation.mutate({ title: "ship" })}>Add</button>;
}

Два таймера: staleTime решает перезапрос, gcTime решает память

Каждой записью кеша управляют два независимых таймера, и их смешивание — недоразумение номер один вокруг TanStack Query. staleTime отвечает: «достаточно ли эти данные свежи, чтобы отдать их, не спрашивая сервер снова?» Пока запись свежа, любой маунт или фокус окна отдаёт её из кеша, точка — ноль запросов. Когда запись устарела, данные всё равно отдаются мгновенно, но фоновый перезапрос стреляет на следующем триггере: монтируется новый компонент, окно получает фокус, сеть переподключается. Это stale-while-revalidate: пользователь всегда видит данные сразу; свежесть тихо приходит следом. gcTime отвечает на другой вопрос: «после размонтирования последнего компонента, использующего запись, сколько держать её в памяти?» Активная запись не собирается никогда; неактивная живёт gcTime (по умолчанию 5 минут), чтобы возврат назад в этом окне был мгновенным кеш-хитом, а не спиннером.

Дефолты сознательно агрессивны: staleTime: 0 — всё устаревает немедленно, поэтому каждый маунт и каждый фокус окна запускают фоновый перезапрос; плюс упавшие запросы ретраятся 3 раза с экспоненциальным бэкоффом. Команды открывают это как «почему наш API долбят?» — и ответ не в глобальном отключении refetchOnWindowFocus (перезапрос по фокусу — то, что делает дашборд честным, когда пользователь вернулся с обеда), а в честном staleTime на ресурс: 30 секунд для списка задач, 10 минут для списка стран, 0 для котировки. Неверная настройка таймеров ломается по-разному: слишком большой staleTime отдаёт неправду; слишком большой gcTime держит мёртвые данные в памяти; а gcTime меньше staleTime тихо обессмысливает свежесть — запись соберут раньше, чем вернувшийся посетитель ею воспользуется.

Мутации замыкают цикл — и настоящий счёт библиотеки

Чтения — половина истории. useMutation оборачивает запись, и в onSuccess вы примиряете кеш с новой серверной реальностью — проще всего через invalidateQueries({ queryKey: ['todos'] }): он матчит по префиксу каждый ключ, начинающийся с 'todos', помечает их устаревшими и немедленно перезапрашивает активные (неактивные лишь получают флаг и перезапросятся при следующем использовании). Это то, чего у паттерна с эффектами не было никогда: после POST ваши рукописные useState-кеши в пяти компонентах все молча неверны, и никакая гигиена эффектов не чинит данные, которые больше не отражают сервер.

Подобьём, что библиотека реально экономит против базы из прошлого урока: дедупликация в полёте (шесть подписчиков — один запрос) и общие записи кеша; встроенная защита от гонок — ответы сопоставляются со своими запросами, а queryFn получает AbortSignal, подключённый к отмене запроса; ретраи с экспоненциальным бэкоффом; жизненный цикл — устаревание, перезапрос по фокусу и реконнекту, сборка мусора; и путь записи — инвалидация плюс оптимистичные обновления (следующий урок). Вместе эти пять свойств означают, что каждый компонент, читающий одни данные, остаётся синхронизированным при записях, сбоях сети и возвратах на вкладку без единой строки boilerplate — уберите любое из них, и вы снова пишете его сами. Честные издержки: зависимость в критическом пути (~12 КБ gzip ядро), дисциплина проектирования ключей (ключи — схема вашего кеша; централизуйте их в фабрике, иначе разбросанные ad-hoc-ключи превращают точечную инвалидацию в гадание) и дефолты, которые надо осознанно настраивать. Трейдофф вечный: кеша вы не избегаете — вы выбираете между проверенным и тем, что напишете случайно.