Как реализовать идемпотентность HTTP POST-эндпоинта с помощью idempotency key?

Короткий ответ

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

Как это работает подробнее

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

Пример кода

example.sqlКопировать

CREATE TABLE idempotency_keys (
    key UUID PRIMARY KEY,
    status TEXT NOT NULL,
    response JSONB
);

Что использовать на практике

• Практика. Ключ хранят с уникальным ограничением в БД (или Redis с SETNX) вместе со статусом и сериализованным ответом; важно обрабатывать параллельные запросы с одним ключом.

Подводные камни

• Риск. Генерировать ключ на сервере (ретрай клиента создаст новый ключ, защита не сработает); не сохранять сам результат первой попытки, только факт «уже выполнено».