Query Layer

Тема

Query LayerHTTP-запросы через Axios. Состояние через MobX.

API-слой получает и проверяет данные, store управляет запросом, а React-компонент работает только со store.

Быстрый старт
Выбрать API

RequestStore

Выполняет отдельный запрос без сохранения результата в общем кэше запросов, и хранит его MobX-состояние. Подходит для авторизации, регистрации, отправки форм, загрузки файлов, экспорта и одноразовых проверок.

FetchStore

Используется для ручного получения и кэширования данных через GET-запросы. При вызове fetch() он проверяет кэш, возвращает свежие данные или выполняет запрос и сохраняет ответ. Изменения параметров не отслеживаются, поэтому для обновления нужен новый вызов fetch().

QueryStore

После вызова start() store проверяет кэш. Актуальные данные использует сразу, иначе отправляет запрос и сохраняет ответ. Затем продолжает следить за записью, а при изменении параметров, например userId, переключается на другую запись кэша.

MutationStore

Используется для изменения данных через POST, PUT, PATCH и DELETE. Позволяет обрабатывать успешное выполнение, ошибки и обновлять или сбрасывать связанные данные в кэше.

InfiniteQueryStore

Постраничное чтение с cursor pagination. Хранит страницы и умеет загружать следующую или предыдущую.

QueryRuntime

Объединяет store общим кэшем и настройками запросов. Используется для Module Federation, сохранения кэша, синхронизации вкладок и диагностики.

Что это за библиотека ​

Query Layer организует работу с server state — данными, которые приложение получает с backend. Библиотека не рисует интерфейс и не описывает бизнес-модель. Она связывает Axios-запрос, MobX-состояние и кэш.

Обычный поток выглядит так:

  1. API-функция знает URL и формат HTTP-запроса.
  2. MobX-store вызывает API-функцию и хранит состояние запроса.
  3. React-компонент вызывает метод store и читает его observable-свойства.
  4. Компонент не импортирует Axios-клиент и не обращается к backend напрямую.
mermaid
flowchart LR
    UI["React-компонент"] --> Store["MobX domain store"]
    Store --> Handler["Query Layer API"]
    Handler --> Api["API-функция"]
    Api --> Backend["Backend"]

Зона ответственности ​

СлойЗа что отвечает
API-функцияHTTP-метод, URL, DTO, Axios config и проверка ответа
Query Layer APIЗапуск, отмена, retry, статус, ошибка и при необходимости кэш
Domain storeСкрывает техническую работу с запросом, преобразует данные UI в формат API и содержит вычисляемые значения и бизнес-правила feature
React-компонентОтображение данных и передача пользовательских действий в store

Query Layer не заменяет Axios, MobX или Valibot. Axios отправляет запрос, MobX делает состояние реактивным, Valibot при необходимости проверяет ответ, а Query Layer объединяет их в единый процесс: запуск запроса, загрузку, обработку результата, ошибки, отмену и кэширование.

Какие проблемы решает библиотека ​

  • React-компоненты не работают с Axios напрямую: они вызывают методы store и отображают его состояние;
  • loading, status, error и отмена работают одинаково во всех feature;
  • результаты GET-запросов сохраняются в кэше, а одинаковые одновременные запросы не отправляются повторно;
  • каждая запись кэша получает queryKey — адрес, по которому данные можно найти, обновить или пометить устаревшими;
  • для POST, PUT, PATCH и DELETE можно одинаково обработать запуск, успешный ответ, ошибку и завершение запроса;
  • InfiniteQueryStore управляет курсорной пагинацией и объединяет загруженные страницы;
  • host и remote в Module Federation могут безопасно работать с общим кэшем через QueryRuntime;
  • сохранение кэша, синхронизация между вкладками и очередь запросов без сети подключаются отдельно, только когда они нужны.

Как выбрать API ​

СитуацияAPIСоздание
Одноразовый запрос без query-кэшаRequestStorecreateRequestStore(...)
Ручное кэшируемое чтениеFetchStorenew FetchStore(...)
Автоматическое реактивное чтениеQueryStorecreateQueryStore(...)
Изменение данных с обработкой результата и обновлением кэшаMutationStorenew MutationStore(...)
Cursor paginationInfiniteQueryStorecreateInfiniteQueryStore(...)
Общий кэш, настройки запросов и MFQueryRuntimecreateQueryRuntime(...)

Слово create здесь означает factory-функцию, которая возвращает экземпляр. У FetchStore и MutationStore таких factory-функций нет — они создаются обычным new.

Начните с быстрого старта. Затем откройте страницу того API, который подходит вашей задаче.