Старые потребители ещё не обновлены после изменения публичного контракта модуля. Как организовать эволюцию, чтобы не требовать одновременного релиза?
Нужно сохранять обратную совместимость контракта: сначала добавлять новые возможности без удаления и изменения смысла старых, а несовместимые изменения проводить через версионирование, адаптер или переходный слой. Тогда старые потребители продолжают работать, пока новые постепенно переходят на обновлённый контракт.
В распределённых и модульных системах независимые компоненты редко выпускаются одновременно. Контракт между ними становится отдельной архитектурной границей, поэтому изменение его структуры может затронуть множество команд и релизных циклов.
Подходы к совместимой эволюции появились как ответ на риск массовой синхронизации релизов. Их цель — уменьшить связанность во времени: поставщик и потребитель могут обновляться независимо, если временно поддерживается общий набор правил взаимодействия.
Предположим, модуль публикует контракт, которым пользуются несколько приложений. Если переименовать поле, изменить его тип, удалить значение или поменять смысл существующей операции, старые потребители могут начать ошибаться ещё до собственного обновления.
Особенно опасны изменения, которые формально выглядят небольшими: обязательное новое поле, другой формат даты, изменение семантики пустого значения или замена ошибки успешным ответом. Неверная стратегия приводит к связанным релизам, простою, сложному откату и необходимости заранее координировать всех потребителей.
Базовое правило — сначала расширять, потом переключать, затем удалять. Новое необязательное поле или операция добавляются так, чтобы старые потребители могли их игнорировать, а поставщик некоторое время продолжает поддерживать прежнее поведение.
Для несовместимых изменений применяют несколько механизмов. Версионирование позволяет явно поддерживать старый и новый контракт; адаптер преобразует старый формат во внутреннюю модель поставщика; переходный слой направляет потребителей к нужной версии и помогает контролировать миграцию.
Совместимость бывает не только синтаксической. Нужно сохранять смысл операций, допустимые диапазоны значений, правила обязательности полей, семантику ошибок, порядок обработки и идемпотентность, если она является частью ожиданий потребителя.
Поставщик должен измерять использование старой версии, объявлять срок её поддержки и удалять её только после подтверждённой миграции. Полезны контрактные тесты от потребителей, проверка неизвестных полей, наблюдаемость по версиям и автоматические предупреждения о deprecated-возможностях.
Есть компромисс между длительной поддержкой версий и сложностью кода. Слишком раннее удаление ломает потребителей, а бесконечное сохранение старых вариантов увеличивает стоимость тестирования и риск расхождения поведения. Поэтому версия должна иметь владельца, срок перехода и понятные критерии вывода из эксплуатации.
Платёжный модуль возвращал сведения о способе оплаты. Требовалось добавить несколько способов, не останавливая старые версии мобильного приложения и отчётного сервиса.
Рассматривались три варианта. Немедленно изменить существующее поле означало простой и синхронный релиз всех потребителей. Полностью выпустить новый контракт без поддержки старого упрощало реализацию поставщика, но переносило риск на потребителей и требовало координации.
Выбрали переходный вариант: сохранить старое поле и его смысл, добавить новые необязательные данные, а для несовместимой структуры предоставить новую версию контракта. Поставщик преобразовывал старый запрос во внутреннюю модель, собирал метрики по версиям и объявил дату прекращения старого варианта.
Это позволило обновлять потребителей поэтапно. После того как использование старой версии стало нулевым и контрактные проверки подтвердили миграцию, переходный код удалили отдельным изменением.
1. Достаточно ли добавить новую версию контракта, чтобы обеспечить безопасную миграцию?
Нет. Версия сама по себе лишь разделяет варианты интерфейса. Нужно определить правила совместимости, поддерживать обе версии в переходный период, проверить реальные сценарии потребителей, настроить наблюдаемость и назначить условия удаления старой версии.
Если новая версия сохраняет тот же внешний формат, но меняет смысл поля или порядок побочных эффектов, формальная нумерация не устраняет семантическую несовместимость. Поэтому контрактные тесты должны проверять не только структуру сообщений, но и ожидаемое поведение.
2. Когда аддитивное изменение всё равно может сломать старого потребителя?
Например, если потребитель не игнорирует неизвестные поля, строго сравнивает весь объект, считает любое новое значение ошибкой или использует схему с запретом дополнительных атрибутов. Также опасно добавление нового значения в перечисление, если потребитель предполагает, что набор вариантов закрытый.
Следовательно, безопасное расширение зависит от реального поведения потребителей. Нельзя считать изменение обратно совместимым только потому, что старые поля и операции формально не удалены.
3. Чем отличается совместимость контракта от совместимости реализации поставщика?
Поставщик может полностью переписать внутреннюю реализацию, сохранив внешний контракт и его семантику. В таком случае потребителям не требуется изменение, потому что граница изолирует внутреннюю эволюцию.
Обратная ситуация тоже возможна: реализация почти не меняется, но изменяется формат ошибки, обязательность поля или смысл результата. Тогда контракт нарушен, даже если внутренний код кажется прежним. Поэтому совместимость оценивают по наблюдаемому поведению через границу, а не по устройству реализации.