Настройка 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 не может просканировать среду сервиса (другая сеть, отсутствие интеграции с платформой, обычные виртуальные машины).

Добавьте зависимость

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

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

Стартер также зависит от 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.

Вариант B — Саморегистрация

Если Master не может просканировать среду сервиса — другой кластер, обычная виртуальная машина, изолированная сеть — включите саморегистрацию в стартере. Сервис тогда отправляет в Master heartbeat со своим actuator URL через фиксированный интервал. Master принимает запрос по адресу POST /api/internal/service/register — это же значение указывается в axelix.sbs.discovery.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.

Несмотря на то, что 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 и резолюцию полномочий с обеих сторон.