Совместимость и версионирование

На этой странице описано, как версионируется сам Axelix и как он остаётся совместимым с основными участниками процесса: версией Java, на которой работают ваши сервисы, мажорной версией Spring Boot, под которую они собраны, и как собственные компоненты Axelix остаются совместимыми друг с другом.

Одна версия для всех компонентов

Axelix выпускается как единый, согласованный дистрибутив. Все компоненты имеют ровно одну и ту же версию.

Когда выходит новый дистрибутив Axelix — скажем, Axelix OSS 3.1.2 — каждый выпущенный компонент несёт эту же версию 3.1.2:

Spring Boot-стартеры (публикуются как Maven-артефакты);
плагины (тоже публикуются как Maven-артефакты);
Axelix Master как standalone JAR;
Axelix Master как Docker-образ.

Независимого версионирования по компонентам нет. Если вы знаете версию одного артефакта Axelix, вы знаете версию их всех в этом релизе.

Это верно и для патч-релизов: патч перевыпускает весь флот под версией X.Y.Z, срезаясь из патч-ветки минорной линии — см. Модель ветвления и Релизы о том, как делаются эти срезы.

Отдельный стартер под каждую мажорную версию Spring Boot

Axelix поставляет отдельный стартер под каждую мажорную версию Spring Boot. Для каждой поддерживаемой мажорной версии существует самостоятельный, отдельный артефакт:

axelix-spring-boot-2-starter — для сервисов на Spring Boot 2.x;
axelix-spring-boot-3-starter — для сервисов на Spring Boot 3.x;
axelix-spring-boot-4-starter — для сервисов на Spring Boot 4.x.

На данный момент Axelix поддерживает Spring Boot мажорных версий с 2 по 4. Выбирайте стартер, соответствующий мажорной версии Spring Boot вашего сервиса.

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

Gradle-плагин протестирован на мажорных версиях Gradle с 5 по 9;
Maven-плагин совместим с Maven 3 (именно его сегодня использует практически любой Maven-проект, так что всё хорошо).

Минимальная версия Spring Boot 2 — 2.7.x

axelix-spring-boot-2-starter поддерживает Spring Boot 2 начиная с версии 2.7, а не всю линейку 2.x. Если ваш сервис на более ранней версии Spring Boot 2.x — некоторые сервисы работают вплоть до 2.5.15 — перед подключением Axelix нужно обновиться как минимум до Spring Boot 2.7.

Совместимость с версиями Java

Axelix Master — это сам по себе Spring Boot-приложение, написанное на Java 25. Это важно только в случае, если вы хотите запускать Axelix Master как JAR. В любом другом случае разницы нет.

Стартеры следуют совместимости по Java той версии Spring Boot, под которую они собраны. Каждый стартер совместим с любой версией Java, которая поддерживается данной мажорной версией Spring Boot. Например, Spring Boot 3 поддерживает как минимум Java 17 и вплоть до Java 25 (в Spring Boot 3.5) — и axelix-spring-boot-3-starter следует ровно тому же диапазону. Он тоже тестируется на всех версиях от Java 17 до Java 25.

Минимальная версия Java — 11

Единственное исключение из правила «следуем за поддержкой Java у Spring Boot» — это жёсткий минимум Java 11 для стартеров и плагинов Axelix. Пользователи Spring Boot 2, которые теоретически ещё могут быть на Java 8, не смогут использовать Axelix — им нужно обновиться как минимум до Java 11.

Совместимость между компонентами

Axelix выпускается синхронно (lockstep), но ничто не заставляет вас и обновляться синхронно: в реальном флоте вы можете поднять Master до последнего патча раньше, чем догонят сервисы, или обновить стартер одного сервиса, пока всё остальное стоит на месте. Для таких смешанных развёртываний есть одно правило, и оно применяется к каждому компоненту Axelix:

Любые два компонента Axelix гарантированно совместимы до тех пор, пока у них одна и та же мажорная и минорная версия. Патч-версия не имеет значения.

Это весь контракт. Он покрывает сразу все пары — Master со стартером, стартер со своим плагином, все вместе — так что матрица совместимости вам никогда не понадобится. Просто выровняйте major.minor.

✅ Master 1.4.2, стартер 1.4.5, плагин 1.4.0 — все на 1.4, гарантированно совместимо.
✅ Стартер 1.4.3 с плагином 1.4.0 — та же 1.4, гарантированно совместимо.
⚠️ Master 1.4.2 со стартером 1.3.4 — минорное расхождение, не гарантируется. Может сработать, может сломаться.
⚠️ Стартер 3.1.x с плагином 3.3.x — минорное расхождение, не гарантируется и не поддерживается.
⚠️ Любое мажорное расхождение — не гарантируется и ещё менее вероятно сработает, чем минорное.

Если компоненты расходятся на минорной или мажорной версии, мы не гарантируем ничего — комбинация может сработать, но может и сломаться, и она не тестируется. Самая простая политика — и та, которую синхронные релизы делают тривиальной — держать всё на одной и той же точной X.Y.Z; но реальный контракт — это только major.minor.

Почему патч-расхождение безопасно, а минорное/мажорное — нет

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

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

Минорное и мажорное расхождение может сломать протоколы взаимодействия

Мы можем — это не значит, что мы будем, но мы можем — пересматривать протоколы между компонентами (Master ↔ стартер, плагин ↔ стартер) между минорными релизами, не говоря уже о мажорных. Это значит, что любая комбинация, пересекающая минорную границу, может сломаться. Это не значит, что она сломается — но она может, и обратного мы не гарантируем. Держите каждый компонент на одной мажорной и минорной версии, и позволяйте расходиться только патч-версиям.

Гарантии обратной совместимости между релизами

Axelix Master

Axelix Master — это Java-приложение, которое предполагается запускать как самостоятельный процесс: в Kubernetes, в Docker или просто как JAR. Использовать его как библиотеку не предполагается. Поэтому мы не считаем публичную поверхность Java публичным контрактом: публичные классы, публичные методы, конструкторы, поля, enum-ы и константы — всё это считается внутренним.

На практике это значит, что мы можем менять этот публичный Java API в минорных и даже патч-релизах. Предполагается, что никто не зависит от Master как от библиотеки, поэтому свобода менять его Java API позволяет нам разрабатывать быстрее. Это осознанный компромисс, который реально почти никого не затрагивает — большой плюс для темпа развития проекта.

А вот что мы считаем публичным контрактом Master — это его конфигурацию:

имена свойств — как для Helm-чарта Axelix Master, так и для запуска Axelix Master как standalone JAR;
их значения по умолчанию;
их типы.

Всё это будет меняться только в мажорных релизах.

Правило для Master

Полагайтесь на свойства Master (имена, значения по умолчанию, типы) — они стабильны в пределах мажорной версии. Не полагайтесь на Java-классы, методы и прочие элементы уровня кода в Master — они могут меняться в любом релизе.

Стартеры

Стартеры действительно используются как библиотеки — это Spring Boot-стартеры, поэтому они приносят в ваше приложение auto-configuration'ы с бинами (bootstrap-обвязку, внутреннюю стратегию проксирования и так далее). Из этой реальности вытекают два правила.

Не переопределяйте бины Axelix. Мы намеренно не даём конечным пользователям переопределять внутренние бины, которые объявляет Axelix, чтобы вмешиваться в процесс bootstrap, стратегию проксирования и подобные внутренности. Это осознанный выбор. Axelix изо всех сил старается не добавлять никакого ощутимого оверхеда вашему приложению и быть максимально эффективным и стабильным; возможность переопределять бины вроде BeanPostProcessor-ов или экземпляров ProxyFactoryBean открыла бы backdoor для трудноуловимых багов и худшей производительности. Поэтому, пожалуйста, не пытайтесь подменять бины Axelix. С огромной вероятностью вы не сделаете лучше - вы сделаете хуже.

Не завязывайтесь на публичный Java API стартера. Приходится признать, что стартеры работают внутри реальных приложений, поэтому их публичный Java API технически можно использовать из вашего кода — но это не предполагается, и мы настоятельно не советуем так делать. Чтобы двигаться быстро и оставаться конкурентоспособными, мы можем менять публичный Java API и в стартерах. Мы будем избегать этого любой ценой, но если сочтём необходимым — можем изменить его в рамках минорного апгрейда версии.

Не хватает возможности? Заведите issue, а не тинкерите

Правило простое: если вам чего-то не хватает или нужна какая-то возможность — не тюнтье стартер, а заведите issue в нашем трекере на GitHub. Мы обещаем, что рассмотрим. Когда мы добавим запрошенную вами возможность, мы дадим вам свойство для управления этим поведением — стабильную, поддерживаемую настрокйу, а не переопределение бина или зависимость на уровне кода.