Режимы совместимости

Schema Registry не просто хранит схемы — он контролирует их эволюцию. При регистрации новой версии схемы Schema Registry проверяет её совместимость с существующими версиями согласно настроенному режиму. Если проверка не пройдена, HTTP 409 Conflict: новая версия отклонена.

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

Зачем нужны режимы совместимости

Без проверки совместимости любой разработчик может опубликовать любую схему. Команда потребителей узнаёт о breaking change только когда начинаются ошибки десериализации в production.

Schema Registry решает это через явную политику совместимости: перед приёмом новой версии схемы он проверяет, выполняются ли условия совместимости. Проверка происходит на стороне Schema Registry, до того как продюсер начнёт использовать новую схему.

Тест совместимости можно выполнить вручную через REST API, не регистрируя схему:

POST /compatibility/subjects/{subject}/versions/latest
Content-Type: application/vnd.schemaregistry.v1+json

{"schema": "...", "schemaType": "AVRO"}
# Ответ: {"is_compatible": true} или {"is_compatible": false, "messages": [...]}

BACKWARD (режим по умолчанию)

Определение: Новая схема может читать данные, написанные со старой схемой.

Направление читаемости: новый читатель — старые данные. Потребители обновляются первыми, до обновления продюсера.

Разрешённые изменения:

• Добавить поле с default (или с union ["null", type] + "default": null) — старые данные не содержат поле, но новый reader возьмёт default.
• Удалить поле, которое имеет default в новой схеме — reader просто не будет использовать это поле.

Запрещённые изменения:

• Добавить обязательное поле без default — новый reader не может прочитать старые данные, в которых поля нет.
• Переименовать поле (без alias) — новый reader не найдёт поле по имени.
• Изменить тип несовместимым образом — binary encoding не совпадёт.

Типичный use case: Микросервисная команда обновляет Consumer перед тем, как Producer начнёт отправлять новые поля. Consumer готов к новому формату заранее.

FORWARD

Определение: Старая схема может читать данные, написанные с новой схемой.

Направление читаемости: старый читатель — новые данные. Продюсеры обновляются первыми, до обновления потребителей.

Разрешённые изменения:

• Удалить поле — старый reader просто не знает об этом поле, использует default если есть.
• Добавить поле с default в новой схеме — старый reader игнорирует неизвестные поля (в Avro — unknown fields). Default в старой схеме не нужен.

Запрещённые изменения:

• Добавить обязательное поле без default в новой схеме — старый reader, читающий новые данные, не знает как обработать поле, которое есть в данных, но отсутствует в его схеме.

Типичный use case: CI/CD pipeline где продюсер деплоится независимо. Старые потребители должны продолжать работать с новым форматом данных.

FULL

Определение: Новая схема BACKWARD-совместима со старой И FORWARD-совместима со старой одновременно.

FULL — это пересечение условий BACKWARD и FORWARD. Это наиболее ограничительный режим из трёх.

Разрешённые изменения:

• Добавить поле с default — разрешено: удовлетворяет BACKWARD (новый reader читает старые данные, использует default) и FORWARD (старый reader игнорирует новое поле в новых данных).
• Удалить поле, если default присутствует в старой схеме — разрешено: BACKWARD (новый reader, читая старые данные, не видит поля, не нужен); FORWARD (старый reader, читая новые данные без удалённого поля, берёт default из своей схемы).

Запрещённые изменения:

• Добавить обязательное поле без default.
• Удалить поле без default.
• Любое изменение типа, кроме допустимых promotions.

Типичный use case: Rolling upgrade, когда старые и новые версии Producer и Consumer работают одновременно. Каждый должен уметь читать данные, написанные другой версией.

NONE

Определение: Никакая проверка совместимости не выполняется. Любая схема принимается.

NONE полностью отключает защиту Schema Registry от breaking changes.

Разрешено всё: Добавление обязательных полей, удаление любых полей, изменение типов, переименование — Schema Registry принимает любую схему.

Запрещено ничего: NONE = отсутствие контракта.

TRANSITIVE варианты

По умолчанию BACKWARD, FORWARD и FULL проверяют совместимость только с последней версией схемы (latest). Если у вас версии V1, V2, V3 — Schema Registry при регистрации V3 проверит только совместимость V3 с V2.

Это создаёт проблему: V3 совместима с V2, V2 совместима с V1, но V3 может быть несовместима с V1 напрямую. Потребитель, который по какой-то причине пропустил V2, получит данные V3, которые он не может прочитать.

TRANSITIVE-варианты решают это: проверка ведётся против всех предыдущих версий, не только последней.

Практическое значение FULL_TRANSITIVE: Гарантирует, что любой потребитель с любой предыдущей версией схемы сможет читать данные, написанные с любой версией схемы. Максимальная гарантия совместимости в системах с долгим retention.

Настройка режима совместимости

Глобально (для всех новых subjects):

PUT /config
{"compatibility": "FULL_TRANSITIVE"}

Переопределение для конкретного subject:

PUT /config/orders-value
{"compatibility": "BACKWARD"}

Читать текущую настройку:

GET /config/orders-value
# {"compatibilityLevel": "BACKWARD"}

GET /config
# {"compatibilityLevel": "FULL_TRANSITIVE"}

Если у subject нет собственной настройки, он наследует глобальную. Это позволяет установить строгий режим глобально (FULL_TRANSITIVE) и ослабить его для отдельных subjects, где это обосновано (например, development-only topics с NONE).

Таблица разрешённых изменений

Визуализация режимов