Схема слоев
Слои и порядок между ними — часть архитектуры конкретного проекта: состав, количество и границы слоев определяет сам проект. Общая форма — вертикальная схема: более стабильные слои находятся ниже, более изменчивые — выше. Направление зависимостей — сверху вниз: слой может импортировать только то, что стоит ниже него.
Схема слоев — настройки settings.weld:
layers— слои проекта;moduleLayers— слои внутри модуля.
Оба списка читаются слева направо так же, как схема сверху вниз: элемент, записанный раньше, находится выше элемента, записанного позже. Сегодня схему читает только weld inspect, поэтому ни одно из правил линтинга порядок слоев пока не проверяет.
В проекте без модулей достаточно задать layers, например ['app', 'pages', 'common']. Метка @modules и moduleLayers задаются вместе или отсутствуют вместе. Без них modulesDir не распознается как контейнер модулей, а flatModules не влияет на схему.
export default [
{
settings: {
weld: {
layers: ['app', 'pages', '@modules', 'common'],
moduleLayers: ['widgets', 'features', 'entities'],
},
},
},
];Что соответствует следующей схеме:
Стрелки показывают направление зависимостей, а значит и разрешенный импорт: app может импортировать pages, слои модулей и common; pages — слои модулей и common; common не может импортировать никого.
Пример структуры директорий для схемы выше (корень дерева — srcDir, по умолчанию src):
src/
├── app/
├── pages/
├── modules/
│ ├── order/
│ │ ├── widgets/
│ │ ├── features/
│ │ └── entities/
│ └── user/
│ ├── widgets/
│ └── entities/
└── common/Каталог modules/ здесь содержит модули, но сам слоем не является. Имя каталога с модулями можно настроить, как и корень дерева (srcDir); в этом и дальнейших примерах используются значения по умолчанию — modules и src.
layers — слои проекта
layers — один упорядоченный список на весь проект, записанный сверху вниз. Обычные имена в нем — слои проекта: им соответствуют непосредственные дочерние директории исходного кода.
Имена с префиксом @ — служебные метки в схеме, а не имена директорий:
@modules— место, куда встают слои модулей изmoduleLayers;@unknown— место для кода, не относящегося ни к одному слою.
moduleLayers — слои модуля
moduleLayers задает одинаковую для всех модулей последовательность слоев сверху вниз. В отличие от слоев проекта, эти слои существуют не в одном экземпляре, а в каждом модуле — и в каждом вложенном модуле тоже, на любой глубине.
При импорте не важно, находятся источник и цель в одном модуле или в разных: значение имеет только положение их слоев в этом порядке. Поэтому order/widgets может импортировать публичную точку входа user/features, а order/entities — нет: features находится выше entities. Остальные границы модулей, включая публичный API и приватность, продолжают действовать.
@modules задает уровень этих слоев в схеме проекта. Поэтому слой модуля видит common, но не видит pages и app — независимо от того, в каком модуле он находится.
flatModules — корневые модули в srcDir
По умолчанию корневые модули лежат в src/modules/, как в примере выше. При flatModules: true они находятся прямо в srcDir:
src/
├── app/ ← слой проекта
├── order/ ← корневой модуль
│ ├── widgets/
│ ├── entities/
│ └── modules/ ← контейнер вложенных модулей
│ └── user/
│ └── entities/
└── common/Имя слоя проекта в корне имеет приоритет перед именем модуля. Имя слоя модуля может использоваться как имя корневого модуля: src/entities/ — модуль, а entities/ внутри модуля — слой.
При плоской схеме корневой src/modules/ не является контейнером: файлы под ним относятся к @root и @unknown. Вложенные модули по-прежнему находятся в modulesDir, например src/order/modules/user/ — модуль order::user.
Почему две настройки, а не один список
Слои можно было бы записать одним списком, перечислив слои модулей прямо на месте маркера. Разделение сохраняет то, что из одного порядка не выводится: слои проекта существуют в единственном экземпляре, а слои модуля повторяются в каждом модуле и на любой глубине вложенности. Это разные сущности, и маркер @modules показывает границу между ними одним взглядом.
Имена слоев
- Имя слоя — имя директории. Обычное имя начинается с буквы, а дальше состоит из букв, цифр,
-,_и.:entities,shared-ui,app_v2,common2,app.v2. Имя с/, а также.и..слоем быть не может: такую директорию не с чем было бы сопоставить. @зарезервирован под спец-позиции. Так называются только@modulesи@unknown, и обе допустимы только вlayers— вmoduleLayersих нет. Других имен, начинающихся с@, схема не принимает.- Одно обычное имя не может стоять в обоих списках. Слой
appвlayersи слойappвmoduleLayers— разные слои, но в дереве они неразличимы: директорияappвнутри модуля читалась бы то как слой проекта, то как слой модуля. - Префикс приватности. Имя слоя может нести префикс приватности — такой слой закрыт для внешнего кода и доступен только внутри директории, в которой лежит. Набор префиксов задает проект; подробности — в статье «Приватность».
INFO
Приватные имена слоев и контейнер internal/ для приватных модулей пока не поддерживаются: разбор путей по схеме их не учитывает.
Повторы: диапазон вместо списка исключений
По умолчанию каждое имя встречается в схеме один раз. Повтор имени ослабляет направление: слой перестает быть точкой и становится диапазоном между первым и последним вхождением. Всё, что попало внутрь диапазона, становится двунаправленным с этим слоем — вплоть до циклов.
INFO
Повтор — заявление о снятой гарантии, а не «настройка строгости»: пока он в схеме, направление внутри диапазона не проверяется. Размер послабления виден прямо в списке и сокращается, когда вхождения сдвигаются навстречу друг другу.
Два вида повторов решают разные задачи: смежный — самое узкое послабление, разнесенный — самое широкое.
Смежный повтор
Открывает только горизонтальные связи: одноименные слои разных модулей могут импортировать друг друга.
moduleLayers: ['widgets', 'features', 'entities', 'entities'];Здесь order/entities и user/entities видят друг друга, но права entities относительно остальных не меняются: features и widgets по-прежнему выше, и получить их entities не может.
Разнесенный повтор
Делает слой двунаправленным со всем, что попало между вхождениями.
layers: ['app', 'pages', 'legacy', '@modules', 'legacy', 'common'];Здесь legacy двунаправлен с модулем целиком и его слоями: легаси-код может импортировать их, а они — легаси. Сам legacy до pages и app при этом не дотягивается — они стоят выше обоих вхождений.
@unknown — код без слоя
Часть кода может остаться без слоя. Для такого кода вне модулей в layers есть позиция @unknown:
layers: ['app', 'pages', '@modules', '@unknown', 'common'];Позиция задает его права, как и у любого другого слоя: код без слоя может импортировать common, но не дотягивается до модулей, pages и app. В обратную сторону он открыт — импортировать его может всё, что стоит выше.
Если @unknown в схеме нет, такой код — нарушение, а не пропуск: иначе его импорты остались бы непроверенными при зеленом линте, и непроверенный код выглядел бы ровно как проверенный.