Зачем идемпотентность: безопасные retry

Бея нажимает “Оплатить” на странице оформления заказа. Wifi пропадает до того, как ответ долетает. Она нажимает снова. У сервера нет способа отличить второй клик от первого — он списывает дважды.

Проблема сетевых гарантий

Интернет гарантирует at-least-once доставку, если клиент повторяет запросы до получения ответа, и at-most-once, если никогда не повторяет. Ни то ни другое само по себе не работает:

• At-most-once — платёж, который не прошёл, потому что клиент сдался.
• At-least-once без дедупликации — двойное списание.

Закрыть этот разрыв — задача приложения. Инструмент — идемпотентность.

Что такое idempotency key

Idempotency key — это непрозрачная клиентская строка, обычно UUID v4 (36 символов), передаваемая в HTTP-заголовке Idempotency-Key. Клиент выбирает один ключ на логическую операцию, а не на запрос. Каждый retry той же операции использует тот же самый ключ.

Сервер использует ключ как основной токен для ответа на вопрос: “я уже это обрабатывал?” Если да — возвращает исходный ответ без повторного запуска бизнес-логики. Если нет — обрабатывает и сохраняет результат.

Метафора: конверт и журнал

Представь, что отправляешь деньги через курьера. Помечаешь конверт “Заказ #A7-payment” и говоришь: “Если этот конверт уже доставили — не доставляй снова”. На каждом retry пишешь тот же номер заказа на новом конверте. Получатель проверяет журнал (idempotency cache) и либо доставляет конверт, либо говорит “уже сделано — вот квитанция”.

Журнал помнит. Без него каждый конверт выглядит новым.

HTTP-конвенция

Stripe популяризировал заголовок Idempotency-Key в 2014 году. Square, PayPal, Adyen и IETF-черновик draft-ietf-httpapi-idempotency-key-header следуют той же форме. RFC 9110 §9.2.2 перечисляет идемпотентные по спецификации HTTP-методы (GET, HEAD, PUT, DELETE, OPTIONS) — POST в этом списке нет, именно поэтому заголовок и существует.