Schema Registry и совместимость версий данных

Schema Registry, или реестр схем, хранит идентифицируемые версии описания данных и помогает управлять их использованием. Он нужен, когда несколько приложений независимо создают и читают сообщения, настройки или документы, а старая информация продолжает жить после выпуска новой версии.

Сначала определите, какую совместимость нужно сохранить: чтение старых данных новым потребителем, чтение новых данных старым потребителем или оба направления. Затем выберите формат схем, режим проверки, способ доставки и порядок активации. Реестр не исправляет смысл полей и не выполняет миграцию автоматически.

Результат — согласованный порядок изменения контракта: неизменяемые версии, перечень потребителей, проверки совместимости и поведения, управляемый выпуск и проверенный путь восстановления. Ниже разберём учебный пример JSON Schema, роли команды и условия, при которых достаточно Git и процесса поставки.

В распределённой системе производитель и потребитель данных могут выпускаться разными командами. Новая версия сервиса начинает отправлять поле, которого старый обработчик не знает, либо новый обработчик делает обязательным то, чего нет в истории. Реестр делает описание формата доступным по устойчивой идентичности и помогает контролировать изменения.

Конкретный продукт может называть логическую группу subject, schema group или иначе. Номер версии внутри группы и глобальный идентификатор схемы также могут быть разными сущностями. Сначала проверьте модель выбранного реестра. Например, Confluent Schema Registry API ↗ различает регистрацию, версии и получение схем.

Связь с Kafka и другими системами

Schema Registry — общая архитектурная роль и класс решений; реестр не становится частью Apache Kafka только из-за совместного использования. Реализации отличаются форматами, протоколом сериализации и способом доставки идентификатора схемы. Нельзя переносить детали одного продукта на любой API или очередь. В Azure Event Hubs ↗ реестр находится в отдельном продуктовом контексте со своей моделью групп и форматов.

Для небольшой системы может быть достаточно схем в Git, неизменяемого пакета релиза и явного выбора версии в приложении. Это уже управляемая доставка контрактов, если известны активная версия, потребители и процедура возврата. Отдельный сетевой сервис оправдан, когда нужны независимая регистрация, обнаружение версий или управление большим числом потребителей. Он добавляет эксплуатационные обязанности и не нужен автоматически.

Выбор способа хранения данных решается отдельно. Реестр не определяет, использовать ли JSONB в PostgreSQL, обычные колонки или EAV. Его задача — помочь воспроизводимо интерпретировать данные и управлять изменениями контракта.

Совместимость нужно определять относительно направления чтения. Формулировка «изменение обратно совместимо» без указания производителя, потребителя и поддерживаемых версий оставляет разные трактовки. Полезно сразу записать, какие сочетания должны работать во время перехода.

Эти направления описывают взаимодействие производителя и потребителя, а не обещают, что любые программы с валидным документом будут работать одинаково. Автоматический анализ зависит от формата и инструмента. В документации Confluent по эволюции схем ↗ для форматов выделены отдельные правила; правила Avro нельзя без проверки применять к JSON Schema.

Учебный пример закрытой JSON Schema

Рассмотрим условное правило оповещения из введения в JSON Schema. В версии 1 допустимы только enabled и threshold, оба поля обязательны, additionalProperties равно false. В версии 2 добавили необязательное поле channel со значениями email и webhook.

{
  "enabled": true,
  "threshold": 20,
  "channel": "email"
}

Старый документ без channel пройдёт новую схему. Но приведённый новый документ не пройдёт старую: она запрещает неизвестное поле. Значит, добавление необязательного свойства в этом примере сохраняет приём старых документов новым валидатором, но не гарантирует обратное направление. Совместимость определяется конкретными схемами и поведением клиентов.

default в JSON Schema не вставляет значение автоматически. Поэтому обязательное новое поле с default не делает прежние документы валидными без дополнительного поведения приложения. В Avro значение по умолчанию участвует в другом механизме чтения; одинаковое название не означает одинаковую семантику. Для JSON Schema это прямо объясняет руководство по аннотациям ↗.

Разделите подготовку, доставку артефакта и разрешение его использования. Успешная генерация документации не означает, что работающие приложения получили новую схему. Регистрация также не доказывает, что все потребители готовы к новым данным. Для вашего решения нужно явно определить, кто и когда выбирает версию.

1. Найдите влияние. Владелец перечисляет производителей, потребителей, сохранённые документы, сроки хранения и поддержку старых клиентов.
2. Подготовьте неизменяемую версию. Проверьте синтаксис, метасхему, компиляцию, ссылки и поддерживаемый профиль. Свяжите артефакт с изменением и описанием смысла.
3. Проверьте совместимость в обоих нужных направлениях. Автоматический анализ схем дополните примерами сообщений и тестами реальных потребителей. Корпус старых документов полезен, но не доказывает совместимость всех возможных значений.
4. Спланируйте переход. Определите порядок обновления приложений, чтение старых версий, миграцию истории и момент начала новых записей. Непрошедшая версия остаётся кандидатом.
5. Доставьте и активируйте. Убедитесь, что нужные приложения получили тот же артефакт. Используйте предусмотренный механизм выбора версии и зафиксируйте результат.
6. Проверьте работу и завершите переход. Наблюдайте ошибки и использование версий, выполните миграцию, затем прекращайте новые записи старого формата по согласованному правилу.

Пример с одной активной версией относится к каталогу конфигураций: приложение может выбирать её для новых объектов. В потоковой системе одновременно могут использоваться несколько разрешённых версий. Не навязывайте единый глобальный указатель «активная» там, где архитектура его не предполагает.

Почему проверка истории недостаточна

Можно проверить тысячу существующих документов и пропустить значение, которое допускает старая схема, но ещё не встречалось. Анализ совместимости ограничений и проверка корпуса данных отвечают на разные вопросы. Первый оценивает отношения между правилами, второй обнаруживает реальные данные и ошибки миграции. Тесты потребителей добавляют проверку поведения, включая смысл enum и единиц.

Формат версии в документе или сообщении должен позволять однозначно получить контракт. Это может быть поле конверта, заголовок протокола или идентификатор в согласованном формате сериализации. Не заменяйте эту связь догадкой по набору полей. Порядок и ошибки зафиксируйте в документации интеграций.

Реестр становится зависимостью системы, если приложение обращается к нему во время обработки. Определите, что происходит при недоступности: используется ли ранее проверенный локальный артефакт, на какой срок допустим кэш и как обрабатывается неизвестная версия. Молчаливый переход к произвольной последней схеме может изменить смысл проверки.

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

Неизменяемость версии помогает воспроизводимости: исправление схемы выпускается новым артефактом вместо тихой замены содержимого по прежнему идентификатору. Связанные схемы также должны разрешаться воспроизводимо. Контроль целостности полезен при доставке, но hash не заменяет описание изменений и решение об их допустимости.

Роли можно распределить без отдельного комитета. Аналитик согласует смысл полей и единиц; владелец данных — допустимые изменения и миграцию; архитектор — совместимость, границы и доступность; инженер — реализацию проверок, доставку и тесты. В небольшой команде один человек совмещает роли, но решения всё равно должны быть явными.

Схемы, загруженные внешними пользователями или плагинами, требуют ограничений ресурсов и проверки доверия. Поддерживаемые ключевые слова, форматы, расширения и разрешение ссылок составляют профиль системы. Один и тот же JSON Schema документ может по-разному обрабатываться при разных настройках default, format и преобразования типов.

• Описан один логический контракт и определены его производители, потребители и владелец.
• Для каждого поддерживаемого формата указан диалект или версия и настройки инструментов.
• Есть неизменяемые артефакты версий и воспроизводимое разрешение ссылок.
• Определены направления и глубина проверки совместимости.
• Подготовлены позитивные и негативные примеры, проверки старой истории и тесты потребителей.
• Согласованы порядок выпуска, миграция, наблюдение ошибок и восстановление после сбоя.

Ошибки, которые стоит обнаружить заранее

Частые ошибки — смешивать регистрацию с активацией, проверять только соседнюю версию при долгом хранении истории, считать необязательное поле всегда безопасным и применять правила Avro к JSON Schema. Также опасно менять содержимое уже используемой версии и откатывать приложение без проверки новых документов.

Ещё одна ошибка — строить отдельный сервис реестра без потребности в независимом управлении. Если команды выпускаются вместе, достаточно небольшой системы и понятного процесса поставки. Если потребители обновляются независимо, экономия на описании версий быстро оборачивается ручным согласованием и поиском скрытых зависимостей. Решение следует привязать к реальному порядку выпуска.

Итоговый артефакт — карта контрактов и версий, матрица совместимости, план перехода и результаты проверок. Этот пакет позволяет согласовать изменение до включения нового формата. Если переносится история, дополните его планом миграции и сверки данных.