Не менее одного раза разрешает повтор и оставляет приложению защиту эффекта. Ровно один раз требует согласовать фиксируемый результат с входом в указанной области, включая правила внешнего приёмника.
Практический смысл
Почему это важно
Транзакция Kafka может связать выходные записи и позиции чтения. Но платёж через внешний API не становится её частью автоматически, а идемпотентный производитель решает только свою задачу повторной публикации.
Доказательная часть
Что подтверждено
В транзакционном пути чтение—обработка—запись Kafka выходные записи и соответствующие позиции потребителя фиксируются одной транзакцией. Это связывает видимый результат с продвижением входа.
Граница применимости: Kafka 4.0, правильно организованная транзакционная обработка между темами Kafka.
При записи во внешнюю систему гарантия требует её участия: результат и позицию можно хранить атомарно в приёмнике либо использовать отдельно доказанный протокол согласования. Транзакция Kafka не включает произвольный вызов внешнего API.
Граница применимости: Kafka 4.0, внешний приёмник; один заголовок идемпотентности без границ хранения и результата не доказывает сквозную гарантию.
Идемпотентный производитель Kafka предотвращает дубли своих повторных отправок в журнал. Он не связывает внешний платёж с позицией потребителя и потому сам по себе не доказывает обработку платежа ровно один раз.
Граница применимости: Kafka 4.0; гарантия публикации производителя отделена от результата потребителя.
Потребитель с isolation.level=read_committed не выдаёт отменённые транзакционные записи. В каждом разделе он читает только до последней стабильной позиции этого раздела; при открытых транзакциях её ограничивает первая из них в том же разделе. Без этого режима можно увидеть результаты, которые позже отменят.
Граница применимости: Kafka 4.0, видимость транзакционных записей и last stable offset отдельно по разделам; read_committed не превращает внешние действия в транзакционные.
Транзакция производителя Kafka может охватывать записи в нескольких разделах и темах. Идемпотентность отдельных отправок не заменяет атомарную фиксацию всего такого набора вместе с нужными позициями входа.
Граница применимости: Kafka 4.0, транзакционные записи в несколько разделов; состав транзакции должен быть задан приложением.
Гарантия ровно одного раза относится к наблюдаемому зафиксированному результату, а не к числу запусков функции обработки. После отказа работа может выполняться повторно; некоординируемые внешние эффекты такого повтора остаются за границей гарантии.
Граница применимости: Kafka 4.0, повтор транзакционной обработки и область её результата.
transactional.id связывает транзакционный протокол Kafka между сеансами производителя: прежние транзакции с тем же идентификатором должны получить завершение до начала новых. Одно enable.idempotence без transactional.id не включает этот межсеансовый транзакционный контракт.
Граница применимости: Kafka 4.0, конфигурация транзакционного производителя; это условие не отменяет необходимости связать позиции и результат и выбрать правильный режим чтения.
Граница терминов
Не путать
Идемпотентность удерживает эффект одной операции при повторе. Она может быть частью решения для внешнего приёмника, но не заменяет доказательство всей цепочки и срока защиты ключа.
Перед спецификацией
Что проверить
- Перечислите входные позиции и результаты, на которые распространяется гарантия.
- Проверьте атомарную фиксацию выходных записей и позиций потребителя.
- Настройте чтение транзакционных результатов через read_committed.
- Отделите идемпотентность производителя от транзакционной обработки потребителя.
- Проверьте назначение transactional.id и восстановление после смены сеанса производителя.
- Испытайте отмену транзакции и повтор работы после сбоя.
- Назовите все внешние API и докажите их участие либо защиту результата от повтора.
- Оценивайте число зафиксированных деловых результатов, а не только запусков обработчика.
Открытые основания
Первоисточники
Apache Kafka 4.0 Design
Apache Software Foundation · Apache Kafka 4.0 documentation
Определяет log ordering, producer idempotence, delivery semantics и scope exactly-once processing.
Открыть первоисточникApache Kafka 4.0: Consumer Configs
Apache Software Foundation · документация Apache Kafka 4.0, страница открыта 7 сентября 2026 года
Открыт редактором 7 сентября 2026 года, заголовок документа сверен. Сверить isolation.level=read_committed, last stable offset и задержку чтения из-за незавершённых транзакций.
Открыть первоисточникApache Kafka 4.0: Producer Configs
Apache Software Foundation · документация Apache Kafka 4.0, страница открыта 7 сентября 2026 года
Открыт редактором 7 сентября 2026 года, заголовок документа сверен. Сверить transactional.id, связь с enable.idempotence и продолжение транзакционного протокола между сеансами производителя.
Открыть первоисточникStripe API Reference: Idempotent requests
Stripe · справочник Stripe API, страница открыта 7 сентября 2026 года
Открыт редактором 7 сентября 2026 года, заголовок документа сверен. Сверить POST с ключом идемпотентности: параметры, сохранение ответа после начала выполнения и удаление ключей не раньше 24 часов.
Открыть первоисточникHTTP Semantics
Internet Engineering Task Force · RFC 9110, June 2022
Определяет stateless HTTP, origin server, intermediaries, target URI и security significance полей authority и Host.
Открыть первоисточник