Клиент нажал «Оплатить», запрос ушёл в платёжный сервис, деньги списались — а ответ потерялся по дороге из-за обрыва связи. Мобильное приложение показывает ошибку, пользователь нажимает кнопку ещё раз. Если система не готова к такому сценарию, деньги спишутся дважды. Это не экзотика, а штатная ситуация в любой распределённой системе. Защита от неё называется идемпотентностью, и её нужно проектировать на этапе постановки задачи, а не добавлять после первой жалобы.
Почему повторы неизбежны
При сетевом вызове у клиента есть три возможных исхода: успешный ответ, ошибка и неизвестность — таймаут, обрыв соединения, сбой прокси. В третьем случае клиент не знает, выполнил ли сервер операцию. Варианты:
- операция не дошла до сервера;
- операция дошла, но упала до изменения данных;
- операция выполнилась, но потерялся ответ.
Единственный способ довести дело до конца — повторить запрос. Значит, сервер должен уметь отличить повтор от новой операции. В асинхронных интеграциях ситуация такая же: брокеры гарантируют доставку «хотя бы один раз», и при сбое получателя до подтверждения сообщение будет доставлено снова.
Источники повторов в реальной системе:
- пользователь нажимает кнопку повторно или обновляет страницу с формой;
- клиентская библиотека или 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.
Как сервер обрабатывает ключ
- Получив запрос, сервер ищет ключ в хранилище (таблица БД, Redis).
- Ключа нет — сервер атомарно сохраняет ключ со статусом «в обработке» и выполняет операцию. По завершении сохраняет результат: код ответа и тело.
- Ключ есть, операция завершена — сервер возвращает сохранённый ответ, не выполняя операцию заново.
- Ключ есть, операция ещё выполняется — сервер возвращает
409 Conflict(клиент повторит позже), а не запускает вторую параллельную обработку. - Ключ есть, но тело запроса другое — это ошибка клиента: тот же ключ для другой операции. Сервер возвращает
422, а не молча применяет старый результат.
Ключевой момент — атомарность: сохранение ключа и изменение бизнес-данных должны быть в одной транзакции, или ключ должен захватываться через уникальный индекс до начала операции. Иначе два параллельных повтора оба увидят «ключа нет» и выполнят операцию дважды.
Что решить при проектировании
- Кто генерирует ключ. Клиент, при создании намерения — например, при открытии формы оплаты, а не при нажатии кнопки. Иначе каждое нажатие получит новый ключ, и защита не сработает.
- Область действия. Ключ уникален в пределах клиента (партнёра, учётной записи) и операции.
- Срок хранения. Обычно от 24 часов до нескольких суток — дольше любого разумного окна повторов.
- Что возвращать при повторе. Тот же ответ, что в первый раз, включая код. Хорошая практика — дополнительный заголовок вроде
Idempotent-Replayed: true. - Сохранять ли ошибки. Ответы
4xxс бизнес-ошибкой обычно сохраняют (повтор не исправит ошибку в данных), а5xx— нет, чтобы повтор мог выполнить операцию.
Дедупликация в асинхронных интеграциях
В мире брокеров аналог ключа идемпотентности — идентификатор сообщения. Отправитель присваивает каждому сообщению уникальный messageId (например, по спецификации CloudEvents — поле id), получатель запоминает обработанные идентификаторы.
Шаблон Idempotent Consumer:
- Получатель начинает транзакцию в своей БД.
- Пытается вставить
messageIdв таблицу обработанных сообщений с уникальным индексом. - Если вставка не удалась — сообщение уже обработано, его можно подтвердить и пропустить.
- Если удалась — выполняет бизнес-логику в той же транзакции и фиксирует её.
- Только после фиксации подтверждает сообщение брокеру.
Если получатель упадёт между фиксацией и подтверждением, брокер доставит сообщение снова, но таблица дедупликации его отсеет.
Альтернатива — дедупликация по бизнес-ключу и версии: событие «остаток товара 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. Как выбрать между синхронной и асинхронной интеграцией — в статье «Синхронная и асинхронная интеграция».
