Ошибки, повторы и схемы сообщений
Интеграция живёт годами, и за это время в неё обязательно придут битое сообщение, недоступная база и новая версия контракта. Этот урок о том, как заранее описать все три ситуации.
Два вида ошибок
| Вид | Примеры | Что делать |
|---|---|---|
| Временные | База недоступна, внешний сервис ответил «попробуйте позже», истёк таймаут | Повторить через паузу — скорее всего, получится |
| Постоянные | Битый JSON, нет обязательного поля, ссылка на несуществующего клиента, нарушено бизнес-правило | Повторять бесполезно — убрать с пути и разобрать отдельно |
Сообщение с постоянной ошибкой называют «ядовитым» (poison pill). Если обработчик честно пытается обработать его снова и снова, вся партиция встаёт: следующие сообщения ждут за ним в очереди, лаг растёт. Одно кривое событие может остановить обработку тысяч нормальных.
Стратегии повторов
- Повтор на месте с паузой. Обработчик ждёт и пробует снова, обычно с нарастающей паузой: 1, 2, 4, 8 секунд. Порядок сохраняется, но партиция стоит, пока идут попытки. Подходит для коротких сбоев.
- Retry-топики. Неудачное сообщение перекладывают в отдельный топик с задержкой — например,
orders.created.retry-1m, затемretry-10m. Основной поток не стоит. Но порядок по ключу ломается: следующее событие того же заказа обработается раньше отложенного. - Очередь «мёртвых писем» (DLQ, dead letter queue). После исчерпания попыток — или сразу для постоянных ошибок — сообщение уходит в отдельный топик вместе с причиной: текст ошибки, число попыток, исходные партиция и оффсет. Оттуда его разбирает человек или автоматика и при необходимости отправляет повторно.
Retry-топик для потока, где важен порядок. Событие «заказ оплачен» ушло на повтор, а «заказ отменён» обработалось сразу. Через минуту повтор применится — и отменённый заказ окажется оплаченным. Если порядок по ключу важен, нужна блокировка ключа: пока у заказа есть сообщение на повторе, его следующие события тоже откладываются.
Разработчик сам выберет библиотеку и механизм. Но правила обработки ошибок — это требования, их должен написать аналитик:
- Какие ошибки временные, а какие постоянные — по каждому типовому случаю.
- Сколько попыток и с какой паузой; сколько в сумме допустимо ждать.
- Важен ли порядок при повторах и как его сохранить.
- Куда уходят необработанные сообщения: имя DLQ-топика, какие сведения об ошибке туда пишутся.
- Кто и в какой срок разбирает DLQ, как получает тревогу.
- Как отправить сообщение на повторную обработку после исправления.
Схема сообщения
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. Обработчик пытается разобрать его снова и снова. Что происходит и как правильно?
- Ничего страшного, Kafka сама пропустит сообщение через минуту
- Партиция встала: после нескольких попыток или сразу сообщение нужно отправить в DLQ и идти дальше
- Нужно увеличить число партиций
- Нужно включить exactly-once
В событии, которое читают пять систем, нужно переименовать поле customer в client. Как сделать это безопасно?
- Переименовать в схеме и выкатить продюсера ночью
- Попросить все пять команд обновиться в один день
- Добавить
clientрядом сcustomer, перевести потребителей, затем удалить старое поле - Переименовать без изменения схемы — JSON всё стерпит