Skip to content

Схема слоев ​

Слои и порядок между ними — часть архитектуры конкретного проекта: состав, количество и границы слоев определяет сам проект. Общая форма — вертикальная схема: более стабильные слои находятся ниже, более изменчивые — выше. Направление зависимостей — сверху вниз: слой может импортировать только то, что стоит ниже него.

Схема слоев — настройки settings.weld:

  • layers — слои проекта;
  • moduleLayers — слои внутри модуля.

Оба списка читаются слева направо так же, как схема сверху вниз: элемент, записанный раньше, находится выше элемента, записанного позже. Сегодня схему читает только weld inspect, поэтому ни одно из правил линтинга порядок слоев пока не проверяет.

В проекте без модулей достаточно задать layers, например ['app', 'pages', 'common']. Метка @modules и moduleLayers задаются вместе или отсутствуют вместе. Без них modulesDir не распознается как контейнер модулей, а flatModules не влияет на схему.

js
export default [
    {
        settings: {
            weld: {
                layers: ['app', 'pages', '@modules', 'common'],
                moduleLayers: ['widgets', 'features', 'entities'],
            },
        },
    },
];

Что соответствует следующей схеме:

Стрелки показывают направление зависимостей, а значит и разрешенный импорт: app может импортировать pages, слои модулей и common; pages — слои модулей и common; common не может импортировать никого.

Пример структуры директорий для схемы выше (корень дерева — srcDir, по умолчанию src):

text
src/
├── app/
├── pages/
├── modules/
│   ├── order/
│   │   ├── widgets/
│   │   ├── features/
│   │   └── entities/
│   └── user/
│       ├── widgets/
│       └── entities/
└── common/

Каталог modules/ здесь содержит модули, но сам слоем не является. Имя каталога с модулями можно настроить, как и корень дерева (srcDir); в этом и дальнейших примерах используются значения по умолчанию — modules и src.

layers — слои проекта ​

layers — один упорядоченный список на весь проект, записанный сверху вниз. Обычные имена в нем — слои проекта: им соответствуют непосредственные дочерние директории исходного кода.

Имена с префиксом @ — служебные метки в схеме, а не имена директорий:

moduleLayers — слои модуля ​

moduleLayers задает одинаковую для всех модулей последовательность слоев сверху вниз. В отличие от слоев проекта, эти слои существуют не в одном экземпляре, а в каждом модуле — и в каждом вложенном модуле тоже, на любой глубине.

При импорте не важно, находятся источник и цель в одном модуле или в разных: значение имеет только положение их слоев в этом порядке. Поэтому order/widgets может импортировать публичную точку входа user/features, а order/entities — нет: features находится выше entities. Остальные границы модулей, включая публичный API и приватность, продолжают действовать.

@modules задает уровень этих слоев в схеме проекта. Поэтому слой модуля видит common, но не видит pages и app — независимо от того, в каком модуле он находится.

flatModules — корневые модули в srcDir ​

По умолчанию корневые модули лежат в src/modules/, как в примере выше. При flatModules: true они находятся прямо в srcDir:

text
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

Повтор — заявление о снятой гарантии, а не «настройка строгости»: пока он в схеме, направление внутри диапазона не проверяется. Размер послабления виден прямо в списке и сокращается, когда вхождения сдвигаются навстречу друг другу.

Два вида повторов решают разные задачи: смежный — самое узкое послабление, разнесенный — самое широкое.

Смежный повтор ​

Открывает только горизонтальные связи: одноименные слои разных модулей могут импортировать друг друга.

js
moduleLayers: ['widgets', 'features', 'entities', 'entities'];

Здесь order/entities и user/entities видят друг друга, но права entities относительно остальных не меняются: features и widgets по-прежнему выше, и получить их entities не может.

Разнесенный повтор ​

Делает слой двунаправленным со всем, что попало между вхождениями.

js
layers: ['app', 'pages', 'legacy', '@modules', 'legacy', 'common'];

Здесь legacy двунаправлен с модулем целиком и его слоями: легаси-код может импортировать их, а они — легаси. Сам legacy до pages и app при этом не дотягивается — они стоят выше обоих вхождений.

@unknown — код без слоя ​

Часть кода может остаться без слоя. Для такого кода вне модулей в layers есть позиция @unknown:

js
layers: ['app', 'pages', '@modules', '@unknown', 'common'];

Позиция задает его права, как и у любого другого слоя: код без слоя может импортировать common, но не дотягивается до модулей, pages и app. В обратную сторону он открыт — импортировать его может всё, что стоит выше.

Если @unknown в схеме нет, такой код — нарушение, а не пропуск: иначе его импорты остались бы непроверенными при зеленом линте, и непроверенный код выглядел бы ровно как проверенный.