06.6Теория≈ 14 минут

Ошибки, повторы и схемы сообщений

Интеграция живёт годами, и за это время в неё обязательно придут битое сообщение, недоступная база и новая версия контракта. Этот урок о том, как заранее описать все три ситуации.

Два вида ошибок

ВидПримерыЧто делать
ВременныеБаза недоступна, внешний сервис ответил «попробуйте позже», истёк таймаутПовторить через паузу — скорее всего, получится
ПостоянныеБитый JSON, нет обязательного поля, ссылка на несуществующего клиента, нарушено бизнес-правилоПовторять бесполезно — убрать с пути и разобрать отдельно

Сообщение с постоянной ошибкой называют «ядовитым» (poison pill). Если обработчик честно пытается обработать его снова и снова, вся партиция встаёт: следующие сообщения ждут за ним в очереди, лаг растёт. Одно кривое событие может остановить обработку тысяч нормальных.

Стратегии повторов

  1. Повтор на месте с паузой. Обработчик ждёт и пробует снова, обычно с нарастающей паузой: 1, 2, 4, 8 секунд. Порядок сохраняется, но партиция стоит, пока идут попытки. Подходит для коротких сбоев.
  2. Retry-топики. Неудачное сообщение перекладывают в отдельный топик с задержкой — например, orders.created.retry-1m, затем retry-10m. Основной поток не стоит. Но порядок по ключу ломается: следующее событие того же заказа обработается раньше отложенного.
  3. Очередь «мёртвых писем» (DLQ, dead letter queue). После исчерпания попыток — или сразу для постоянных ошибок — сообщение уходит в отдельный топик вместе с причиной: текст ошибки, число попыток, исходные партиция и оффсет. Оттуда его разбирает человек или автоматика и при необходимости отправляет повторно.
Типичная ошибка

Retry-топик для потока, где важен порядок. Событие «заказ оплачен» ушло на повтор, а «заказ отменён» обработалось сразу. Через минуту повтор применится — и отменённый заказ окажется оплаченным. Если порядок по ключу важен, нужна блокировка ключа: пока у заказа есть сообщение на повторе, его следующие события тоже откладываются.

Что важно аналитику

Разработчик сам выберет библиотеку и механизм. Но правила обработки ошибок — это требования, их должен написать аналитик:

  1. Какие ошибки временные, а какие постоянные — по каждому типовому случаю.
  2. Сколько попыток и с какой паузой; сколько в сумме допустимо ждать.
  3. Важен ли порядок при повторах и как его сохранить.
  4. Куда уходят необработанные сообщения: имя DLQ-топика, какие сведения об ошибке туда пишутся.
  5. Кто и в какой срок разбирает DLQ, как получает тревогу.
  6. Как отправить сообщение на повторную обработку после исправления.

Схема сообщения

Kafka не проверяет содержимое сообщений, поэтому договорённость о формате нужно где-то зафиксировать. Варианты:

  • JSON + JSON Schema — читается глазами, привычен всем командам, но объёмнее.
  • Avro или Protobuf — компактные двоичные форматы со строгой схемой; без схемы сообщение не прочитать.

Схемы хранят в реестре схем (Schema Registry — у Confluent, Apicurio и других). Продюсер регистрирует схему, в сообщение кладёт её номер, а потребитель по номеру получает схему и разбирает данные. Главная польза реестра — он проверяет совместимость новой версии схемы со старыми и не даёт зарегистрировать ломающее изменение.

Режим совместимостиГарантияКого обновлять первым
BACKWARDНовая схема читает данные, записанные старойПотребителей
FORWARDСтарая схема читает данные, записанные новойПродюсеров
FULLИ то и другоеВ любом порядке

В реестре Confluent по умолчанию действует BACKWARD.

Правила эволюции контракта

  • Можно: добавить необязательное поле со значением по умолчанию.
  • Нельзя: удалить или переименовать обязательное поле, сменить его тип или смысл.
  • Переименование делается в два шага: добавить новое поле рядом со старым, перевести всех потребителей, через согласованный срок убрать старое.
  • Несовместимое изменение — новая версия топика (.v2) и период, когда продюсер пишет в оба.

Конверт события

Удобно отделить служебные поля от бизнес-данных: общий «конверт» одинаков для всех событий системы, а полезная нагрузка своя у каждого типа. Пример:

{
  "eventId":       "3f1c2a8e-7b1d-4c55-9a0e-6d2b8f9e1a47",
  "eventType":     "OrderCreated",
  "eventVersion":  1,
  "occurredAt":    "2026-11-17T09:42:15.120Z",
  "source":        "order-service",
  "correlationId": "c-8812-ab",
  "payload": {
    "orderId":    "42",
    "customerId": "c-1007",
    "total":      { "amount": "1990.00", "currency": "RUB" },
    "items":      [ { "sku": "A-17", "qty": 2 } ]
  }
}
  • eventId — для дедупликации у потребителей (урок 06.5);
  • eventType и eventVersion — чтобы обработчик понимал, что перед ним;
  • occurredAt — время бизнес-события, а не записи в Kafka;
  • correlationId — чтобы связать события одной бизнес-операции в разных сервисах;
  • деньги — строкой или в минимальных единицах, а не числом с плавающей точкой.
Тонкие и толстые события, DLQ из коробки
  • Тонкое событие — уведомление: «заказ 42 изменился», без подробностей. Потребитель сам идёт за данными в API источника. Контракт маленький и стабильный, зато источник получает лавину запросов и должен быть доступен.
  • Толстое событие несёт всё состояние, нужное получателям. Источник разгружен, получатель независим, но контракт больше и меняется чаще. Выбор — сознательное архитектурное решение; запишите его в ADR.
  • DLQ из коробки. В Kafka Connect очередь мёртвых писем включается настройкой коннектора, многие клиентские библиотеки тоже умеют её сами. Для share-групп DLQ появился в самой Kafka в версии 4.4 (KIP-1191).
  • Повторная отправка из DLQ должна сохранять исходный eventId — иначе дедупликация у потребителей не сработает.

В топик попало сообщение с битым JSON. Обработчик пытается разобрать его снова и снова. Что происходит и как правильно?

  1. Ничего страшного, Kafka сама пропустит сообщение через минуту
  2. Партиция встала: после нескольких попыток или сразу сообщение нужно отправить в DLQ и идти дальше
  3. Нужно увеличить число партиций
  4. Нужно включить exactly-once
Битый формат — постоянная ошибка, повторы ничего не дадут. Пока обработчик упирается, за ядовитым сообщением копится вся партиция.

В событии, которое читают пять систем, нужно переименовать поле customer в client. Как сделать это безопасно?

  1. Переименовать в схеме и выкатить продюсера ночью
  2. Попросить все пять команд обновиться в один день
  3. Добавить client рядом с customer, перевести потребителей, затем удалить старое поле
  4. Переименовать без изменения схемы — JSON всё стерпит
Переименование — это удаление старого поля и добавление нового, то есть ломающее изменение. Двухшаговая миграция позволяет командам обновляться независимо.