Создание пользовательских шаблонов и стандартов в Nx для согласованности

Каждая инженерная команда, которая выходит за рамки нескольких проектов, в конечном итоге сталкивается с одной и той же проблемой: как вы поддерживаете согласованность десятков или сотен кодовых баз? Без явных стандартов каждый новый проект становится снежинкой - разные структуры папок, разные версии зависимостей, разные правила винта, разные настройки тестирования. Результатом является повышенная когнитивная нагрузка, более медленная посадка и кошмар обслуживания. Nx, структура сборки монорепо от Nrwl, была разработана для решения именно этой проблемы. Предоставляя систему генераторов, общие файлы конфигурации и мощные механизмы обеспечения выполнения, Nx дает командам инструменты для выпечки согласованности непосредственно в их рабочем процессе. Эта статья проходит через практические стратегии для создания пользовательских шаблонов и стандартов в Nx, от проектирования генераторов до соблюдения правил в каждом проекте в вашем рабочем пространстве.

Проблема согласованности в масштабе

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

Nx заменяет этот специальный подход программным. Вместо копирования и вставки разработчики запускают команду — — и получают проект, который соответствует каждому стандарту, который определила команда. Шаблон не является статической копией; это генератор, который может встраивать логику, запрашивать пользовательский ввод и автоматически подключать конфигурацию. Это устраняет изменчивость, которая ползет в ручной настройке. Последовательность становится путем наименьшего сопротивления.

Как Nx обеспечивает согласованность

Nx достигает согласованности через три основных механизма: генераторы, общие конфигурации и исполнительные затворы. Генераторы (часто называемые «схемами» в более старой документации Nx) - это функции, которые создают или изменяют файлы. Они являются основным инструментом для пользовательских шаблонов. Общие конфигурации, такие как , в корне и , распространяют настройки во всех проектах. Исполняющие затворы - такие как выстилка и этапы тестирования в вашем конвейере CI - предотвращают несоответствующий код от когда-либо слияния.

Генераторы: основа пользовательских шаблонов

Генератор Nx — это файл TypeScript (или JavaScript), который экспортирует функцию . Эта функция получает (абстракцию по файловой системе) и (варианты, переданные разработчиком). Внутри генератора вы можете читать, создавать, обновлять или удалять файлы. Nx поставляется с набором встроенных генераторов для Angular, React, Node и других фреймворков, но вы можете создать свой собственный, чтобы кодифицировать любой шаблон, который использует ваша команда.

Например, представьте, что ваша команда требует, чтобы каждая интерфейсная библиотека включала определенную структуру папок: каталог для экспорта бочек, папка для компонентов React и папка для единичных тестов. Настраиваемый генератор может автоматически скаффолдировать это. Он также может добавить библиотеку в глобальный файл бочек, зарегистрировать его в и настроить любые необходимые переопределения ESLint. Разработчик предоставляет только имя библиотеки и дополнительный каталог; генератор обрабатывает остальное.

Проектирование пользовательских генераторов в Nx

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

Шаг 1: Определите схему и интерфейс

Начните с принятия решения о том, какие параметры генератор примет. Общие параметры включают , , (для ограничений зависимости Nx) и (CSS, SCSS, CSS-in-JS.] Они определены в файле , который также определяет правила проверки (например, требуемые поля, значения по умолчанию). Nx CLI использует эту схему для подсказки пользователей или проверки ввода. Хорошо разработанная схема уменьшает путаницу и предотвращает создание несоответствующих проектов.

Шаг 2: Реализуйте логику генератора

Функция генератора получает и проверенную . Используйте утилиты для взаимодействия с деревом.

Файлы шаблонов хранятся рядом с генератором и используют синтаксис EJS для вариабельной интерполяции. Например, шаблон может содержать , который будет заменен именем библиотеки. Вы также можете включать условные блоки или петли внутри шаблонов, если логика проста; для более сложной логики предпочтите манипулировать деревом в самом генераторе.

Шаг 3: Зарегистрируйте генератор

Генераторы регистрируются в разделе (или для более старых настроек]. Для локального плагина файл в проекте плагина определяет, какие генераторы доступны и где их код живет. После регистрации генератор становится видимым для и может быть обнаружен другими разработчиками через CLI или Nx Console.

Шаг 4: Испытайте генератор

Nx предоставляет помощника по тестированию, , из . Напишите единичные тесты, которые вызывают ваш генератор на виртуальном дереве и утверждают полученную структуру файла. Также проверьте крайние случаи: что происходит, если библиотека уже существует? Если каталог вложен? Если необходимые параметры отсутствуют? Надежное тестирование гарантирует, что генератор остается надежным по мере развития рабочего пространства.

Соблюдать стандарты с помощью Nx

Создание шаблонов — это только половина картины. Даже с идеальными генераторами разработчик может изменять файлы после генерации способами, которые нарушают стандарты. Nx позволяет автоматически применять стандарты, не полагаясь на человеческий анализ кода для каждого файла.

Общие линтинговые и форматирующие конфигурации

Разместите файлы конфигурации ESLint и Prettier в корне рабочего пространства. Плагин Nx ESLint () позволяет определять правила рабочего пространства, при этом все еще позволяя переопределять уровень проекта. Например, вы можете обеспечить соблюдение всеми библиотеками конвенции об именах (например, префикс , , ) путем написания пользовательского правила ESLint или использования . Правило особенно мощно: оно использует , назначенное вам проектам во время генерации, чтобы запретить определенные отношения зависимости. Библиотека доступа к данным, например, не может импортировать из библиотеки пользовательского интерфейса. Это архитектурное ограничение применяется во время включения, а не только в проектных документах.

Интеграция с Nx Affected Commands

Команды Nx , , ) выполняются только на проектах, которые изменились, что делает быструю обратную связь возможной даже в больших монорепо. Настройте свой конвейер CI для запуска на каждом PR. Если проект не выстраивается, PR не может быть объединен. Это уловка неизменная приверженность вашим пользовательским правилам выстраивания. объединяйтесь с для обеспечения форматирования Prettier. Вместе эти автоматизированные проверки делают отклонение от стандартов видимым и блокируемым.

Общие версии зависимостей

Nx разрешает зависимости через один корень. Это означает, что все проекты имеют одну и ту же версию, скажем, React или Lodash - устраняя искажение версии. Для монорепо с различными фреймворками вы все еще можете использовать управление зависимостью на уровне рабочего пространства через или рабочие пространства, но Nx обеспечивает, чтобы ни один проект не прокрадывался в конфликтующую версию через свою собственную . Вы также можете создавать схемы генератора, которые закрепляют конкретные версии зависимостей и проверяют их с помощью автоматизированных аудитов.

Кодовое поколение как ворота

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

За пределами лесов: стандартизация архитектуры

Настраиваемые шаблоны и правила винта могут обеспечить не только структуру файлов и стиль кода, но и архитектурные шаблоны. Именно здесь Nx сияет по сравнению с более простыми инструментами для строительных лесов.

Структура папки как контракт

Выберите стандартную иерархию для рабочего пространства. Общий шаблон для фронтенд-монорепо:

Ваш собственный генератор может обеспечить это, по умолчанию в каталоге , вызывая категорию (например, функцию, общий доступ к данным) и размещая проект соответственно.Со временем каждый разработчик интернализует структуру, потому что это единственная структура, которую создает генератор.

Наименования конвенций и тегов

Метаданные Nx прикреплены к проектам, которые использует правило границы модуля. Например, библиотеке с тегом может быть разрешено импортировать , но не . Определите свою конвенцию тегов в документе уровня рабочего пространства и внедрите ее в генератор: когда разработчик создает новую библиотеку типа «доступ к данным», генератор автоматически добавляет тег .

Общий шаблон для общих шаблонов

Рассмотрим создание генераторов для межсекторальных задач: промежуточное ПО для журналирования, границы ошибок, заглушки клиента API, определения маршрутов. Вместо того, чтобы каждый разработчик реализовывал утилиту для журналирования по-разному, генератор создает согласованную службу журналирования с выбранной командой библиотекой (например, Winston, Pino) предварительно сконфигурированной. Тот же принцип применяется к запросам GraphQL, конечным точкам REST, срезам управления состоянием и т. Д. Каждый сгенерированный проект становится моделью лучших практик команды.

Интеграция стандартов в рабочий процесс вашей команды

Технические решения эффективны только в том случае, если команда их принимает. Вот практические шаги по развертыванию пользовательских шаблонов и стандартов без перегрузки ваших разработчиков.

Начните с малого: один генератор, одно правило

Не пытайтесь генерировать каждый возможный тип проекта в первый день. Определите наиболее распространенный тип проекта, который ваша команда создает - вероятно, библиотеку для определенного слоя или новую оболочку приложения - и создайте генератор для этого. Одновременно введите одно правило обеспечения соблюдения, такое как форматирование Prettier в CI. Пусть команда испытает преимущество, прежде чем добавить больше сложности.

Документируйте свои генераторы и конвенции

Генераторы бесполезны, если никто не знает, что они существуют. Добавьте каталог в корень рабочего пространства с короткой страницей, в которой перечислены все пользовательские генераторы, их опции и примеры. Включите соглашения имен и определения тегов. Сохраните этот документ обновленным по мере развития рабочего пространства. Еще лучше, свяжитесь с ним с выхода команды или из сообщений об ошибках в правиле границы модуля.

Использование Nx Console для обнаружения

Nx Console — это плагин VS Code и JetBrains, который предоставляет графический интерфейс для запуска генераторов. Он автоматически перечисляет все генераторы из установленных плагинов, включая ваши собственные. Поощряйте свою команду использовать его — они могут точно видеть, что генератор создает перед его запуском, и схема подсказок делает варианты понятными. Это снижает барьер для принятия шаблонов.

Итеративный на основе обратной связи

Через несколько недель, собрать обратную связь от разработчиков: что генератор пропустил? Какую конфигурацию они должны были изменить вручную после генерации? Обновить генератор. Обработать генераторы как живой код, который развивается вместе с практикой команды. Nx позволяет легко обновлять их, потому что логика генератора контролируется версией и тестируется.

Измерение влияния последовательности

Как узнать, работают ли ваши пользовательские шаблоны и стандарты? Ищите эти ведущие показатели:

Отслеживайте эти показатели неофициально с вашей командой. Если вы используете инструмент, такой как Code Climate или панель приборов для задержки CI, вы можете получить объективные числа. Цель состоит не в том, чтобы достичь совершенства, а в том, чтобы постоянно уменьшать трение, вызванное непоследовательностью.

Заключение

Последовательность в монорепо не случайность; это результат преднамеренного инструментария и командной дисциплины. Nx дает вам возможность кодировать архитектурные решения вашей команды в генераторы, обеспечивать их с помощью подкладки и CI-воротов и развивать их по мере обучения вашей организации. Пользовательские шаблоны устраняют ручной, подверженный ошибкам шаг копирования и вставки старых проектов. Стандарты, применяемые и общая конфигурация предотвращают дрейф с течением времени. Инвестиции в строительство этих генераторов быстро окупаются, поскольку ваше рабочее пространство растет от десятков проектов до сотен. Начните с одного генератора, одного правила и одного шага CI. Оттуда ваша команда откроет свои собственные шаблоны для стандартизации - и Nx будет готов справиться с ними.