Настройка Spring Boot Starter

На этой странице показано, как подключить Axelix Spring Boot Starter к сервису на Spring Boot, чтобы Axelix Master мог обнаруживать его, считывать его состояние и взаимодействовать с ним — как через пользовательский интерфейс, так и через встроенный в Master сервер MCP (Model Context Protocol), который предоставляет те же данные агентам искусственного интеллекта. Выберите модуль стартера, соответствующий мажорной версии Boot, предоставьте доступ к Axelix actuator-эндпоинтам (начиная с Axelix 1.2.0 это происходит автоматически), поделитесь с Master ключом для подписи JWT и укажите Master, где найти сервис.

Прежде чем вы начнётеСкопировать ссылку на раздел

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

• Три модуля стартера, по одному для каждой мажорной версии Spring Boot. Выберите тот, который соответствует версии Boot, которую уже использует ваш сервис:
  • com.axelixlabs:axelix-spring-boot-2-starter — Spring Boot 2.7.x (это жёсткий минимум, а не просто версия, на которой мы тестировали; собран и протестирован с использованием 2.7.18, Spring Cloud 2021.0.9, минимальная версия JDK 11).
  • com.axelixlabs:axelix-spring-boot-3-starter — Spring Boot 3.x (собран и протестирован с использованием 3.0.13, Spring Cloud 2022.0.4, минимальная версия JDK 17).
  • com.axelixlabs:axelix-spring-boot-4-starter — Spring Boot 4.x (собран и протестирован с использованием 4.0.6, Spring Cloud 2025.1.0, минимальная версия JDK 17).
• Что добавляет стартер: набор Axelix-специфичных actuator-эндпоинтов (axelix-metadata, axelix-beans, axelix-loggers, …), JWT-фильтр авторизации, который ограничивает доступ к ним, и опциональный компонент саморегистрации, который объявляет сервис в Master.
• Плагин сборки Axelix также обязателен: помимо зависимости стартера, подключите Gradle- или Maven-плагин сборки Axelix. Он записывает координаты сборки (groupId/artifactId/version) в артефакт, а Master идентифицирует каждое приложение именно по этим координатам — сервис, собранный без плагина, не сможет зарегистрироваться. См. Что такое плагин сборки Axelix? и Настройка плагина сборки.
• Два потребителя одних и тех же данных: Master отдаёт пользовательский интерфейс Axelix по адресу / и сервер MCP по адресу /api/mcp (управляется axelix.master.mcp-server.enabled, по умолчанию включён). Оба считывают данные с тех же actuator-эндпоинтов, которые публикует стартер, — поэтому подключение стартера делает сервис видимым и для пользователей UI, и для MCP-клиентов без дополнительной настройки на стороне стартера.
• Что нужно Master для взаимодействия с сервисом: HTTP-доступность к базовому пути актуатора сервиса (по умолчанию /actuator), Axelix-эндпоинты, открытые через management.endpoints.web.exposure.include, и ключ для подписи JWT, идентичный тому, который настроен на Master — см. Аутентификация — JWT на стороне Master.
• Master может найти сервис двумя способами:
  • Автоматическое обнаружение на стороне Master — Master сканирует свою среду (в настоящее время — Kubernetes Services) и проверяет actuator-эндпоинт каждого из них. Стартеру нужно только предоставить доступ к эндпоинтам, ничего дополнительно настраивать не нужно.
  • Самостоятельная регистрация — стартер отправляет в Master heartbeat через фиксированный интервал. Используйте этот метод, если Master не может просканировать среду сервиса (другая сеть, отсутствие интеграции с платформой, обычные виртуальные машины).

Реактивные приложения (WebFlux)Скопировать ссылку на раздел

Начиная с Axelix 1.3.0, все три стартера работают в реактивных приложениях на Spring WebFlux, а не только в servlet-приложениях (Spring MVC). Стартер сам определяет, на каком веб-стеке работает приложение, поэтому ничего дополнительно добавлять или настраивать не нужно: зависимость, плагин сборки и свойства на этой странице одинаковы для обоих стеков. Axelix-эндпоинты и JWT-авторизация перед ними работают так же, в том числе когда Actuator запущен на отдельном management.server.port.

Одна функция по-прежнему работает только в servlet-приложениях. Мониторинг транзакций, а вместе с ним и страницы «Мониторинг транзакций» и «Карта сущностей», недоступны в WebFlux-приложениях.

Добавьте зависимостьСкопировать ссылку на раздел

Укажите координату стартера, соответствующую мажорной версии Boot.

dependencies {
    implementation("com.axelixlabs:axelix-spring-boot-4-starter:1.2.2")
}

Стартер также зависит от Spring Boot Actuator. Если в вашем сервисе ещё нет spring-boot-starter-actuator, добавьте его рядом.

Транзитивные зависимостиСкопировать ссылку на раздел

Стартер устроен так, чтобы добавлять в ваш classpath как можно меньше. Всё, с чем он интегрируется, — Spring Boot, Actuator, Spring Kafka, Micrometer, Caffeine, Jackson — используется только при компиляции стартера и не подтягивается вместе с ним: стартер работает с тем, что уже есть в вашем сервисе. Транзитивно он приносит только следующие библиотеки:

Этот список будет сокращаться. Стартер — единственный компонент Axelix, который работает внутри ваших сервисов, и каждая библиотека, которую он приносит, — это ещё одна зависимость в вашем classpath, которую нужно сканировать на уязвимости, обновлять и поддерживать совместимой с остальным приложением. Позиция core-команды Axelix такова: у стартера не должно быть внешних зависимостей вообще, и мы шаг за шагом убираем оставшиеся — за ходом работы можно следить в axelixlabs/axelix#1748.

JsonPath больше не подключаетсяСкопировать ссылку на раздел

До Axelix 1.1.x включительно стартер также подтягивал com.jayway.jsonpath:json-path, хотя сам его не использовал. Начиная с Axelix 1.2.0 эта зависимость удалена — это первый шаг к стартеру без внешних зависимостей, описанному в axelixlabs/axelix#1748.

Если ваш сервис использует JsonPath в собственном коде и получал его только через стартер Axelix, при обновлении объявите зависимость явно. Версией управляет Spring Boot, поэтому указывать её не нужно:

dependencies {
    implementation("com.jayway.jsonpath:json-path")
}

Тесты это не затрагивает: spring-boot-starter-test подключает JsonPath самостоятельно.

JSpecify больше не подключаетсяСкопировать ссылку на раздел

До Axelix 1.2.x включительно стартер также подтягивал org.jspecify:jspecify. Стартер использует JSpecify только ради аннотаций nullness, и нужны они ему только при компиляции. Начиная с Axelix 1.3.0 эта зависимость удалена — это следующий шаг к стартеру без внешних зависимостей, описанному в axelixlabs/axelix#1748.

Стартер продолжает работать без JSpecify в classpath, потому что JVM игнорирует аннотации, классы которых отсутствуют во время выполнения. На Spring Boot 4 ничего не меняется вовсе: Spring Framework 7 сам зависит от JSpecify.

Если ваш собственный код использует аннотации JSpecify и получал их только через стартер Axelix, при обновлении объявите зависимость явно. Spring Boot 2 и 3 не управляют её версией, поэтому укажите её:

dependencies {
    implementation("org.jspecify:jspecify:1.0.0")
}

Actuator-эндпоинтыСкопировать ссылку на раздел

Начиная с Axelix 1.2.0 ничего настраивать вручную не нужно: стартер сам добавляет свои actuator-эндпоинты в management.endpoints.web.exposure.include при старте приложения, поэтому Master получает к ним доступ «из коробки». На более старых версиях стартер этого не делает, и эндпоинты нужно перечислить вручную — см. Открытие эндпоинтов на Axelix ниже 1.2.0.

Что открывает стартерСкопировать ссылку на раздел

Стартер выставляет следующие эндпоинты:

В колонке С версии указан релиз стартера Axelix, в котором эндпоинт появился впервые. 1.0.0 — первый релиз Axelix, то есть эндпоинт с такой отметкой существует с самого начала. Версия с пометкой скоро ещё не выпущена: эндпоинт станет доступен в следующем релизе Axelix — минорном или мажорном, смотря какой выйдет раньше.

Эндпоинты, неприменимые к вашему сервису, остаются неактивными — стартер активирует каждый только при выполнении его предусловий (например, axelix-caches без CacheManager не поднимается).

Начиная с Axelix 1.2.0 стандартные эндпоинты health и info больше не требуются, поэтому стартер сам их не открывает (до 1.2.0 Axelix зависел от них, и стартер принудительно открывал оба). Открытыми будут только эндпоинты, перечисленные вами в management.endpoints.web.exposure.include, плюс эндпоинты Axelix — добавьте health и info в список сами, когда они вам нужны, в том числе health, который Spring Boot иначе открыл бы по умолчанию.

Эндпоинт axelix-feign удалёнСкопировать ссылку на раздел

До Axelix 1.2.x включительно стартеры для Spring Boot 3 и Spring Boot 4 добавляли ещё и эндпоинт axelix-feign, который возвращал список клиентов Spring Cloud OpenFeign вашего сервиса. Axelix Master ни разу не использовал его для отображения чего-либо, и эндпоинт оставался лишь наследием ранних дней проекта. Начиная с Axelix 1.3.0 эндпоинт удалён из стартеров — вместе со всем, что в Master умело его вызывать.

При обновлении ничего делать не нужно. Единственное видимое отличие: /actuator/axelix-feign больше не существует на сервисе со стартером 1.3.0 и новее, поэтому, если ваши собственные инструменты обращаются к этому URL напрямую, они получат 404. Если вы перечисляете эндпоинты Axelix в management.endpoints.web.exposure.include вручную и axelix-feign есть в этом списке, его можно убрать — оставить его там безвредно.

Добавление собственных эндпоинтовСкопировать ссылку на раздел

Если вам нужны свои actuator-эндпоинты, просто перечислите только их — стартер смёржит ваш список со своим, а не заменит его.

management:
  endpoints:
    web:
      exposure:
        include:
          - prometheus

В результате будет выставлен prometheus и все эндпоинты Axelix.

Значение * тоже поддерживается — тогда открывается всё, и стартер список не трогает.

Открытие эндпоинтов на Axelix ниже 1.2.0Скопировать ссылку на раздел

Стартеры старше 1.2.0 не добавляют свои эндпоинты в список открытых самостоятельно, поэтому каждый эндпоинт Axelix, который должен читать Master, нужно перечислить в management.endpoints.web.exposure.include вручную. Как минимум откройте axelix-metadata — без него инстанс никогда не появится в Master, — а на практике весь набор, чтобы у каждого раздела UI были данные. Эндпоинты health и info эти версии стартера открывают принудительно сами, так что их перечислять не нужно:

management:
  endpoints:
    web:
      exposure:
        include:
          - axelix-metadata
          - axelix-beans
          - axelix-caches
          - axelix-conditions
          - axelix-configprops
          - axelix-details
          - axelix-env
          - axelix-gc
          - axelix-heap-dump
          - axelix-loggers
          - axelix-metrics
          - axelix-scheduled-tasks
          - axelix-thread-dump

Эти версии стартера также добавляют устаревший эндпоинт axelix-feign. В список он не включён намеренно: Master его никогда не читает, а в Axelix 1.3.0 эндпоинт удалён — см. раздел Что открывает стартер.

Экспорт метрик Axelix через MicrometerСкопировать ссылку на раздел

Actuator-эндпоинт axelix-metrics нужен для пользовательского интерфейса Axelix. Кроме того, Axelix Spring Boot Starter может публиковать небольшой набор Axelix-специфичных метрик в MeterRegistry вашего приложения.

Этот путь экспорта включается автоматически, когда в приложении есть бин MeterRegistry. Отдельного свойства Axelix для включения данного функционала нет. Стартер регистрирует такие метрики:

Эти метрики дополняют UI-ориентированные actuator-эндпоинты, а не заменяют их. Пользовательский интерфейс по-прежнему читает axelix-metrics, axelix-caches и axelix-transactions-monitoring.

Поделитесь JWT-ключом подписи с MasterСкопировать ссылку на раздел

Каждый Axelix actuator-эндпоинт контролируется JwtAuthorizationFilter. Фильтр ожидает токен HS256, HS384 или HS512, подписанный тем же ключом, который использует Master, поэтому обе стороны должны согласовать алгоритм и секретный ключ. Используйте то же значение, которое вы указали для axelix.master.auth.jwt.signing-key на Master.

axelix:
  sbs:
    auth:
      jwt:
        algorithm: HMAC512
        signing-key: ${AXELIX_JWT_SIGNING_KEY}
        duration: 5m

duration определяет, как долго действителен выпущенный стартером токен для heartbeat-сигналов саморегистрации, по умолчанию он равен пяти минутам, после чего стартер автоматически его ротирует.

Запуск без ключа подписиСкопировать ссылку на раздел

Начиная с Axelix 1.2.0, algorithm и signing-key необязательны. Если они не заданы, стартер использует HMAC512 и тот же встроенный ключ, что и Master по умолчанию, поэтому сервис подключается к Master с настройками по умолчанию без настройки ключа. Пока используется встроенный ключ, стартер при старте пишет в лог предупреждение.

Дайте Master найти сервисСкопировать ссылку на раздел

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

Вариант A — автоматическое обнаружение на стороне MasterСкопировать ссылку на раздел

Если Master работает в кластере Kubernetes вместе с вашими сервисами, проще всего настроить его так, чтобы он сканировал namespace в поисках Services и опрашивал /actuator/axelix-metadata каждого из них. На стороне стартера не требуется никакой дополнительной настройки, помимо открытия actuator-эндпоинтов и общего JWT-ключа подписи. Настройте сканирование на стороне Master через axelix.master.discovery.auto.* — см. Обнаружение — автообнаружение на странице Master. Что Master делает при каждом сканировании, описано на странице Как работает обнаружение.

Вариант B — СаморегистрацияСкопировать ссылку на раздел

Если Master не может просканировать среду сервиса — другой кластер, обычная виртуальная машина, изолированная сеть — включите саморегистрацию в стартере. Сервис тогда отправляет в Master heartbeat со своим actuator URL через фиксированный интервал. Master принимает запрос по адресу POST /api/internal/service/register — это же значение указывается в axelix.sbs.discovery.master-url. Начиная с Axelix 1.3.0, стартер отправляет полную регистрацию только один раз, а затем переходит на лёгкие heartbeat-сигналы, которые уходят на эндпоинт рядом с master-url. Весь цикл описан на странице Как работает обнаружение.

axelix:
  sbs:
    discovery:
      self-registration: true
      master-url: http://master.internal:2935/api/internal/service/register
      instance-actuator-url: http://my-app.internal:8080/actuator
      instance-name: orders-service
      heartbeat-interval: 15s

Несколько деталей, на которых люди спотыкаются:

• instance-actuator-url — это базовый URL-адрес сервиса, поскольку Master будет обращаться к нему из своей собственной сети — только по имени хоста и порту.
• master-url — это полный URL-адрес, включая /api/internal/service/register. Стартер отправляет его без изменений. Начиная с Axelix 1.2.0 Master по умолчанию слушает порт 2935; до этого релиза портом по умолчанию был 8080 — см. Общие настройки.
• instance-name — это имя, которое Master показывает для этого сервиса в пользовательском интерфейсе и в MCP-ответах. Выбирайте имя, которое переживает рестарты и реплики, — как правило, имя сервиса, а не имя пода.
• Саморегистрация принимается Master из коробки (axelix.master.discovery.self-registration.enabled по умолчанию true), установите её в false, если хотите отказаться от heartbeat-сигналов. Master выселяет сервис после axelix.master.discovery.self-registration.eviction.heartbeat-timeout молчания (по умолчанию 45s), поэтому держите heartbeat-interval с запасом меньше этого значения.

Маскирование чувствительных значений свойствСкопировать ссылку на раздел

Эндпоинты Axelix axelix-env и axelix-configprops возвращают значения свойств в Master. Чтобы секреты не утекали при обычных просмотрах, стартер маскирует значения, которые он возвращает вызывающим без соответствующего полномочия. Механизм одинаков для обоих эндпоинтов и управляется одним свойством стартера:

axelix.sbs.endpoints.config.sanitized-properties

• Пустой список (по умолчанию) — каждое значение, возвращаемое axelix-env и axelix-configprops, заменяется на ****** для вызывающих без соответствующего полномочия. По умолчанию выбран намеренно консервативный вариант: чтобы быть в безопасности, ничего включать не нужно.
• Непустой список — маскируются только перечисленные ключи, всё остальное возвращается вызывающему без изменений. Используйте этот режим, если консервативное поведение по умолчанию слишком агрессивное и вы хотите маскировать только конкретные ключи (пароли, токены, ключи подписи).

Полномочие проверяется по каждому эндпоинту отдельно:

• axelix-env — полномочие ENV_VALUES_READ позволяет вызывающему видеть исходные значения.
• axelix-configprops — полномочие CONFIG_PROPS_VALUES_READ позволяет вызывающему видеть исходные значения.

Оба полномочия выдаются встроенными в Master ролями ADMIN и SUPER_ADMIN. VIEWER и EDITOR всегда проходят через функцию маскирования. Полную матрицу см. в Роли и полномочия.

axelix:
  sbs:
    endpoints:
      config:
        sanitized-properties:
          - database.password
          - spring.datasource.password
          - jwt.signing-key

Справочник по конфигурацииСкопировать ссылку на раздел

Все свойства стартера живут в пространстве имён axelix.sbs.*.

Отключение стартераСкопировать ссылку на раздел

axelix.sbs.enabled — глобальный переключатель всего стартера. По умолчанию он равен true, то есть достаточно добавить зависимость, чтобы активировать всё описанное на этой странице. Установите его в false — и каждая автоконфигурация Axelix отключится: не будет ни Axelix actuator-эндпоинтов, ни фильтра JWT-авторизации, ни heartbeat-сигналов саморегистрации, ни метрик Micrometer, ни мониторинга транзакций. Приложение запустится так, как будто стартера нет в classpath, при этом сама зависимость остаётся в сборке.

Этот переключатель пригодится, когда нужно выключить Axelix в конкретном окружении — например, локально или в тестовом профиле — не поддерживая отдельный набор зависимостей. Кроме того, это быстрый способ исключить стартер из подозреваемых при диагностике проблем на старте приложения.

axelix:
  sbs:
    enabled: false

Свойство читается один раз — при старте. Поэтому, чтобы изменение вступило в силу, приложение нужно перезапустить.

Аутентификация — JWTСкопировать ссылку на раздел

СаморегистрацияСкопировать ссылку на раздел

Саморегистрация выключена по умолчанию (axelix.sbs.discovery.self-registration=false) — оставьте всё как есть, если Master может найти сервис через автообнаружение на стороне Master.

Когда axelix.sbs.discovery.self-registration=true, следующие свойства становятся обязательными:

• axelix.sbs.discovery.master-url
• axelix.sbs.discovery.instance-actuator-url
• axelix.sbs.discovery.instance-name

Приёмник этих heartbeat-сигналов на стороне Master — эндпоинт, таймаут выселения, расписание подметания выселений — описан на странице Master в Обнаружение — саморегистрация. JWT-ключ подписи, заданный в axelix.sbs.auth.jwt.signing-key, должен совпадать с axelix.master.auth.jwt.signing-key на Master, иначе heartbeat-сигналы будут отклоняться с 401.

Маскирование значений в эндпоинтахСкопировать ссылку на раздел

Управление кэшамиСкопировать ссылку на раздел

Управление кэшами - это то, что обеспечивает работу страницы «Кэши» и метрик axelix_cache_*. Под капотом стартер оборачивает каждый бин CacheManager вашего приложения в прокси, который записывает обращения к кэшам и позволяет включать, выключать и очищать кэши во время работы приложения, а данные отдаёт через actuator-эндпоинт axelix-caches.

Эта функция включена по умолчанию, как только стартер оказывается в classpath.

Установите значение свойства axelix.sbs.cache.management.enabled в false, чтобы полностью её отключить, без проксирования CacheManager, без эндпоинта axelix-caches и без метрик кэшей. Ваши бины CacheManager при этом остаются ровно такими, какими их определило ваше приложение.

axelix:
  sbs:
    cache:
      management:
        enabled: false

Записи логовСкопировать ссылку на раздел

Эндпоинт axelix-logs отдаёт последние записи логов вашего приложения, поэтому их можно прочитать без доступа к хосту. Стартер хранит эти записи в памяти с момента запуска приложения. Когда буфер заполнен, каждая новая запись вытесняет самую старую. Поскольку буфер находится в памяти, после перезапуска он снова пуст.

По умолчанию стартер хранит последние 1000 записей. Увеличьте axelix.sbs.logs.max-entries, если нагруженный сервис пишет столько логов, что 1000 записей покрывают лишь несколько секунд. Уменьшите значение, если памяти мало: каждая хранимая запись остаётся в куче.

axelix:
  sbs:
    logs:
      max-entries: 5000

Мониторинг транзакцийСкопировать ссылку на раздел

Мониторинг транзакций — это то, что обеспечивает работу страницы «Мониторинг транзакций» и связанных метрик. Под капотом стартер оборачивает ваши @Transactional методы (путем обычного проксирования) с целью сбора различного рода инсайтов, случившихся в транзакции. Собранные инсайты передаются в Master внутри метаданных регистрации сервиса (которые отправляются либо в момент heartbeat в случае саморегистрации, либо сканируются Master-ом в момент автоматического обнаружения), поэтому отдельный actuator-эндпоинт для этого не требуется.

Эта функция включена по умолчанию, как только стартер оказывается в classpath.

Мониторинг транзакций работает только в servlet-приложениях (Spring MVC). В реактивном приложении (WebFlux) стартер его не включает, независимо от значения свойства. См. Реактивные приложения (WebFlux).

Несмотря на то, что overhead от этого проксирования крайне небольшой, если вдруг вы захотите отключить этот функционал - это можно сделать. Установите значение свойства axelix.sbs.transaction.monitoring.enabled в false, чтобы полностью её отключить — без bean post-processor'ов, без проксирования источника данных, без фильтра очистки и без интегратора Hibernate.

axelix:
  sbs:
    transaction:
      monitoring:
        enabled: false

Обнаружение in-memory paginationСкопировать ссылку на раздел

Обнаруживает случаи применения in-memory pagination, выполняемые Hibernate при использовании методов setFirstResult/setMaxResults совместно с выборкой коллекций через fetch.

По умолчанию мониторинг транзакций регистрирует appender, который перехватывает предупреждения Hibernate (HHH000104 в Hibernate 5.x и HHH90003004 в Hibernate 6.x–7.3.x). Стартер выбирает appender в соответствии с активной системой логирования приложения, поэтому обнаружение работает как на Logback, так и на Log4j2:

• Logback — стартер регистрирует com.axelixlabs.axelix.sbs.spring.core.persistence.hibernate.pagination.LogbackInMemoryPaginationAppender. Так происходит в стандартной конфигурации Spring Boot, где системой логирования является Logback.
• Log4j2 — если приложение использует Log4j2 (обычно после добавления spring-boot-starter-log4j2 и исключения стандартного стартера Logback), стартер регистрирует com.axelixlabs.axelix.sbs.spring.core.persistence.hibernate.pagination.Log4j2InMemoryPaginationAppender.

Выбирать между ними не нужно — стартер сам определяет активную систему логирования и регистрирует подходящий appender.

Установите значение свойства axelix.sbs.transaction.monitoring.in-memory-pagination-detection.enabled в false, если хотите отключить регистрацию любого из этих appender-ов.

axelix:
  sbs:
    transaction:
      monitoring:
        in-memory-pagination-detection:
          enabled: false

См. такжеСкопировать ссылку на раздел

• Настройка плагина сборки — вторая половина подключения сервиса; обязательна для регистрации сервиса.
• Настройка Master — где задаются ключ подписи, таймаут выселения и сканирование Kubernetes.
• Что такое Master? — фон того, как Master использует данные, которые публикует стартер.
• Аутентификация — углублённый взгляд на JWT и резолюцию полномочий с обеих сторон.