Что такое idempotency и как сделать endpoint идемпотентным

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

Операция идемпотентна, если её повторный вызов не меняет итоговое состояние после первого успешного выполнения. Например, повторный PUT с одинаковым телом должен привести ресурс к тому же состоянию, а повторный запрос на создание платежа без защиты может случайно списать деньги дважды.

HTTP и идемпотентность

GET обычно безопасен и идемпотентен;
PUT и DELETE обычно проектируют идемпотентными;
POST по умолчанию не обязан быть идемпотентным, но его часто делают таким для критичных операций.

Idempotency key

Клиент генерирует уникальный ключ для логической операции и передаёт его в заголовке. Сервер хранит ключ, хеш запроса, статус выполнения и ответ.

POST /api/payments
Idempotency-Key: 78f30e14-2f1f-4c64-a0db-4bc38c1bd301

Алгоритм обработки

Проверить наличие idempotency key.
Попытаться атомарно создать запись с этим ключом и статусом processing.
Если ключ уже существует, сравнить хеш запроса и вернуть сохранённый результат либо статус обработки.
Выполнить бизнес-операцию в транзакции.
Сохранить итоговый status code и response body для повторных запросов.

idempotency_records:
  key: string, unique
  request_hash: string
  status: processing | completed | failed
  response_status: integer
  response_body: json
  created_at: timestamp
  expires_at: timestamp

Важные детали

ключ должен быть уникальным в scope пользователя или tenant;
один ключ нельзя использовать с другим payload;
нужен TTL и очистка старых idempotency records;
для конкурентных запросов нужна уникальность в БД или распределённая блокировка;
внешний provider оплаты также должен получать тот же idempotency key, если он это поддерживает.

Как ответить на собеседовании

Идемпотентность означает, что повторный одинаковый запрос не создаёт новый побочный эффект. Для POST создания заказа или платежа я принимаю Idempotency-Key, атомарно сохраняю его вместе с хешем payload и результатом первого запроса, а при повторе возвращаю сохранённый response. Это позволяет безопасно делать retry после сетевых ошибок.

Что такое idempotency? Как сделать endpoint идемпотентным?