re:re:actable
Урок 033 минуты чтения

Что такое safe и idempotent методы и Idempotency-Key?

На этой странице
Кратко

Safe method не должен менять состояние сервера. Idempotent method можно повторить несколько раз, и итоговое состояние будет таким же, как после одного запроса. Для неидемпотентных операций (платежи, заказы) используют Idempotency-Key. Эти свойства важны для кеширования, retries и проектирования REST API.

Вопрос

Что значит safe и idempotent? Какие методы такими являются? Как защитить POST /payments от двойного выполнения?

Safe methods

Safe method предназначен для чтения.

GET /api/articles
HEAD /api/articles/1
OPTIONS /api/articles/1

GET может писать технические логи или метрики, но не должен создавать заказ, списывать деньги или менять профиль пользователя.

Плохой пример:

GET /api/orders/create?productId=10

Такой endpoint опасен: browser, crawler, prefetch или cache layer могут выполнить GET, не ожидая изменения данных. Кроме того, state-changing GET легко эксплуатировать через CSRF: достаточно <img src="..."> на чужой странице.

Idempotent methods

Idempotent значит: один и тот же запрос можно повторить, а результат в системе останется тем же.

PUT /api/users/1
 
{
  "name": "Anna"
}

Если отправить этот PUT пять раз, имя все равно будет Anna.

DELETE /users/1 тоже обычно idempotent по смыслу: после первого удаления пользователя уже нет, после повторного он все еще отсутствует. Но конкретный status code может отличаться: первый раз 204, второй раз 404 или тоже 204. Идемпотентность — про состояние сервера, а не про одинаковый ответ.

POST обычно не idempotent

POST /api/orders
 
{
  "productId": 10,
  "quantity": 1
}

Если browser, mobile app или proxy повторит request (timeout, нестабильная сеть, двойной клик), можно создать два заказа.

Idempotency-Key

Для опасных POST операций клиент генерирует уникальный ключ и отправляет его в header:

POST /api/payments
Idempotency-Key: 5f7f8f6e-4d53-4c37-9f4f-1f9df5a1c101

Server сохраняет результат первого request с таким ключом. Если такой же request повторится, server вернет сохраненный результат, а не создаст новую операцию. Если с тем же ключом пришло другое тело запроса, сервер обычно отвечает 409 или 422.

const idempotencyKey = crypto.randomUUID(); // один ключ на одну попытку оплаты
 
async function pay(amount: number) {
  return fetch('/api/payments', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
    body: JSON.stringify({ amount }),
  });
}

Где это важно:

  • payments;
  • order creation;
  • booking;
  • sending email/SMS;
  • imports и file processing;
  • webhook handlers (провайдер может прислать событие повторно).

Таблица

МетодSafeIdempotent
GETдада
HEADдада
OPTIONSдада
PUTнетда
PATCHнетзависит от реализации
DELETEнетобычно да
POSTнетобычно нет

Frontend-угол

На frontend idempotency помогает пережить двойной клик, retry после timeout, нестабильную мобильную сеть и повторную отправку формы после refresh. Но кнопку все равно нужно блокировать на время submit: Idempotency-Key — защита backend-уровня, а не замена нормального UX.

Что важно помнить

  • Автоматические retries (в fetch-обертках, TanStack Query, axios-retry) безопасны только для idempotent запросов.
  • PATCH { "count": count + 1 } с вычислением на клиенте идемпотентен, а PATCH { "increment": 1 } — нет.
  • Ключ генерируется на одну логическую операцию: новый клик «Оплатить» после успешной оплаты — новый ключ.
  • Сервер хранит ключи ограниченное время (часто 24 часа) и должен атомарно обрабатывать одновременные запросы с одним ключом.

Мини-шпаргалка

  • Safe - не меняет состояние.
  • Idempotent - повтор не меняет итоговое состояние.
  • GET не должен выполнять действия.
  • POST может создать дубликаты при retry.
  • Idempotency-Key нужен для платежей, заказов и других критичных операций.

Документация

MDN: Safe methods, MDN: Idempotent, IETF: Idempotency-Key header (draft).

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам