Настройка Schema Registry compatibility выглядит как галочка в конфигурации, но на деле она решает, в каком порядке команды должны выкатывать продюсеров и консьюмеров. Если порядок не совпал с допущением режима, проверка пропустит схему, а сообщения упадут уже в проде. Разберём реальный инцидент из чужого блога, выясним, какой вопрос задаёт каждый режим, воспроизведём падение на стенде и добавим проверку схемы в CI до релиза.
Что случилось на складе в Лидсе
Исходник это заметка инженера Сергея Шиндера (Sergey Shinder) на dev.to под названием The schema registry approved a change that only worked if we deployed first. Автор рассказывает, как сбор заказов для перевозчиков со склада в Лидсе ушёл наполовину пустым, и около шести тысяч собранных заказов ночь пролежали на доке. Заказы собрали, упаковали и объявили в Kafka как обычно, но интеграция с перевозчиками сложила каждое объявление в топик недоставленных сообщений (dead letter queue, DLQ) как нечитаемое.
Все сообщения в Avro, схемы лежат в Confluent Schema Registry. Консьюмер использует классы, сгенерированные из схемы на момент последней сборки. Команда склада выкатила версию без поля depot_code, а в схеме консьюмера у этого поля не было default. Avro может разрешить запись с отсутствующим полем, только если схема читателя говорит, чем его заполнить, поэтому все сообщения после двух часов дня не десериализовались.
Реестр принял схему, потому что subject работал в режиме по умолчанию, BACKWARD. Этот режим отвечает на вопрос, сможет ли консьюмер на новой схеме прочитать данные по старой, и удаление поля эту проверку проходит легко. Но проверка молча допускает, что консьюмеры переходят на новую схему раньше продюсеров. Консьюмеры самой команды склада так и сделали, а интеграция перевозчиков жила в другой команде с другим циклом релизов, и реестр о ней ничего не знал. Нужен был обратный вопрос, а это FORWARD, и он отклонил бы удаление поля без default.
Автор после инцидента перевёл каждый subject с внешним консьюмером в FULL_TRANSITIVE, вернул поле с default и стал задавать default для каждого читаемого поля. DLQ теперь поднимает тревогу на первом сообщении, а не на тысячном.
Исходник не называет язык консьюмера, поэтому поведение воспроизведём на Python и fastavro. Формат DLQ автор тоже не описал, так что устройство DLQ ниже придумано нами.
Совместимость отвечает на вопрос о порядке деплоя
Главная мысль исходника шире конкретного инцидента. Режим совместимости не оценивает качество схемы, он формально записывает допущение о том, кто обновляется первым. Реестр сравнивает пары схем и не знает ни о ваших командах, ни о релизных окнах. Если допущение режима не совпадает с реальностью, проверка бесполезна.
Как Avro читает данные
Бинарный Avro не содержит имён полей и типов, поэтому читатель всегда нуждается в схеме. По спецификации Avro лучше всего читать данные той же схемой, которой их записали. Если схема читателя другая, нужны обе схемы, схема писателя (writer schema) и схема читателя (reader schema), и Avro разрешает расхождения между ними (schema resolution).
В Confluent-сериализаторах сообщение начинается с нулевого байта и четырёх байтов с идентификатором схемы в реестре, дальше идут данные Avro. Идентификатор позволяет консьюмеру запросить схему писателя из реестра. Поле, которое есть у писателя, но нет у читателя, читатель пропускает. Поле, которое есть у читателя, но нет у писателя, читатель заполняет значением default из своей схемы, а если default нет, чтение падает. Спецификация уточняет, что default используется только при чтении экземпляров без поля и необязательным поле при кодировании не делает.
Отсюда прямое следствие для инцидента. Удаление поля без default безопасно для новых читателей, потому что они просто пропустят лишнее. Для старых читателей оно опасно, потому что им нечем заполнить недостающее. Документация Confluent приводит тот же пример, где удаление поля favorite_number без default несовместимо вперёд с исходной схемой.
Семь режимов совместимости и порядок обновления клиентов
Режимов семь, и различаются они двумя осями. Первая ось задаёт направление проверки, то есть кто читает чьи данные. Вторая ось задаёт глубину, то есть сравнивается ли новая схема только с последней версией или со всей историей subject (transitive). Документация Confluent по реестру отдельно оговаривает, что BACKWARD по умолчанию нетранзитивный, поэтому новая схема сверяется только с последней версией.

В таблице собраны режимы, вопрос каждого из них, глубина сравнения и порядок деплоя по документации Confluent. В двух столбцах про поле без default каждая ячейка помечена. Пометка «стенд» значит, что результат получен прогоном на нашем реестре, пометка «выведено» значит, что значение мы вывели из правил разрешения схем Avro и определений режимов, а прогон его не проверял. Под удалением понимается удаление поля, у которого в последней версии нет default.
| Режим | Вопрос проверки | Сравнение с | Кто обновляется первым | Удалить поле без default | Добавить поле без default | Типичный сценарий |
|---|---|---|---|---|---|---|
| BACKWARD | Новый читатель читает старые данные | Последняя версия | Консьюмеры | Да (стенд) | Нет (выведено) | Режим по умолчанию, перемотка консьюмеров на начало топика |
| BACKWARD_ |
Новый читатель читает данные всех версий | Все версии | Консьюмеры | Да (выведено) | Нет (выведено) | Рекомендация документации для Protobuf, читатель на новой схеме должен понимать всю историю |
| FORWARD | Читатель на последней схеме читает новые данные | Последняя версия | Продюсеры | Нет (стенд) | Да (выведено) | Логика консьюмеров привязана к определённой версии схемы |
| FORWARD_ |
Читатели на всех версиях читают новые данные | Все версии | Продюсеры | Нет (выведено) | Да (выведено) | Старые консьюмеры любой давности должны пережить новую схему |
| FULL | Оба направления | Последняя версия | Любой, независимо | Нет (выведено) | Нет (выведено) | Команды выкатываются независимо друг от друга |
| FULL_TRANSITIVE | Оба направления | Все версии | Любой, независимо | Нет (стенд) | Нет (стенд) | Консьюмер вне владеющей команды, выбор автора исходника |
| NONE | Проверок нет | Не сравнивается | Нужна осторожность, порядок определяют сами | Не проверяется (документация) | Не проверяется (документация) | Несовместимое изменение, документация советует новый топик |
Прогон подтвердил четыре ячейки. Удаление поля без default реестр пропустил в BACKWARD, отклонил в FORWARD и отклонил в FULL_TRANSITIVE (основной прогон, в истории одна версия). Добавление поля без default в FULL_TRANSITIVE отклонено в задании 2. Остальные ячейки прогон не проверял. Значения «Да» для BACKWARD_TRANSITIVE и FORWARD_TRANSITIVE, добавление без default в других режимах и удаление без default в FULL выведены из правил Avro. Задание 1 показывает соседний сценарий, где у поля в последней версии default уже есть, и это другие условия, поэтому к ячейкам таблицы мы его не относим.
Таблица читается так. BACKWARD удобен тем, что консьюмера можно перемотать на начало топика и прочитать всю историю новой схемой, поэтому он и стоит по умолчанию. Цена в том, что продюсеров нельзя выпускать раньше консьюмеров, и это ровно то допущение, которое сломалось на складе. FORWARD требует обратного порядка и, по словам документации, не гарантирует чтения старых сообщений, поэтому работать с ним сложнее, чем кажется. FULL и FULL_TRANSITIVE снимают вопрос о порядке, но разрешают только добавление и удаление полей с default.
У транзитивных режимов есть оборотная сторона. Они помнят всю историю subject, так что поле без default, однажды попавшее в версию 1, продолжает мешать удалению и в версии 10. Это мы проверим на стенде в первом задании.
Отдельное замечание касается Kafka Streams. Документация Confluent формулирует требования к режимам для него неоднозначно. В одном месте сказано, что поддерживается только BACKWARD, в другом перечислены FULL, FULL_TRANSITIVE и BACKWARD, а BACKWARD_TRANSITIVE названа всегда поддерживаемой как более строгая. Надёжный ориентир такой. Берите BACKWARD или режим, который его включает, и обновляйте приложения Streams раньше продюсера, пишущего во входной топик. Приложения на этой библиотеке подробно разбираем на курсе Kafka Streams для разработчиков.

Стенд, воспроизводим инцидент и отклонение схемы
Стенд состоит из брокера Apache Kafka 4.3.2 в режиме KRaft и Schema Registry из образа cp-schema-registry 7.8.0. Реестр не входит в Apache Kafka, это отдельный компонент Confluent. Выпуск 7.8.0 относится к линейке Confluent Platform на базе Kafka 3.8, поэтому пара с брокером 4.3.2 не рекомендована производителем. Для наших проверок это допустимо, потому что реестр только хранит схемы в служебном топике и отвечает по REST. Но выводы ниже относятся именно к этой паре, а на актуальных выпусках Confluent Platform стенд не гонялся. REST-вызовы совместимости в текущей документации описаны так же, но тексты сообщений об ошибках могут отличаться. Суммарный лимит памяти 2 ГБ, порты только на 127.0.0.1. Клиентский код работает в виртуальном окружении на хосте.
# compose.yaml · apache/kafka 4.3.2 · cp-schema-registry 7.8.0
services:
kafka:
image: apache/kafka:4.3.2
mem_limit: 1g
ports:
- "127.0.0.1:9092:9092"
environment:
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
KAFKA_LISTENERS: HOST://:9092,INTERNAL://:19092,CONTROLLER://:9093
KAFKA_ADVERTISED_LISTENERS: HOST://127.0.0.1:9092,INTERNAL://kafka:19092
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: HOST:PLAINTEXT,INTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT
KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
KAFKA_HEAP_OPTS: -Xms400m -Xmx400m
healthcheck:
test: ["CMD-SHELL", "KAFKA_HEAP_OPTS=-Xmx128m /opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:19092 > /dev/null 2>&1"]
interval: 5s
timeout: 20s
retries: 24
start_period: 10s
schema-registry:
image: confluentinc/cp-schema-registry:7.8.0
mem_limit: 1g
depends_on:
kafka:
condition: service_healthy
ports:
- "127.0.0.1:8081:8081"
environment:
SCHEMA_REGISTRY_HOST_NAME: schema-registry
SCHEMA_REGISTRY_KAFKASTORE_BOOTSTRAP_SERVERS: kafka:19092
SCHEMA_REGISTRY_LISTENERS: http://0.0.0.0:8081
SCHEMA_REGISTRY_HEAP_OPTS: -Xms400m -Xmx400m
# requirements.txt confluent-kafka==2.6.1 fastavro==1.9.7 requests==2.32.3
#!/usr/bin/env bash # run.sh · docker compose · Python 3 · confluent-kafka 2.6.1 set -euo pipefail docker compose up -d python3 -m venv .venv .venv/bin/pip install -q -r requirements.txt until curl -sf http://127.0.0.1:8081/subjects > /dev/null; do sleep 2; done .venv/bin/python incident.py
Весь клиентский код опирается на общий модуль. Сериализацию в формате Confluent мы пишем руками на requests и fastavro, а не берём готовый AvroSerializer. Так хорошо видно, где именно в чтении участвуют схема писателя и схема читателя. В модуле три схемы. V1 содержит depot_code без default, V2 не содержит этого поля, а V1_DEFAULT это вариант V1 с default для depot_code.
# common.py · confluent-kafka 2.6.1 · fastavro 1.9.7 · Kafka 4.3.2 · Schema Registry 7.8.0
import io
import json
import os
import struct
import time
import fastavro
import requests
from confluent_kafka import Consumer, Producer
from confluent_kafka.admin import AdminClient, NewTopic
SR = os.environ.get("SR_URL", "http://127.0.0.1:8081")
BOOT = os.environ.get("BOOTSTRAP", "127.0.0.1:9092")
HEADERS = {"Content-Type": "application/vnd.schemaregistry.v1+json"}
V1 = {
"type": "record", "name": "Shipment", "namespace": "wh",
"fields": [
{"name": "order_id", "type": "string"},
{"name": "depot_code", "type": "string"},
{"name": "carrier", "type": "string"},
],
}
V2 = {
"type": "record", "name": "Shipment", "namespace": "wh",
"fields": [
{"name": "order_id", "type": "string"},
{"name": "carrier", "type": "string"},
],
}
V1_DEFAULT = {
"type": "record", "name": "Shipment", "namespace": "wh",
"fields": [
{"name": "order_id", "type": "string"},
{"name": "depot_code", "type": "string", "default": "UNKNOWN"},
{"name": "carrier", "type": "string"},
],
}
_writers = {}
def set_mode(subject, mode):
r = requests.put(f"{SR}/config/{subject}", data=json.dumps({"compatibility": mode}),
headers=HEADERS, timeout=10)
return r.status_code, r.json()
def register(subject, schema):
r = requests.post(f"{SR}/subjects/{subject}/versions",
data=json.dumps({"schema": json.dumps(schema)}),
headers=HEADERS, timeout=10)
return r.status_code, r.json()
def check(subject, schema):
url = f"{SR}/compatibility/subjects/{subject}/versions?verbose=true"
r = requests.post(url, data=json.dumps({"schema": json.dumps(schema)}),
headers=HEADERS, timeout=10)
return r.status_code, r.json()
def show(title, status, body):
print(f"{title}: HTTP {status} {json.dumps(body, ensure_ascii=False)}")
def ensure_topics(*names):
admin = AdminClient({"bootstrap.servers": BOOT})
futures = admin.create_topics([NewTopic(n, 1, 1) for n in names])
for future in futures.values():
try:
future.result()
except Exception as e:
if "TOPIC_ALREADY_EXISTS" not in str(e):
raise
def encode(schema_id, schema, record):
buf = io.BytesIO()
buf.write(b"\x00" + struct.pack(">I", schema_id))
fastavro.schemaless_writer(buf, fastavro.parse_schema(schema), record)
return buf.getvalue()
def _writer_schema(schema_id):
if schema_id not in _writers:
r = requests.get(f"{SR}/schemas/ids/{schema_id}", timeout=10)
r.raise_for_status()
_writers[schema_id] = fastavro.parse_schema(json.loads(r.json()["schema"]))
return _writers[schema_id]
def decode(payload, reader_schema):
if payload[0] != 0:
raise ValueError("not Confluent wire format")
schema_id = struct.unpack(">I", payload[1:5])[0]
return fastavro.schemaless_reader(
io.BytesIO(payload[5:]), _writer_schema(schema_id),
fastavro.parse_schema(reader_schema))
def produce(topic, items):
p = Producer({"bootstrap.servers": BOOT})
for key, value, headers in items:
p.produce(topic, key=key, value=value, headers=headers)
p.flush(15)
def consume_all(topic, group, expected, timeout=30):
c = Consumer({"bootstrap.servers": BOOT, "group.id": group,
"auto.offset.reset": "earliest", "enable.auto.commit": False})
c.subscribe([topic])
out = []
deadline = time.time() + timeout
while len(out) < expected and time.time() < deadline:
m = c.poll(1.0)
if m is None:
continue
if m.error():
raise RuntimeError(m.error())
out.append(m)
c.close()
return out
Основной сценарий в incident.py идёт в два этапа. Сначала мы повторяем инцидент на subject в режиме BACKWARD. Регистрируем V1, затем проверяем и регистрируем V2 без depot_code, пишем в топик три сообщения по V2 и читаем их консьюмером со схемой V1. Всё, что не десериализуется, уходит в DLQ вместе с заголовками с причиной. Затем на двух новых subject, в режимах FORWARD и FULL_TRANSITIVE, пробуем зарегистрировать ту же V2 после V1.
# incident.py · confluent-kafka 2.6.1 · fastavro 1.9.7 · Kafka 4.3.2 · Schema Registry 7.8.0
from common import (V1, V2, check, consume_all, decode, encode, ensure_topics,
produce, register, set_mode, show)
SUBJECT = "warehouse.picked-value"
TOPIC = "warehouse.picked"
DLQ = "warehouse.picked.dlq"
print("== BACKWARD, как на складе ==")
show("режим", *set_mode(SUBJECT, "BACKWARD"))
status, body = register(SUBJECT, V1)
show("регистрация v1", status, body)
show("проверка v2 до регистрации", *check(SUBJECT, V2))
status, body = register(SUBJECT, V2)
show("регистрация v2 без depot_code", status, body)
v2_id = body["id"]
ensure_topics(TOPIC, DLQ)
produce(TOPIC, [(f"A-{i}", encode(v2_id, V2, {"order_id": f"A-{i}", "carrier": "DPD"}), None)
for i in range(1, 4)])
moved = 0
for m in consume_all(TOPIC, "carrier-v1", 3):
try:
print("прочитано", decode(m.value(), V1))
except Exception as e:
print(f"offset={m.offset()} ошибка {type(e).__name__}: {e}")
produce(DLQ, [(m.key(), m.value(), [("error", str(e).encode())])])
moved += 1
print("сообщений в DLQ:", moved)
for mode in ("FORWARD", "FULL_TRANSITIVE"):
print(f"== {mode} ==")
subject = f"warehouse.picked-{mode.lower()}-value"
show("режим", *set_mode(subject, mode))
show("регистрация v1", *register(subject, V1))
show("проверка v2", *check(subject, V2))
show("регистрация v2", *register(subject, V2))
== BACKWARD, как на складе ==
режим: HTTP 200 {"compatibility": "BACKWARD"}
регистрация v1: HTTP 200 {"id": 1}
проверка v2 до регистрации: HTTP 200 {"is_compatible": true, "messages": []}
регистрация v2 без depot_code: HTTP 200 {"id": 2}
offset=0 ошибка SchemaResolutionError: No default value for field depot_code in wh.Shipment
offset=1 ошибка SchemaResolutionError: No default value for field depot_code in wh.Shipment
offset=2 ошибка SchemaResolutionError: No default value for field depot_code in wh.Shipment
сообщений в DLQ: 3
== FORWARD ==
режим: HTTP 200 {"compatibility": "FORWARD"}
регистрация v1: HTTP 200 {"id": 1}
проверка v2: HTTP 200 {"is_compatible": false, "messages": ["{errorType:'READER_FIELD_MISSING_DEFAULT_VALUE', description:'The field 'depot_code' at path '/fields/1' in the old schema has no default value and is missing in the new schema', additionalInfo:'depot_code'}", "{oldSchemaVersion: 1}", "{oldSchema: '{\"type\":\"record\",\"name\":\"Shipment\",\"namespace\":\"wh\",\"fields\":[{\"name\":\"order_id\",\"type\":\"string\"},{\"name\":\"depot_code\",\"type\":\"string\"},{\"name\":\"carrier\",\"type\":\"string\"}]}'}", "{validateFields: 'false', compatibility: 'FORWARD'}"]}
регистрация v2: HTTP 409 {"error_code": 409, "message": "Schema being registered is incompatible with an earlier schema for subject \"warehouse.picked-forward-value\", details: [{errorType:'READER_FIELD_MISSING_DEFAULT_VALUE', description:'The field 'depot_code' at path '/fields/1' in the old schema has no default value and is missing in the new schema', additionalInfo:'depot_code'}, {oldSchemaVersion: 1}, {oldSchema: '{\"type\":\"record\",\"name\":\"Shipment\",\"namespace\":\"wh\",\"fields\":[{\"name\":\"order_id\",\"type\":\"string\"},{\"name\":\"depot_code\",\"type\":\"string\"},{\"name\":\"carrier\",\"type\":\"string\"}]}'}, {validateFields: 'false', compatibility: 'FORWARD'}]"}
== FULL_TRANSITIVE ==
режим: HTTP 200 {"compatibility": "FULL_TRANSITIVE"}
регистрация v1: HTTP 200 {"id": 1}
проверка v2: HTTP 200 {"is_compatible": false, "messages": ["{errorType:'READER_FIELD_MISSING_DEFAULT_VALUE', description:'The field 'depot_code' at path '/fields/1' in the old schema has no default value and is missing in the new schema', additionalInfo:'depot_code'}", "{validateFields: 'false', compatibility: 'FULL_TRANSITIVE'}"]}
регистрация v2: HTTP 409 {"error_code": 409, "message": "Schema being registered is incompatible with an earlier schema for subject \"warehouse.picked-full_transitive-value\", details: [{errorType:'READER_FIELD_MISSING_DEFAULT_VALUE', description:'The field 'depot_code' at path '/fields/1' in the old schema has no default value and is missing in the new schema', additionalInfo:'depot_code'}, {validateFields: 'false', compatibility: 'FULL_TRANSITIVE'}]"}
В выводе видно ту же последовательность, что и на складе. В режиме BACKWARD проверка и регистрация V2 проходят, а консьюмер на V1 не может заполнить depot_code и отправляет сообщения в DLQ. Одна и та же схема V2 на subject с FORWARD и FULL_TRANSITIVE не регистрируется, и реестр отвечает кодом 409. Сообщение об ошибке при регистрации содержит детали само по себе, без дополнительных параметров, а именно тип ошибки READER_FIELD_MISSING_DEFAULT_VALUE, поле depot_code и режим проверки. Параметр verbose=true нужен только эндпоинту проверки совместимости. Он добавлен в функцию check, поэтому в ответах проверки видны messages, а без него при несовместимости причина не возвращалась бы. Прогон показывает одну схему и один сценарий, а не доказывает поведение реестра во всех случаях.
Задания
Три задания закрывают то, что в исходнике осталось за кадром, а именно устройство FULL_TRANSITIVE, проверку схемы до релиза и работу с DLQ. Решения используют тот же common.py.
Задание 1. Что мешает удалить поле при FULL_TRANSITIVE
На subject в режиме FULL_TRANSITIVE зарегистрируйте V1 без default. Затем выясните, проходит ли V1_DEFAULT (поле с default), и можно ли после этого удалить depot_code. Сравните ответ реестра для FULL_TRANSITIVE и для FULL на одной и той же схеме без поля.
▶ Решение (нажмите, чтобы открыть)
Сначала добавляем default, а удаление поля проверяем отдельно, не регистрируя его. Последним шагом переключаем subject в FULL и повторяем проверку той же схемы.
# task1_transitive.py · confluent-kafka 2.6.1 · fastavro 1.9.7 · Kafka 4.3.2 · Schema Registry 7.8.0
from common import V1, V1_DEFAULT, V2, check, register, set_mode, show
SUBJECT = "task1-value"
set_mode(SUBJECT, "FULL_TRANSITIVE")
show("v1 без default", *register(SUBJECT, V1))
show("кандидат с default", *check(SUBJECT, V1_DEFAULT))
show("регистрация с default", *register(SUBJECT, V1_DEFAULT))
show("удаление поля, FULL_TRANSITIVE", *check(SUBJECT, V2))
set_mode(SUBJECT, "FULL")
show("удаление поля, FULL", *check(SUBJECT, V2))
v1 без default: HTTP 200 {"id": 1}
кандидат с default: HTTP 200 {"is_compatible": true, "messages": []}
регистрация с default: HTTP 200 {"id": 3}
удаление поля, FULL_TRANSITIVE: HTTP 200 {"is_compatible": false, "messages": ["{errorType:'READER_FIELD_MISSING_DEFAULT_VALUE', description:'The field 'depot_code' at path '/fields/1' in the old schema has no default value and is missing in the new schema', additionalInfo:'depot_code'}", "{validateFields: 'false', compatibility: 'FULL_TRANSITIVE'}"]}
удаление поля, FULL: HTTP 200 {"is_compatible": true, "messages": []}
Добавление default безопасно в обе стороны, поэтому реестр принимает версию с default и возвращает HTTP 200. Число в ответе, id 3, не номер версии в subject, а идентификатор схемы в реестре. Список версий subject мы не запрашивали, так что номер новой версии прогон не показывает.
Теперь сравнение. FULL_TRANSITIVE сопоставляет кандидата со всей историей, а в ней остаётся версия 1, где у depot_code нет default. Читатель на ней не сможет разрешить данные без поля, и удаление запрещено. FULL сравнивает только с последней версией. Раз регистрация с default прошла, последней стала именно она, и та же схема без поля проходит проверку. Поэтому обязательные поля без default стоит вводить, только если вы готовы никогда их не удалять, или заводить новый subject и новый топик.
Задание 2. Проверка схемы в CI до релиза
Напишите скрипт для CI, который принимает subject и файл со схемой, вызывает проверку совместимости в реестре и завершается ненулевым кодом, если схема не проходит. Прогоните его на двух кандидатах, а именно на добавлении поля без default и на удалении поля с default.
▶ Решение (нажмите, чтобы открыть)
Скрипт использует конечную точку проверки без указания версии, которая по документации выполняет ту же проверку, что и регистрация. Маршрут с параметром version проверяет схему против одной указанной версии (значение latest означает последнюю зарегистрированную), а маршрут без версии учитывает транзитивность режима и сравнивает с одной или со всеми версиями. Для CI нужна проверка, равная регистрации, поэтому берём второй вариант. Код возврата 0 означает совместимость, 1 несовместимость, 2 ошибку запроса.
# ci_check.py · requests 2.32.3 · Schema Registry 7.8.0
import json
import os
import sys
import requests
SR = os.environ.get("SR_URL", "http://127.0.0.1:8081")
HEADERS = {"Content-Type": "application/vnd.schemaregistry.v1+json"}
def main():
if len(sys.argv) != 3:
print("usage: ci_check.py SUBJECT SCHEMA_FILE")
return 2
subject, path = sys.argv[1], sys.argv[2]
with open(path, encoding="utf-8") as f:
schema = f.read()
url = f"{SR}/compatibility/subjects/{subject}/versions?verbose=true"
r = requests.post(url, data=json.dumps({"schema": schema}), headers=HEADERS, timeout=10)
if r.status_code != 200:
print(f"ERROR HTTP {r.status_code} {r.text}")
return 2
body = r.json()
if body.get("is_compatible"):
print(f"OK {path} совместима с {subject}")
return 0
print(f"FAIL {path} несовместима с {subject}")
for message in body.get("messages", []):
print(" ", message)
return 1
sys.exit(main())
Демонстрационный файл готовит subject в режиме FULL_TRANSITIVE с базовой версией, где у depot_code есть default, пишет двух кандидатов во временный каталог и запускает скрипт как отдельный процесс, чтобы получить настоящие коды возврата.
# ci_demo.py · confluent-kafka 2.6.1 · fastavro 1.9.7 · Kafka 4.3.2 · Schema Registry 7.8.0
import copy
import json
import pathlib
import subprocess
import sys
import tempfile
from common import V1_DEFAULT, register, set_mode, show
SUBJECT = "ci-demo-value"
set_mode(SUBJECT, "FULL_TRANSITIVE")
show("базовая версия", *register(SUBJECT, V1_DEFAULT))
add_no_default = copy.deepcopy(V1_DEFAULT)
add_no_default["fields"].append({"name": "dock", "type": "string"})
remove_with_default = copy.deepcopy(V1_DEFAULT)
remove_with_default["fields"] = [f for f in V1_DEFAULT["fields"] if f["name"] != "depot_code"]
script = pathlib.Path(__file__).with_name("ci_check.py")
with tempfile.TemporaryDirectory() as tmp:
for name, schema in (("add_no_default", add_no_default),
("remove_with_default", remove_with_default)):
path = pathlib.Path(tmp) / f"{name}.json"
path.write_text(json.dumps(schema), encoding="utf-8")
result = subprocess.run([sys.executable, str(script), SUBJECT, str(path)],
capture_output=True, text=True)
print(f"--- {name}, код возврата {result.returncode}")
print(result.stdout.strip())
базовая версия: HTTP 200 {"id": 3}
--- add_no_default, код возврата 1
FAIL /tmp/tmpcc5e5a00/add_no_default.json несовместима с ci-demo-value
{errorType:'READER_FIELD_MISSING_DEFAULT_VALUE', description:'The field 'dock' at path '/fields/3' in the new schema has no default value and is missing in the old schema', additionalInfo:'dock'}
{oldSchemaVersion: 1}
{oldSchema: '{"type":"record","name":"Shipment","namespace":"wh","fields":[{"name":"order_id","type":"string"},{"name":"depot_code","type":"string","default":"UNKNOWN"},{"name":"carrier","type":"string"}]}'}
{validateFields: 'false', compatibility: 'FULL_TRANSITIVE'}
--- remove_with_default, код возврата 0
OK /tmp/tmpcc5e5a00/remove_with_default.json совместима с ci-demo-value
Добавление обязательного поля без default блокирует релиз, потому что новый читатель не сможет прочитать старые данные. Удаление поля, у которого есть default, проходит. В реальном конвейере достаточно вызвать ci_check.py отдельным шагом перед сборкой и считать ненулевой код провалом.
Задание 3. DLQ с алертом на первое сообщение и replay
Напишите консьюмера, который при первой ошибке десериализации выводит алерт с именем топика, partition, offset и причиной, а затем сохраняет сырые байты каждого проблемного сообщения. После исправления схемы читателя проиграйте DLQ заново.
▶ Решение (нажмите, чтобы открыть)
Решение самодостаточно и использует свои топики и subject. Алерт печатается один раз, на первой ошибке, а остальные сообщения только пересылаются в DLQ вместе с заголовками и записываются в файл в base64. Replay читает DLQ новой схемой читателя, где у depot_code есть default.
# task3_dlq.py · confluent-kafka 2.6.1 · fastavro 1.9.7 · Kafka 4.3.2 · Schema Registry 7.8.0
import base64
import json
from common import (V1, V1_DEFAULT, V2, consume_all, decode, encode, ensure_topics,
produce, register, set_mode)
SUBJECT = "t3-value"
TOPIC = "t3.picked"
DLQ = "t3.picked.dlq"
set_mode(SUBJECT, "BACKWARD")
register(SUBJECT, V1)
_, body = register(SUBJECT, V2)
v2_id = body["id"]
ensure_topics(TOPIC, DLQ)
produce(TOPIC, [(f"B-{i}", encode(v2_id, V2, {"order_id": f"B-{i}", "carrier": "GLS"}), None)
for i in range(1, 4)])
alerted = False
dump = []
for m in consume_all(TOPIC, "t3-carrier", 3):
try:
decode(m.value(), V1)
except Exception as e:
if not alerted:
print(f"ALERT topic={m.topic()} partition={m.partition()} "
f"offset={m.offset()} reason={type(e).__name__}: {e}")
alerted = True
headers = [("src.topic", m.topic().encode()),
("src.partition", str(m.partition()).encode()),
("src.offset", str(m.offset()).encode()),
("error", str(e).encode())]
produce(DLQ, [(m.key(), m.value(), headers)])
dump.append({"offset": m.offset(), "raw": base64.b64encode(m.value()).decode()})
with open("dlq_dump.txt", "w", encoding="utf-8") as f:
for row in dump:
f.write(json.dumps(row) + "\n")
print("сохранено сырых сообщений:", len(dump))
print("== replay схемой читателя с default ==")
replayed = 0
for m in consume_all(DLQ, "t3-replay", len(dump)):
print("replay", decode(m.value(), V1_DEFAULT))
replayed += 1
print("проиграно:", replayed)
ALERT topic=t3.picked partition=0 offset=0 reason=SchemaResolutionError: No default value for field depot_code in wh.Shipment
сохранено сырых сообщений: 3
== replay схемой читателя с default ==
replay {'order_id': 'B-1', 'carrier': 'GLS', 'depot_code': 'UNKNOWN'}
replay {'order_id': 'B-2', 'carrier': 'GLS', 'depot_code': 'UNKNOWN'}
replay {'order_id': 'B-3', 'carrier': 'GLS', 'depot_code': 'UNKNOWN'}
проиграно: 3
Алерт приходит на первой же записи, а не после тысячи. Сырые байты сохраняются без изменений, поэтому replay не зависит от того, как и когда исправлена схема читателя. После исправления схемы проигрывание даёт те же записи, а depot_code получает значение UNKNOWN. Для настоящего конвейера replay стоит писать в рабочий топик отдельным процессом и сначала проверять результат на копии.
Что взять с собой
Режим совместимости нужно выбирать не по вкусу, а по тому, кто в вашей системе обновляется первым. Если консьюмеры живут в других командах и релизятся независимо, стоит рассмотреть FULL или FULL_TRANSITIVE. На нашем стенде BACKWARD по умолчанию пропустил удаление поля без default, а FORWARD и FULL_TRANSITIVE отклонили ту же схему. Проверяйте схему до релиза запросом к реестру и настраивайте DLQ на тревогу с первого сообщения. Технику работы с реестром, сериализаторами и Kafka Connect мы подробно разбираем на курсе Интеграция Apache Kafka для разработчиков.
Референсные ссылки
- The schema registry approved a change that only worked if we deployed first, исходный разбор инцидента.
- Schema Evolution and Compatibility for Schema Registry on Confluent Platform, режимы совместимости и порядок обновления клиентов.
- Schema Registry API Reference for Confluent Platform, конечные точки /config и /compatibility.
- Apache Avro Specification 1.11.1, поля, default и разрешение схем.

