← Все статьи

Идемпотентность, повторы и дубли в интеграциях

· 9 мин чтения

Почему в распределённых системах повторы неизбежны, что такое идемпотентная операция, как работают ключ идемпотентности и дедупликация сообщений, как настраивать повторы с экспоненциальной паузой и что аналитику описать в контракте, чтобы клиент не заплатил дважды.

Клиент нажал «Оплатить», запрос ушёл в платёжный сервис, деньги списались — а ответ потерялся по дороге из-за обрыва связи. Мобильное приложение показывает ошибку, пользователь нажимает кнопку ещё раз. Если система не готова к такому сценарию, деньги спишутся дважды. Это не экзотика, а штатная ситуация в любой распределённой системе. Защита от неё называется идемпотентностью, и её нужно проектировать на этапе постановки задачи, а не добавлять после первой жалобы.

Почему повторы неизбежны

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

  • операция не дошла до сервера;
  • операция дошла, но упала до изменения данных;
  • операция выполнилась, но потерялся ответ.

Единственный способ довести дело до конца — повторить запрос. Значит, сервер должен уметь отличить повтор от новой операции. В асинхронных интеграциях ситуация такая же: брокеры гарантируют доставку «хотя бы один раз», и при сбое получателя до подтверждения сообщение будет доставлено снова.

Источники повторов в реальной системе:

  • пользователь нажимает кнопку повторно или обновляет страницу с формой;
  • клиентская библиотека или API-шлюз повторяет запрос после таймаута;
  • балансировщик переотправляет запрос на другой экземпляр;
  • брокер повторно доставляет сообщение после перезапуска потребителя;
  • планировщик запускает задачу повторно после сбоя;
  • партнёр при разборе инцидента вручную переотправляет пачку запросов.

Что такое идемпотентность

Операция идемпотентна, если её многократное выполнение с одними и теми же параметрами даёт тот же результат, что и однократное. Важно: речь о состоянии системы, а не обязательно об одинаковом ответе. Повторный DELETE может вернуть 404 вместо 204, но ресурс как был удалён, так и остался.

В HTTP идемпотентность методов определена стандартом:

МетодИдемпотентенПочему
GET, HEAD, OPTIONSдане меняют состояние
PUTдазаменяет ресурс целиком — повтор запишет то же самое
DELETEдапосле первого вызова ресурса нет, повторы ничего не меняют
POSTнеткаждый вызов создаёт новый ресурс или запускает действие
PATCHне гарантируетсязависит от операции: «установить статус» идемпотентно, «увеличить счётчик» — нет

Стандарт описывает намерение, но не реализацию. PUT, который внутри увеличивает версию документа и отправляет письмо, идемпотентным по факту не будет. Ответственность за это лежит на проектировании.

Естественная идемпотентность

Самый дешёвый способ — сформулировать операцию так, чтобы повтор был безопасен сам по себе.

  • Абсолютные значения вместо приращений. «Установить остаток 15» вместо «уменьшить остаток на 3». «Установить статус SHIPPED» вместо «перевести в следующий статус».
  • Идентификатор от клиента. Клиент генерирует UUID заказа и создаёт его через PUT /orders/{uuid}. Повтор попадёт в тот же ресурс.
  • Условные переходы. «Перевести из PAID в SHIPPED»: если заказ уже SHIPPED, повтор ничего не меняет.
  • Оптимистическая блокировка. Изменение с указанием версии (If-Match: "v7"): повтор после успешного изменения получит 412 Precondition Failed, а не применится второй раз.
  • Upsert по бизнес-ключу. Загрузка справочника «вставить или обновить по коду» идемпотентна, «вставить» — нет.

Ключ идемпотентности

Когда операция по природе не идемпотентна — платёж, перевод, отправка письма, создание заявки, — используют ключ идемпотентности. Клиент генерирует уникальный ключ для каждой бизнес-операции и передаёт его в заголовке. При повторе — тот же ключ.

POST /payments
Idempotency-Key: 5f0c8c3e-2a91-4b0e-9d1f-1c7a3d2e8b44
Content-Type: application/json

{"orderId": "42", "amount": 1500.00, "currency": "RUB"}

Так устроены API Stripe, ЮKassa и многих банков; есть и черновик стандарта IETF для заголовка Idempotency-Key.

Как сервер обрабатывает ключ

  1. Получив запрос, сервер ищет ключ в хранилище (таблица БД, Redis).
  2. Ключа нет — сервер атомарно сохраняет ключ со статусом «в обработке» и выполняет операцию. По завершении сохраняет результат: код ответа и тело.
  3. Ключ есть, операция завершена — сервер возвращает сохранённый ответ, не выполняя операцию заново.
  4. Ключ есть, операция ещё выполняется — сервер возвращает 409 Conflict (клиент повторит позже), а не запускает вторую параллельную обработку.
  5. Ключ есть, но тело запроса другое — это ошибка клиента: тот же ключ для другой операции. Сервер возвращает 422, а не молча применяет старый результат.

Ключевой момент — атомарность: сохранение ключа и изменение бизнес-данных должны быть в одной транзакции, или ключ должен захватываться через уникальный индекс до начала операции. Иначе два параллельных повтора оба увидят «ключа нет» и выполнят операцию дважды.

Что решить при проектировании

  • Кто генерирует ключ. Клиент, при создании намерения — например, при открытии формы оплаты, а не при нажатии кнопки. Иначе каждое нажатие получит новый ключ, и защита не сработает.
  • Область действия. Ключ уникален в пределах клиента (партнёра, учётной записи) и операции.
  • Срок хранения. Обычно от 24 часов до нескольких суток — дольше любого разумного окна повторов.
  • Что возвращать при повторе. Тот же ответ, что в первый раз, включая код. Хорошая практика — дополнительный заголовок вроде Idempotent-Replayed: true.
  • Сохранять ли ошибки. Ответы 4xx с бизнес-ошибкой обычно сохраняют (повтор не исправит ошибку в данных), а 5xx — нет, чтобы повтор мог выполнить операцию.

Дедупликация в асинхронных интеграциях

В мире брокеров аналог ключа идемпотентности — идентификатор сообщения. Отправитель присваивает каждому сообщению уникальный messageId (например, по спецификации CloudEvents — поле id), получатель запоминает обработанные идентификаторы.

Шаблон Idempotent Consumer:

  1. Получатель начинает транзакцию в своей БД.
  2. Пытается вставить messageId в таблицу обработанных сообщений с уникальным индексом.
  3. Если вставка не удалась — сообщение уже обработано, его можно подтвердить и пропустить.
  4. Если удалась — выполняет бизнес-логику в той же транзакции и фиксирует её.
  5. Только после фиксации подтверждает сообщение брокеру.

Если получатель упадёт между фиксацией и подтверждением, брокер доставит сообщение снова, но таблица дедупликации его отсеет.

Альтернатива — дедупликация по бизнес-ключу и версии: событие «остаток товара X стал 15, версия 128». Получатель применяет событие, только если его версия больше сохранённой. Это защищает не только от дублей, но и от нарушения порядка.

«Ровно один раз» (exactly-once) в Kafka существует, но работает внутри Kafka — при чтении из топика и записи в топик в одной транзакции. Как только обработка затрагивает внешнюю БД, письмо или вызов API, гарантию снова обеспечивает идемпотентность получателя.

Повторы: как повторять правильно

Идемпотентность делает повторы безопасными, а политика повторов делает их полезными. Плохо настроенные повторы превращают кратковременный сбой в длительную аварию.

Что повторять

  • Повторять: таймауты, обрывы соединения, 502, 503, 504, 429 Too Many Requests (с учётом заголовка Retry-After), в gRPC — UNAVAILABLE.
  • Не повторять: 400, 401, 403, 404, 422 — повтор не изменит результат.
  • Осторожно: 500 — может быть как временным сбоем, так и ошибкой в данных; повторять ограниченно.

Как повторять

  • Экспоненциальная пауза (exponential backoff): 1 с, 2 с, 4 с, 8 с... — даёт сервису время восстановиться.
  • Случайный разброс (jitter): к паузе добавляется случайная величина. Без этого тысяча клиентов, упавших одновременно, будет повторять тоже одновременно, синхронными волнами.
  • Ограничение числа попыток и общего времени: после N попыток — ошибка пользователю или перенос в очередь ручного разбора.
  • Повтор только на одном уровне. Если повторяет и клиент, и шлюз, и сервис внутри, три попытки на каждом уровне дают 27 запросов к последнему сервису.
  • Предохранитель (circuit breaker): после серии ошибок клиент на время перестаёт вызывать сервис и сразу возвращает ошибку, не добивая упавшую систему.

Повторы в брокерах

Сообщение, которое не удаётся обработать, нельзя бесконечно возвращать в очередь: оно заблокирует обработку остальных. Стандартная схема: несколько повторов с паузами (через отдельные очереди повторов с задержкой), затем перенос в dead letter queue. Для DLQ нужен владелец, мониторинг и процедура: исправить данные или код и переотправить сообщение.

Где идемпотентность нужна обязательно

  • платежи, переводы, списания и начисления бонусов;
  • создание заказов, заявок, договоров;
  • отправка уведомлений: SMS, писем, push (дубль письма не катастрофа, дубль SMS с кодом — уже проблема безопасности и денег);
  • изменение остатков и резервов;
  • вызовы внешних систем, у которых своя бизнес-логика: госсервисы, кредитные бюро, службы доставки;
  • обработчики событий и сообщений — всегда.

Что описать в контракте

Аналитику стоит явно зафиксировать в спецификации интеграции:

  • какие операции идемпотентны по природе, а какие требуют ключа;
  • имя заголовка или поля с ключом, формат (обычно UUID), кто и когда его генерирует;
  • срок хранения ключа и область его уникальности;
  • ответ при повторе с тем же ключом и при повторе с тем же ключом, но другим телом;
  • ответ, если исходный запрос ещё обрабатывается;
  • для сообщений — поле идентификатора, правила дедупликации, ключ порядка;
  • политику повторов клиента: какие ошибки повторять, сколько раз, с какой паузой;
  • что происходит после исчерпания попыток: DLQ, ручной разбор, уведомление.

В OpenAPI ключ идемпотентности описывается как параметр заголовка, а ответы на повтор — отдельными кодами:

parameters:
  - name: Idempotency-Key
    in: header
    required: true
    description: Уникальный ключ операции (UUID). При повторе — тот же ключ;
      результат первого запроса возвращается без повторного выполнения. Хранится 48 часов.
    schema:
      type: string
      format: uuid
responses:
  '201':
    description: Платёж создан (или повтор — возвращён ранее созданный)
  '409':
    description: Запрос с этим ключом ещё обрабатывается — повторите позже
  '422':
    description: Ключ уже использован для запроса с другими параметрами

Как это тестировать

  • повторить запрос с тем же ключом — результат тот же, данные не задвоились;
  • отправить два одинаковых запроса параллельно — выполнилась одна операция;
  • переотправить сообщение в топик — получатель обработал его один раз;
  • прервать обработку после записи в БД, но до ответа, — повтор вернул корректный результат;
  • повторить запрос после истечения срока хранения ключа — поведение соответствует описанному.

Итог

В распределённой системе нельзя гарантировать, что запрос или сообщение будут доставлены ровно один раз. Можно гарантировать, что повтор не навредит. Для этого операции формулируют идемпотентно, где возможно, а там, где нельзя, — вводят ключ идемпотентности или дедупликацию по идентификатору сообщения. Повторы настраивают с экспоненциальной паузой, разбросом и ограничением, а всё это вместе фиксируют в контракте, чтобы обе стороны интеграции понимали правила одинаково.

Заголовки и ответы для повторов удобно описать в редакторе OpenAPI, идентификаторы и ключи сообщений — в AsyncAPI. Как выбрать между синхронной и асинхронной интеграцией — в статье «Синхронная и асинхронная интеграция».