Сериализация ключей и значений

Формат ключа и значения сообщения задаётся на шине реквизитами КлючСердес и ЗначениеСердес. Этот документ описывает контракт: что обработчик обмена обязан вернуть при выгрузке и что получит приёмная процедура при загрузке.

Ключ и значение обрабатываются одинаково — разными сердесами, но по одним правилам. Как устроены сеансы обмена целиком — см. Отправка данных и Получение данных.

Приём: что получает приёмная процедура

Признак null передаётся в сообщении отдельным флагом и проверяется до разбора формата, поэтому он всегда «сильнее» сердеса: сообщение-надгробие (tombstone) приходит как Null при любом сердесе.

Сердес	Флаг null	Тело нулевой длины	Обычное тело
Игнорировать	Null	Неопределено	Неопределено (тело пропускается)
Null	Null	исключение	исключение
Строка	Null	""	Строка (UTF-8)
ДвоичныеДанные	Null	пустые ДвоичныеДанные	ДвоичныеДанные
Uuid	Null	Неопределено	УникальныйИдентификатор
СтруктураJson	Null	Неопределено	Структура
СоответствиеJson	Null	Неопределено	Соответствие
Xml	Null	Неопределено	тип определяется содержимым

Тело нулевой длины — это не отсутствие значения, а пустое значение: отправитель прислал ноль байт, не выставив флаг null. Результат зависит от того, представимо ли пустое тело в формате:

• Строка и ДвоичныеДанные — представимо, возвращается пустое значение того же типа, приём точный;
• Uuid, СтруктураJson, СоответствиеJson, Xml — непредставимо (UUID это всегда 36 символов, минимальный JSON-объект — {}), поэтому возвращается Неопределено, а не выдуманное значение.

Сердес Null предполагает, что в теме допустимы только сообщения-надгробия; любое непустое сообщение считается ошибкой данных и приводит к исключению.

Отправка: что должен вернуть обработчик

Методы СообщениеКлюч и СообщениеЗначение обработки обмена вызываются на каждый выгружаемый объект. Сердес Игнорировать для выгрузки запрещён — это проверяется при записи шины; Null допускается и означает обмен только надгробиями: обработчик обязан возвращать Null.

Сердес	Допустимый тип значения	Что уходит в Kafka
Строка	Строка	UTF-8; пустая строка — тело нулевой длины
ДвоичныеДанные	ДвоичныеДанные, БуферДвоичныхДанных	как есть; пустое значение — тело нулевой длины
Uuid	УникальныйИдентификатор	36 символов, тела нулевой длины не бывает
СтруктураJson	Структура, ФиксированнаяСтруктура	JSON; пустая структура — {}
СоответствиеJson	Соответствие, ФиксированноеСоответствие	JSON; пустое соответствие — {}
Xml	любое сериализуемое значение	XML-документ, тела нулевой длины не бывает
Null	только Null	сообщение с флагом null, без тела

Особые значения:

Что вернул обработчик	Результат
Null	сообщение уходит с флагом null (tombstone)
Неопределено	исключение «Не определен ключ сообщения» / «Не определено значение сообщения»
значение неподходящего типа	исключение «Некорректный тип исходных данных для сериализации…»

При сердесе Null любое значение, кроме Null, приводит к исключению: ветки сериализации для этого сердеса нет, и текст ошибки говорит о неподдерживаемом типе сериализации, хотя настройка шины при этом корректна.

Следствия для прикладного кода

Сквозная пересылка. Принятое Неопределено нельзя отправить дальше без обработки — при выгрузке оно даст исключение. Без изменений пересылаются Null и значения допустимых типов.

Различение пустого и проигнорированного. Для сердеса Игнорировать результат всегда Неопределено, для остальных Неопределено означает пустое тело. Приёмная процедура знает сердес своей шины, поэтому неоднозначности нет.

Проверка на стороне приёмника. Для форматов, где пустое тело непредставимо, значение приходит либо ожидаемого типа, либо Неопределено, либо Null. Код, присваивающий его типизированному реквизиту, должен обрабатывать два последних случая.

Где это в коде

Разбор входящих сообщений — КафкаСервер.ДесериализоватьЗначение. Подготовка исходящих — КафкаСервер.СериализоватьКлючВБуферДвоичныхДанных и КафкаСервер.СериализоватьЗначениеВПотокИЗакрытьЗаписьДанных. Проверки допустимых сердесов для направления обмена — в модуле объекта справочника КафкаШины.