TanStack Query построена вокруг идеи отделения серверного состояния от UI и управления им через единый, централизованный слой кеша. В основе лежит не просто библиотека для загрузки данных, а полноценная архитектурная модель, в которой данные, их жизненный цикл и синхронизация с сервером рассматриваются как отдельная система.
Центральным элементом архитектуры является QueryClient. Это объект, который координирует все операции с данными:
QueryClient выступает как единая точка правды для всего серверного состояния в приложении. Все hooks и утилиты TanStack Query работают через него.
Внутри QueryClient содержится несколько ключевых подсистем:
QueryCache представляет собой структурированное
хранилище, где каждый запрос идентифицируется уникальным ключом
(queryKey).
Каждый элемент кеша — это объект Query, который содержит:
loading, error,
success)data)dataUpdatedAt)Ключевой принцип: один и тот же queryKey всегда
ссылается на один и тот же источник данных в кеше.
QueryCache работает как реактивный слой:
Каждый запрос в TanStack Query проходит строго определённый жизненный цикл.
При первом вызове useQuery создаётся Query объект (если
его нет в кеше). Он регистрируется в QueryCache.
Компонент подписывается на Query. Подписка означает, что любые изменения состояния Query будут вызывать обновление UI.
Если данные отсутствуют или устарели, запускается функция
queryFn. Она может возвращать Promise.
Query переходит в состояние loading. Все подписчики
получают обновление.
При успешном ответе:
successПри ошибке:
errorАрхитектура TanStack Query полностью опирается на структурированные ключи.
queryKey — это не строка, а массив, который позволяет
создавать иерархию:
['users', 42, 'posts']Такой подход даёт:
Кеш организован как дерево, где каждый уровень ключа добавляет детализацию.
TanStack Query использует модель подписок вместо глобального state management.
Каждый useQuery:
Это позволяет:
Подписка работает через внутренний event emitter QueryCache.
В архитектуре важно различие между:
Каждый Query имеет параметры:
Механизм работает так:
Это позволяет разделить:
Query, к которым нет подписчиков, не удаляются мгновенно. Вместо этого используется отсроченная очистка:
Такой подход предотвращает:
MutationCache управляет изменениями данных на сервере (POST, PUT, DELETE).
Каждая мутация содержит:
onSuccess, onError,
onSettled)Мутабельные операции не заменяют QueryCache напрямую. Вместо этого они:
Инвалидация — ключевой архитектурный механизм синхронизации.
При вызове invalidateQueries:
Важно, что инвалидация не равна удалению. Это логическая метка, а не физическая операция.
TanStack Query поддерживает background refetch, встроенный в архитектуру QueryObserver.
Обновление может происходить:
Это реализовано через систему глобальных event listeners, которые связываются с QueryClient.
QueryObserver — скрытый слой, который связывает:
Он отвечает за:
Фактически useQuery — это тонкая обёртка над QueryObserver.
Архитектура учитывает конкурентные запросы:
Также применяются механизмы:
Ключевой архитектурный принцип:
Это создаёт слой абстракции:
UI → QueryObserver → QueryCache → QueryClient → Server
Вся система можно представить как слоистую модель:
Каждый слой строго ограничивает ответственность.
Архитектура включает несколько оптимизаций:
QueryClient работает как event-driven система:
Эти события используются для синхронизации всех подсистем.
TanStack Query функционирует как распределённый кеш с реактивной моделью обновления, где:
Архитектура построена так, чтобы минимизировать прямое управление данными и перенести всю сложность в контролируемый слой кеширования и событийной синхронизации