API-Driven Versioning

Здесь представлено мое видение идеального версионирования в микросервисной архитектуре. Зачем мне своя стратегия версионирования, почему просто не использовать Семантическое версионирование?

Обычное семантическое версионирование (SemVer) нацелено на совместимость и использует три разряда:

1. Мажор (x) — обратно несовместимые изменения.
2. Минор (y) — новые возможности или изменения, сохраняющие совместимость.
3. Патч (z) — исправления ошибок, не затрагивающие функциональность.

Однако, в микросервисных или event-driven архитектурах может возникнуть желание разделить изменения внешних контрактов и внутренних правок, а также явно выделять хотфиксы для уже выпущенных версий. Именно для таких случаев предлагается мое версионирование

Версия состоит из 4 разрядов:

 MAJOR.MINOR.PATCH.HOTFIX

• MAJOR — меняется при обратно несовместимых изменениях внешних контрактов (API, Kafka-event, grpc proto).
  • Например, удаление или серьёзное изменение полей в API, которое требует модификации клиентского кода.
• MINOR — меняется при обратно совместимых изменениях внешних контрактов.
  • Например, добавили новое поле в API или Kafka-событие, не ломая существующих потребителей.
• PATCH — меняется при внутренних изменениях, не влияющих на внешний контракт.
  • Например, логика сервиса, оптимизация производительности, рефакторинг без изменения API.
• HOTFIX — меняется при оперативном исправлении критических ошибок, которое делается в рамках уже выпущенной версии.
  • Например, вышла версия 2.7.0, и в ней обнаружился баг. Если нельзя сразу перескочить на 2.7.1, мы выпускаем 2.7.0.1 (и при необходимости 2.7.0.2, 2.7.0.3 и т.д.).

Пример наглядно

• 3.2.0.0: крупный релиз (MAJOR = 3) без хотфиксов, MINOR = 2, PATCH = 0.
• 3.2.1.0: небольшое улучшение логики (PATCH).
• 3.2.1.1: хотфикс для версии 3.2.1.
• 3.3.0.0: добавили новое поле в API (MINOR).
• 4.0.0.0: убрали/изменили поле API (ломка совместимости), MAJOR стал 4.

Преимущества

1. Явное отображение изменений в API. Клиенты легко ориентируются, что MAJOR или MINOR рост — это сигналы о новых (или изменённых) контрактах, тогда как PATCH говорит о внутренних улучшениях.
2. Чёткая политика хотфиксов
   • Наличие четвертого разряда (HOTFIX) упрощает понимание, куда вкатывается критический фикс.
   • Если у заказчика стоит 2.7.0, мы можем сразу дать ему версию 2.7.0.1 (и не трогать общую линейку, которая пошла дальше до 2.7.1 и т.д.).

Недостатки и подводные камни

1. Несовместимость со стандартными инструментами SemVer. Большинство пакетных менеджеров и CI/CD систем ориентируются на трёхразрядную схему. Вам может понадобиться дополнительная настройка, если логика инструментов «не понимает» четвёртого разряда.
2. Сложность в обучении внешних клиентов. Если ваш сервис используют сторонние разработчики, им нужно будет объяснять, что значит четвёртая цифра, почему у вас два патч-уровня (PATCH/HOTFIX), и как читать изменения MAJOR/MINOR.
3. Параллельная поддержка нескольких веток. Принцип «четвёртой цифры» даёт возможность выпускать хотфиксы для старых версий, но это накладывает обязательство поддерживать эти ветки. Нужно чётко описать правила (например, «поддерживаем не более двух последних MINOR-линеек»).

Дополнительные рекомендации:

• Если есть проблемы c CI/CD, возможно, стоит использовать build-метаданные SemVer (например, 2.7.0+hotfix.1) — так сохраняется совместимость, но вы всё равно видите четвёртый «уровень» версии.
• При любом релизе (любого разряда) фиксируйте в ChangeLog, что именно изменилось. Это особенно важно в микросервисах, чтобы быстро понимать, затрагивает ли обновление API клиентов.

Мета информация

Область::
Родитель::
Источник::
Создана:: 2025-03-07
Автор::

Дополнительные материалы

Дочерние заметки