Network mode и поведение офлайн

TanStack Query опирается не только на кэширование данных, но и на понимание состояния сети. Поведение запросов в условиях отсутствия соединения или нестабильного интернета управляется через механизм network mode, который определяет, как библиотека должна реагировать на офлайн-состояние, попытки повторных запросов и восстановление соединения.

Сетевой режим влияет на стратегию выполнения query и mutation, определяя, будут ли запросы блокироваться при отсутствии сети, ставиться в очередь или выполняться в любом случае.

Основные сетевые режимы

В TanStack Query выделяются три ключевых режима работы с сетью:

online (режим по умолчанию)

Поведение ориентировано на активное сетевое соединение. Если устройство считается офлайн, запросы не выполняются.

Ключевые особенности:

  • запросы блокируются при отсутствии сети
  • автоматический переход в idle при offline состоянии
  • повторное выполнение после восстановления соединения
  • активная интеграция с onlineManager

Логика построена вокруг события navigator.onLine, а также событий online / offline в браузере.

Важно, что даже при наличии кэша запрос не будет перезапущен до восстановления сети, если не используется дополнительная логика.

always

Режим игнорирует состояние сети.

Характеристики:

  • запросы выполняются даже при navigator.onL ine === false
  • TanStack Query не блокирует fetch
  • ошибки сети обрабатываются как обычные ошибки запроса
  • отсутствует автоматическая защита от офлайн-вызовов

Этот режим полезен в случаях, когда:

  • используется кастомный транспорт (например, WebSocket или Electron IPC)
  • состояние сети определяется внешней системой
  • требуется попытка выполнения запроса независимо от статуса браузера

offlineFirst

Режим приоритетного использования кэша.

Логика работы:

  • сначала проверяется наличие данных в кэше
  • если данные есть и считаются валидными — сетевой запрос не выполняется
  • при отсутствии данных выполняется запрос даже в офлайн-режиме

Поведение можно описать как:

  1. попытка получить данные из cache
  2. возврат кеша, если он подходит по staleTime
  3. выполнение запроса только при необходимости

Этот режим особенно эффективен в PWA и приложениях с частичной офлайн-работой.

Как TanStack Query определяет состояние сети

Библиотека использует onlineManager, который реагирует на системные события браузера:

  • window.addEventListener('online')
  • window.addEventListener('offline')

Также учитывается:

  • navigator.onLine
  • кастомные обработчики через onlineManager.setEventListener

Состояние сети влияет на:

  • запуск query
  • повторные попытки (retries)
  • refetch при восстановлении соединения

Поведение запросов при офлайн-состоянии

Когда сеть недоступна, поведение зависит от networkMode и типа операции.

Query

В режиме online:

  • запрос переходит в состояние paused
  • данные из кэша возвращаются, если доступны
  • автоматический refetch откладывается

В режиме offlineFirst:

  • при наличии данных в кэше запрос не выполняется
  • при отсутствии данных query может попытаться выполниться

В режиме always:

  • запрос выполняется независимо от сети
  • ошибка фиксируется как обычный fetch error

Mutation

Mutations ведут себя иначе, так как часто связаны с изменением состояния сервера.

При offline:

  • в online режиме mutation приостанавливается
  • возможна очередь через retry-логику
  • при восстановлении сети выполняется повтор

В always режиме:

  • mutation выполняется немедленно
  • ошибки сети возвращаются сразу

Взаимодействие с retry и backoff

Сетевой режим тесно связан с механизмом повторных попыток.

При offline состоянии:

  • retry может быть отложен до появления сети
  • используется экспоненциальная задержка (exponential backoff)
  • возможна пауза выполнения до online события

Пример логики:

  • попытка запроса
  • ошибка network
  • проверка состояния сети
  • переход в paused state
  • возобновление при online

focus/refetch и восстановление сети

TanStack Query реагирует не только на сеть, но и на активность вкладки.

Комбинация факторов:

  • onlineManager
  • focusManager
  • refetchOnWindowFocus
  • refetchOnReconnect

При восстановлении сети:

  • автоматически триггерится refetch активных query
  • stale данные обновляются
  • кеш синхронизируется с сервером

Это поведение критично для приложений с долгоживущими сессиями.

Кэш и офлайн-доступ к данным

Кэш является центральным элементом офлайн-стратегии.

Особенности:

  • данные сохраняются независимо от сети
  • staleTime определяет актуальность офлайн-данных
  • gcTime влияет на срок жизни в памяти

При корректной настройке:

  • приложение может работать полностью офлайн
  • UI продолжает отображать последние известные данные
  • обновление происходит при восстановлении сети

Persisted Query Cache и офлайн-сценарии

Для полноценного офлайн-режима используется persistence слоя кэша:

  • localStorage
  • IndexedDB
  • AsyncStorage (React Native)

Преимущества:

  • сохранение состояния между перезагрузками
  • восстановление данных без сети
  • синхронизация после reconnection

Типичная схема:

  1. загрузка кэша из storage
  2. инициализация QueryClient
  3. работа приложения офлайн
  4. синхронизация при появлении сети

Приоритеты источников данных

При наличии нескольких источников данных действует следующий порядок:

  1. свежие данные с сервера
  2. кэш TanStack Query
  3. persisted storage
  4. fallback UI состояния

Режим offlineFirst усиливает приоритет кэша, снижая зависимость от сети.

Типичные сценарии поведения

Медленная сеть

  • запрос выполняется с задержкой
  • кэш может быть показан быстрее
  • refetch происходит фоново

Полный offline

  • запросы блокируются (online mode)
  • UI работает на кэше
  • mutations могут быть отложены

Восстановление соединения

  • автоматический refetch
  • синхронизация изменений
  • повтор queued mutations

Контроль через QueryClient

Управление сетевым поведением часто централизуется через QueryClient:

  • глобальные настройки retry
  • управление staleTime
  • интеграция с onlineManager
  • настройка refetch поведения

Также возможно ручное управление состоянием:

  • queryClient.invalidateQueries
  • queryClient.refetchQueries

Практические особенности архитектуры

Сетевые режимы влияют на архитектуру приложения:

  • UI должен быть устойчив к отсутствию данных
  • логика не должна зависеть от мгновенного ответа сервера
  • важно разделение server state и client state
  • офлайн-режим требует предсказуемого кэша

TanStack Query фактически превращает серверные данные в локальное состояние с управляемой синхронизацией.

Ограничения сетевых режимов

Несмотря на гибкость, существуют ограничения:

  • browser API может некорректно определять online status
  • navigator.onLine не гарантирует доступ к интернету
  • сложные офлайн-очереди требуют дополнительной реализации
  • conflict resolution между mutation и cache может быть ручным

Поведение при нестабильных соединениях

При flapping-сети (частое переключение online/offline):

  • возможны повторные refetch
  • mutations могут дублироваться без защиты
  • рекомендуется debounce событий сети

TanStack Query минимизирует лишние запросы, но полностью проблему нестабильной сети не решает без архитектурных решений на уровне приложения.

Оглавление