Введение

Работа с источниками данных в проекте: REST, realtime и любые другие каналы, которые появятся в будущем. Раздел описывает, как создаются клиенты для API и как полученные данные доходят до страниц и компонентов.

Принципы раздела

• Клиент — в infrastructure/. Каждый внешний сервис — отдельный модуль слоя infrastructure/{service-name}/.
• Прямой fetch запрещён. Запросы идут только через клиент модуля. Исключения — точечные и обоснованные.
• Источник данных диктует канал. REST, realtime и т.п. — независимые подразделы, у каждого своя модель клиента и своё потребление.
• Серверные и клиентские компоненты потребляют по-разному. Server Components — прямой await метода клиента, клиентские — через готовые хуки модуля API (useUserList, usePostDetail и т.п.). SWR инкапсулирован в хуке, компонент про него не знает.

Карта раздела

REST

Канал «запрос-ответ» по HTTP. Покрывает большинство API.

• Клиенты — как создаётся клиент REST API:
  • Автоматическая генерация — для API с OpenAPI-спецификацией, через @gromlab/api-codegen.
  • Ручная генерация — для API без схемы, клиент пишется и поддерживается руками.
• Получение данных — как клиент используется в приложении:
  • Серверные компоненты — прямой await метода клиента в Server Components.
  • Клиентские компоненты — через готовые хуки модуля API; SWR с кешем, дедупликацией и ревалидацией скрыт внутри хука.

Realtime

Канал push-данных: WebSocket, SSE, событийные шины. Транспорт не зашит в правила — важна абстракция «подписка».

• Realtime — клиент realtime в infrastructure/, потребление через useSWRSubscription или прямые подписки.

Что даёт раздел

После прочтения раздела понятно:

• Где живёт код работы с API и почему именно там.
• Когда генерировать клиент автоматически, а когда писать вручную, и как структурирован каждый из вариантов.
• Как получать данные на сервере и на клиенте, чтобы не ломать кеш и не плодить лишние запросы.
• Как подключать realtime-источники в общую модель работы с данными.
• Какие правила обязательны и какие отклонения допустимы.

Что не входит в раздел

• Глобальное состояние UI — Stores, формы, фичефлаги. Это Stores.
• Доменная логика — как данные превращаются в сценарии бизнеса. Это слой business/ в Архитектуре.
• Хуки общего назначения — переиспользуемые хуки UI, не привязанные к конкретному API. Это Хуки.