S.Gromov
3d93efd90a
- Добавлен раздел «Данные»: REST (автоматическая и ручная генерация клиентов, получение данных в server и client компонентах с инкапсуляцией SWR в хуках), Realtime, введение - Прикладные разделы переименованы в «Использование», папка перенесена в `docs/docs/usage/` - Создана группа «Установка и настройка» с папкой `docs/docs/setup/` — туда вынесены PostCSS, Biome, VS Code, алиасы и установка SVG-спрайтов - Подгруппы «Стили» и «SVG-спрайты» в сайдбаре упразднены — страницы установки и использования разнесены по верхнеуровневым группам - Удалён устаревший раздел `applied/api.md` - Перекрёстные ссылки в workflow-разделах и внутри новых страниц синхронизированы с новыми путями - CONTRIBUTING.md обновлён под новую структуру папок
4.3 KiB
4.3 KiB
title, keywords
| title | keywords | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Введение |
|
Введение
Работа с источниками данных в проекте: 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 без схемы, клиент пишется и поддерживается руками.
- Автоматическая генерация — для API с OpenAPI-спецификацией, через
- Получение данных — как клиент используется в приложении:
- Серверные компоненты — прямой
awaitметода клиента в Server Components. - Клиентские компоненты — через готовые хуки модуля API; SWR с кешем, дедупликацией и ревалидацией скрыт внутри хука.
- Серверные компоненты — прямой
Realtime
Канал push-данных: WebSocket, SSE, событийные шины. Транспорт не зашит в правила — важна абстракция «подписка».
- Realtime — клиент realtime в
infrastructure/, потребление черезuseSWRSubscriptionили прямые подписки.
Что даёт раздел
После прочтения раздела понятно:
- Где живёт код работы с API и почему именно там.
- Когда генерировать клиент автоматически, а когда писать вручную, и как структурирован каждый из вариантов.
- Как получать данные на сервере и на клиенте, чтобы не ломать кеш и не плодить лишние запросы.
- Как подключать realtime-источники в общую модель работы с данными.
- Какие правила обязательны и какие отклонения допустимы.
Что не входит в раздел
- Глобальное состояние UI — Stores, формы, фичефлаги. Это Stores.
- Доменная логика — как данные превращаются в сценарии бизнеса. Это слой
business/в Архитектуре. - Хуки общего назначения — переиспользуемые хуки UI, не привязанные к конкретному API. Это Хуки.