Что такое плагин сборки Axelix?

Плагин сборки Axelix — это небольшой Gradle или Maven-плагин, который вы подключаете к каждому сервису, которым хотите управлять через Axelix. Он выполняется во время сборки и записывает файл `META-INF/axelix-info.properties` внутрь артефакта вашего приложения. Этот файл несёт набор информации, по которой Master отличает одно приложение от другого.

Он дополняет Axelix Spring Boot Starter: стартер — это runtime-компонент, который общается с Master, а плагин сборки — это компонент времени сборки, который даёт стартеру, что передавать. Оба обязательны — сервис со стартером, но без плагина, не сможет зарегистрироваться.

Что он создаёт

Во время сборки плагин генерирует META-INF/axelix-info.properties и записывает:

Координаты сборки — groupId, artifactId и version. Именно на них Master завязывает всю идентификацию.
Отметку времени сборки — когда был собран артефакт.
Git-метаданные — если сборка выполняется внутри Git-репозитория, текущий коммит, ветку и автора.

Во время выполнения стартер читает этот файл и передаёт координаты в Master в составе метаданных регистрации сервиса.

SBOM зависимостей (Gradle)

Помимо файла axelix-info.properties, Gradle-плагин генерирует SBOM зависимостей — JSON-документ CycloneDX 1.6, описывающий граф runtime-зависимостей приложения. Он упаковывается в артефакт по пути META-INF/axelix/dependencies.cdx.json, рядом с build-информацией. Master читает его, чтобы понять, какие библиотеки приложение действительно поставляет и как каждая из них оказалась в classpath.

Документ создаёт задача generateAxelixDependenciesSbom. Запускать её вручную не нужно: jar, bootJar и processResources зависят от неё, поэтому обычная Spring Boot приложения упаковывает SBOM автоматически, а test и bootRun видят его в classpath. Задача перезапускается только тогда, когда меняется разрешённый граф зависимостей.

SBOM описывает полностью разрешённый runtimeClasspath — точный набор библиотек, который поставляется, а не версии, которые вы объявили:

Только разрешённые версии. Если две зависимости требуют разные версии одной библиотеки, в документ попадает версия, которую в итоге на самом деле выбрал Gradle. Динамические версии вроде 2.0.+ записываются как конкретная версия, в которую они в итоге разрешились (с учётом BOM-ом, т.е. platform(...)).
Runtime-область. Зависимости runtimeOnly включаются. Зависимости compileOnly не присутствуют в финальном артефакте, поэтому исключаются.
Пути разрешения. Каждая библиотека несёт связки dependsOn к библиотекам, которые она притянула, поэтому цепочка от вашего приложения до каждой транзитивной зависимости сохраняется (она нужна Axelix Master для построения дерева зависимости).
Ваши собственные модули не попадают в документ. В multi-project сборке подпроекты, от которых зависит приложение, не перечисляются как библиотеки — библиотеки, которые они притягивают, относятся напрямую к самому приложению. Каждый проект, подключивший плагин, получает собственный SBOM, описывающий его собственный runtime classpath.

Как и остальная часть плагина, SBOM не требует настройки. Сейчас его генерирует только Gradle-плагин; Maven-плагин его пока не создаёт.

Сгенерированные артефакты — внутренние

Всё, что плагин сборки записывает в ваш артефакт — META-INF/axelix-info.properties, SBOM зависимостей и любые файлы, добавленные в будущих релизах, — существует для единственного потребителя: Axelix Spring Boot Starter. Стартер читает эти файлы и передаёт их содержимое в Master. В этом и состоит весь контракт.

Не завязывайтесь на эти файлы

Считайте сгенерированные файлы внутренними артефактами Axelix. Их имена, расположение, формат и содержимое могут измениться в минорном или мажорном релизе без особого предупреждения, и такое изменение не считается ломающим. Если ваш собственный инструментарий извлекает из артефакта axelix-info.properties или dependencies.cdx.json и разбирает их, будьте готовы к тому, что он сломается при обновлении.

Особенно это касается SBOM зависимостей. Он использует стандартный формат CycloneDX, но генерируется под нужды Master — например, ваши собственные модули схлопываются и не попадают в граф. Это не SBOM уровня комплаенса, поэтому не отправляйте его в инструменты аудита или supply-chain-анализа.

Почему он обязателен

Master идентифицирует каждое приложение по его groupId + artifactId. Эти координаты — то, как он группирует сервисы, соотносит состояние и использует ключ для инсайтов по персистентности (анализ N+1 и маппинга сущностей).

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

Gradle и Maven

Плагин поставляется в двух вариантах, по одному на каждый инструмент сборки:

Gradle — плагин com.axelixlabs.axelix. Ему нужно лишь, чтобы были заданы стандартные group и version проекта; он завершает сборку с ошибкой, если group пуст, поскольку Axelix использует его, чтобы различать приложения.
Maven — axelix-maven-plugin, цель которого axelix-generate-project-info привязана к фазе prepare-package. В Maven координаты GAV есть всегда, поэтому ничего дополнительно настраивать не нужно.

Ни один из вариантов не имеет параметров конфигурации — вы его подключаете, и он делает свою работу. Gradle-вариант дополнительно генерирует SBOM зависимостей. Точные сниппеты см. в Настройка плагина сборки.

См. также

Настройка плагина сборки — как подключить его в Gradle или Maven.
Что такое Axelix Spring Boot Starter? — runtime-половина, которая читает и передаёт сгенерированные координаты.