Что такое idempotency key?

Что такое idempotency key?

Idempotency key — это уникальный идентификатор, который клиент передаёт в HTTP-запросе (обычно в заголовке Idempotency-Key), чтобы сервер мог однозначно определить, что данный запрос уже был обработан. Если сервер получает запрос с ключом, который он уже видел, он не выполняет операцию повторно, а возвращает ранее сохранённый ответ. Это критически важно для операций, которые не являются идемпотентными по своей природе (например, создание платежа или заказа), чтобы избежать дублирования при повторных отправках.

Как это работает?

Клиент генерирует уникальный ключ (например, UUID) и отправляет его вместе с запросом. Сервер проверяет, есть ли в хранилище запись с таким ключом:

• Если нет — выполняет операцию, сохраняет ключ и результат, возвращает ответ.
• Если есть — возвращает сохранённый ответ, не выполняя операцию заново.

Ключ обычно хранится ограниченное время (например, 24 часа) и удаляется после истечения срока.

Пример кода (Node.js + Express)

const express = require('express');
const app = express();
const store = new Map(); // хранилище ключей

app.post('/payment', (req, res) => {
  const key = req.headers['idempotency-key'];
  if (!key) return res.status(400).send('Missing idempotency key');

  if (store.has(key)) {
    return res.json(store.get(key)); // возвращаем сохранённый ответ
  }

  // Выполняем операцию (например, списание средств)
  const result = { status: 'success', transactionId: Date.now() };
  store.set(key, result);
  setTimeout(() => store.delete(key), 86400000); // удаляем через 24 часа

  res.json(result);
});

app.listen(3000);

Где применяется?

• Платёжные системы (Stripe, PayPal) — чтобы не списать деньги дважды.
• Создание заказов в интернет-магазинах.
• Любые API, где повторный запрос может привести к дублированию данных.

Вывод

Idempotency key — это простой и надёжный способ сделать неидемпотентные операции безопасными для повторных вызовов. Его стоит применять везде, где клиент может отправить запрос повторно из-за таймаута или сбоя сети, чтобы гарантировать однократное выполнение.