Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
8.3 KiB
Слои web
apps/web — React-приложение. Его код разложен по слоям, и зависимости между слоями идут строго в
одну сторону:
app → pages → widgets → entities → shared
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: shared не знает, где
применён и по чьей воле вызван, а entities не знает о widgets.
Слой — это директория: имя слоя и есть имя директории. Одни слои существуют в проекте в одном экземпляре, других — столько, сколько модулей.
Модуль — не слой, а рамка. modules/<домен> собирает свои entities и widgets и определяет,
что из них видно снаружи, — тем же способом, каким это делает модуль в
слоях API. Поддомен — такая же рамка, вложенная внутрь модуля.
app
Точка входа и оболочка.
app — внешний край приложения. Он монтирует React, объявляет маршруты и их защиту, держит
глобальные провайдеры и рисует оболочку: шапку, подвал, лейауты, общие для целой группы страниц.
Сюда попадает всё, что относится к приложению целиком, а не к отдельному экрану: например, баннер
согласия на cookie. app — единственный слой, который видит приложение снизу доверху, и его самого
не импортирует никто.
Входит:
- Точка входа приложения
- Маршруты и их защита
- Глобальные провайдеры
- Оболочка и лейауты страниц
- Элементы, относящиеся к приложению целиком
Не входит:
- Конкретные страницы и их содержимое
- Доменные данные и сценарии
- Формы, модалки и прочие блоки интерфейса
pages
Общий вид страницы и расстановка блоков.
pages отвечает за то, как страница выглядит целиком, и объявляет хлебные крошки. Страница
решает, какие виджеты на ней стоят, в каком они порядке и как расположены, — и задаёт каждому
начальные данные: идентификатор из маршрута, стартовое значение фильтра, активную вкладку.
Собственное состояние страницы допустимо ровно одно — то, которым страница связывает виджеты между собой. Виджеты друг о друге не знают, поэтому место их встречи — страница. Всё, что является бизнес-логикой или передачей сообщений между виджетами, странице не принадлежит.
Как и модуль, страница бывает вложенной: лейаут с вкладками — это тоже pages, и он объявляет
крошки за все свои вкладки, потому что только у него есть нужные для этого данные.
Входит:
- Композиция виджетов и их расположение на странице
- Хлебные крошки
- Начальные данные виджетов
- Состояние страницы как связь между виджетами
Не входит:
- Бизнес-логика
- Собственное отображение доменных данных — это дело виджетов
- Передача сообщений между виджетами
- Работа с API
widgets
Самостоятельный блок интерфейса.
Виджет сам добывает свои данные и сам держит своё состояние: открытие модалок, активную вкладку, раскрытые строки. Наружу он поставляет готовый блок, а внутрь принимает только параметры — идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего не зная о том, что внутри.
Один виджет — один законченный участок работы: AdminCreditsSummary рисует карточку баланса
платёжного аккаунта и держит диалоги лотов, броней и ручного начисления.
Виджет собирается из entities и shared и о других виджетах на странице не знает: связать два
виджета — задача pages.
Входит:
- Загрузка своих данных
- Своё состояние: модалки, вкладки, раскрытия, промежуточные значения форм
- Композиция
entitiesиshared - Действия пользователя в границах блока
Не входит:
- Хлебные крошки и общая раскладка страницы
- Знание о других виджетах
- Доменные правила
entities
Показ доменной сущности.
Entity отвечает за то, как выглядит одна доменная сущность или одно значение: TokenValue
показывает значение токенов, SummaryRow — строку сводки. Данные приходят пропсами; entity ничего
не загружает и ничего не меняет. Она отвечает только за вид и форматирование того, что ей передали:
числа, даты, статусы.
Входит:
- Показ одной доменной сущности или значения
- Форматирование значения: числа, даты, статусы
- Локальное состояние отображения
Не входит:
- Загрузка данных
- Действия над сущностью: создание, изменение, удаление
- Композиция нескольких сущностей
- Знание о странице и о том, где entity показана
shared
Общий слой.
shared — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API (shared/api), типы,
утилиты форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному
сценарию.
Слой ничего не знает о том, где и для чего его применили. Примитив интерфейса не подписывается на домен, а модуль API не решает, что показать пользователю при ошибке: решение принимает тот, кто его вызвал.
shared — нижний слой: его берут все, он не берёт никого.
Входит:
- UI-примитивы
- Вызовы API
- Типы и утилиты
- Переводы
- Форматирование значений
Не входит:
- Знание о том, где и в каком сценарии он применён
- Композиция доменного интерфейса
- Решения о том, что показать и что сделать при ошибке