Содержание
  1. Одинаковый эффект, разные ответы
  2. Состав серверного контракта
  3. Конфликт тела и конкурентный запрос
  4. Ключ и эффект в одной транзакции
  5. Почему внешний API меняет гарантию
  6. Истечение ключа и неизвестный исход
  7. Заполненная матрица контрольных случаев
  8. Частые вопросы
Справочник

Что такое идемпотентность: как безопасно повторять запросы

15 ноября 2026 · 14 минут чтения

Что такое идемпотентность: как безопасно повторять запросы — это свойство метода или операции давать один и тот же намеченный эффект на сервере при одном запросе и при нескольких одинаковых запросах. В глоссарии MDN сказано: метод HTTP идемпотентен, если намеченный эффект одного запроса совпадает с эффектом нескольких идентичных запросов. Ответы при этом различаются, а повтор безопасен только внутри контракта конкретного API.

Одинаковый эффект, разные ответы

Идемпотентность описывает намеченный эффект операции. Глоссарий MDN формулирует это прямо: метод HTTP идемпотентен, если намеченный эффект на сервере от одного запроса совпадает с эффектом от нескольких идентичных запросов. Ключевое слово здесь — намеченный. Клиент просит создать заявку на 10:00 для человека P17 или удалить ресурс. Сервер обязан привести систему к состоянию, соответствующему этому намерению, сколько бы раз запрос ни пришёл.

Ответы при повторе совпадать не обязаны. Та же страница MDN приводит пример: первый вызов DELETE, скорее всего, вернёт 200, а последующие — 404. Ресурс уже удалён, намерение выполнено, но текст ответа изменился. Из этого следует практический вывод для клиента: повторять запрос можно тогда, когда вы сверяете намеченный эффект. Побайтовое равенство ответов для этого не требуется. Логика «ответ другой — значит операция не прошла» приводит к лишним повторам и лишним эффектам.

Физических обращений к серверу тоже может быть несколько. Журнал доступа зафиксирует каждое. Идемпотентность описывает намеченный эффект на данных. Число строк в логе может увеличиваться с каждым обращением. Эти уровни проверяются раздельно.

Есть и вторая граница. MDN напоминает: серверы поощряются следовать семантике HTTP-спецификации, однако спецификация этого не предписывает. Идемпотентность метода в стандарте — это ожидание, которое конкретный сервер реализует по-своему. Контракт конкретного API сверяют с документацией и проверяют в безопасной тестовой среде.

Практический порядок для читателя выглядит так. Сначала вы формулируете намеченный эффект словами: в системе существует ровно одна заявка R701 на слот 10:00 для P17. Затем проверяете, какие ответы сервер может вернуть при повторе и какие из них означают «эффект уже достигнут». После этого решаете, где ставить повтор, а где — сверку состояния. Такой порядок переносит вопрос из плоскости «какой код ответа пришёл» в плоскость «в каком состоянии данные».

Состав серверного контракта

Идемпотентность на сервере — это набор полей и правил, которые сервер обязуется соблюдать. Документация Stripe описывает базовую механику: клиент генерирует ключ идемпотентности, уникальный ключ, который сервер использует для распознавания последующих повторов того же запроса. Без такого ключа сервер видит два одинаковых POST и не может отличить повтор от нового намерения.

В учебном примере этой статьи сервер хранит пять вещей: key, body_fingerprint, state, result_reference и время. Ключ K=consultation-17:create обозначает операцию. Отпечаток тела H1={slot:10:00,person:P17} фиксирует параметры намерения. Состояние принимает значения pending, completed или unknown. Ссылка на результат хранит идентификатор созданной заявки. Время нужно для политики хранения и истечения записи. Это проект поведения. Реализация и испытания сервера здесь не выполнялись. Обозначения H1/H2 условно представляют нормализованные отпечатки тела; это не настоящие криптографические хэши.

Поле записи Что фиксирует Зачем нужно при повторе
key Идентификатор операции от клиента Отличить повтор от нового запроса
body_fingerprint Отпечаток нормализованного тела Обнаружить конфликт параметров
state pending, completed, unknown Понять, достигнут ли эффект
result_reference Ссылка на созданный объект Вернуть тот же результат
время Момент записи Управлять сроком хранения

Документация AWS Well-Architected добавляет требование к состоянию: поддерживайте состояние каждой операции или запроса в вашей нагрузке. Запись без состояния не отвечает на вопрос «эффект уже был». Документация AWS Well-Architected также советует регулярно удалять старые токены идемпотентности из хранилища, чтобы управлять объёмом и производительностью. Хранение вечное и хранение нулевое одинаково ломают контракт: в первом случае база растёт, во втором теряется память об операции.

Ключ приходит от клиента. Библиотека AWS Builders Library описывает предпочтительный подход Amazon: включать в контракт API уникальный идентификатор клиентского запроса, который передаёт вызывающая сторона. Клиент знает, что он повторяет именно свою операцию, и передаёт эту связь на сервер явно.

Что сервер обещает клиенту при корректном повторе: тот же намеченный эффект, ссылку на тот же результат и явную ошибку при несовпадении параметров. Чего контракт не обещает: одинакового тела ответа, одинакового кода ответа и ровно одного физического выполнения. Эти три ожидания выходят за рамки идемпотентности и требуют отдельных механизмов.

Конфликт тела и конкурентный запрос

Два разных сценария ломают наивную реализацию: клиент присылает тот же ключ с другим телом, и два клиента приходят одновременно с одним ключом. Разберём оба на учебном примере.

Конфликт тела. Клиент C приходит с ключом K=consultation-17:create и телом H2={slot:11:00,person:P17}. Ключ тот же, намерение другое. Сервер сравнивает отпечаток тела с сохранённым H1 и отвергает конфликт параметров. Он не возвращает молча заявку R701 как заявку на 11:00 и не создаёт вторую заявку под тем же ключом. Библиотека AWS Builders Library объясняет логику: безопаснее предположить, что клиент имел в виду другой результат и что это может быть другой запрос. Молчаливый возврат старого результата скрыл бы от клиента, что его новое намерение не выполнено.

Конкурентный запрос. Клиент A начинает транзакцию, резервирует уникальный K с отпечатком H1, вставляет заявку R701 и сохраняет результат. Уникален ключ; отпечаток проверяет параметры. До commit успех клиенту не подтверждён. В этот момент клиент B приходит с той же парой K/H1. Уникальность ключа не разрешает B независимо создать R702. По выбранной политике B ждёт завершения первой транзакции или получает ответ «обработка продолжается». Второй эффект не выполняется.

Дальше возможны два исхода. Если A делает commit, существуют ровно один ключ K/H1 в состоянии completed со ссылкой R701 и одна заявка R701. B после повторного чтения получает ссылку на R701. Если A делает rollback до commit, ни ключ, ни заявка не сохранились, и следующий запрос может заново выполнить локальную операцию. Инвариант проверяется одновременно по таблице ключей и таблице заявок.

Документация AWS Well-Architected называет инструмент для этого случая: поддерживайте согласованность и атомарность с помощью подходящих механизмов управления конкурентным доступом, таких как блокировки, транзакции или оптимистичный контроль версий. Уникальный индекс по ключу сам по себе не решает задачу целиком: он защищает от дубля ключа, а согласованность ключа, заявки и результата обеспечивает транзакция.

Сценарий Вход Ожидаемое поведение сервера
Повтор K/H1, состояние completed Вернуть ссылку на R701
Конфликт K/H2 Явная ошибка конфликта параметров
Конкурент K/H1 от двух клиентов Один эффект, второй ждёт или получает pending
Откат K/H1, rollback до commit Ни ключа, ни заявки, повтор допустим

Ключ и эффект в одной транзакции

Атомарность — это требование к записи ключа, записи эффекта и записи результата. Библиотека AWS Builders Library формулирует его так: процесс, который объединяет запись токена идемпотентности и все изменяющие операции по обслуживанию запроса, должен обладать свойствами атомарной, согласованной, изолированной и долговечной операции. Сокращённо это ACID.

Практический смысл для читателя прост. Если ключ записывается в одной транзакции, а заявка — в другой, между ними появляется окно. Сервер упал после записи ключа и до записи заявки. При повторе он видит ключ со ссылкой на несуществующую заявку. Сервер ошибочно сообщает об успехе при отсутствии данных.

Порядок действий внутри одной транзакции:

  1. Начать транзакцию.
  2. Зарезервировать уникальный K с отпечатком H1. При повторе ключа сравнить отпечатки, включая конфликт K/H2.
  3. Вставить заявку R701 в таблицу заявок.
  4. Записать ссылку на R701 и состояние completed в запись ключа.
  5. Выполнить commit.

До шага 5 успех клиенту не подтверждается. Если на шаге 2 уникальность нарушена, транзакция откатывается и сервер переходит к чтению существующей записи. Если отказ произошёл на шагах 3–4, откат убирает и ключ, и заявку. Следующий запрос с той же парой K/H1 выполнит операцию заново, и это корректно: эффекта не было.

Проверка инварианта идёт по двум таблицам. Запрос есть ли ключ K/H1 в состоянии completed и запрос «есть ли заявка R701» должны давать согласованный ответ. Проверка одного ключа пропускает случай, когда ключ есть, а заявки нет. Документация AWS Well-Architected прямо называет поддержание состояния каждой операции отдельным требованием, и это требование проверяется на уровне данных.

Отдельная тонкость — момент фиксации результата. Документация Stripe для API v1 сообщает: результаты сохраняются только после того, как начинается выполнение эндпоинта. Это значит, что запрос, отклонённый до начала выполнения, не оставляет кэшированного результата. Правило относится к API v1 Stripe и переносится на другие версии и произвольные API только после проверки их документации.

Почему внешний API меняет гарантию

Локальная транзакция охватывает вашу базу. Внешнее действие в чужом API в неё не входит. Это граница, за которой гарантия меняется, и её стоит разобрать отдельно.

Учебный сценарий. Локально записана пара K/H1 в состоянии pending. Запрос на создание внешней заявки отправлен, ответ потерян. Локальное pending не доказывает ни отсутствия, ни наличия внешней заявки. Вы знаете только то, что отправили запрос и не получили подтверждения.

Повтор с той же парой K/H1 видит pending. Сервер не отправляет ещё один неизвестный POST вслепую. Сначала выполняется документированный поиск по ключу или идентификатору операции, который поддерживает внешний API, либо допустимый протокол повторения этого API. Если поиск подтвердил внешнюю заявку R900, локально записывается состояние completed со ссылкой R900. Если поиск не даёт определённого результата, состояние остаётся unknown, и запускается эскалация или отложенная сверка. Новый эффект не выдаётся за безопасный.

Передача заголовка Idempotency-Key работает в границах контракта поддерживающего его провайдера. Произвольному API этот заголовок сам по себе гарантию не добавляет.

Документация Stripe для API v1 сообщает, что сохраняются код состояния и тело первого запроса с данным ключом идемпотентности после начала выполнения эндпоинта. Правило кэширования ошибок в API v1 Stripe привязано к этой версии. Переносить его на API v2 Stripe или на произвольное API нельзя: у другой версии и другого провайдера свои правила хранения и свои коды.

Уровень Что покрывает транзакция Что остаётся неизвестным
Локальная БД Ключ, заявка, результат При потере ответа состояние проверяют в этой БД
Внешний API Ничего Был ли внешний эффект
Смешанный случай Локальная запись pending Наличие внешней заявки

Практический вывод: для внешнего действия проектируйте отдельное состояние unknown и отдельный путь сверки. Считать внешний вызов частью локальной транзакции нельзя, и обещание exactly-once для такой связки давать нельзя.

Истечение ключа и неизвестный исход

Записи ключей удаляются. Документация AWS Well-Architected советует регулярно удалять старые токены идемпотентности из хранилища, чтобы управлять объёмом и производительностью. Удаление решает задачу хранения и создаёт новую границу: после истечения записи сервер теряет память об операции.

Учебный сценарий E4. Запись ключа K истекла или удалена. Отсутствие локального ключа не доказывает, что внешнего эффекта не было. До нового действия проверяют внешний факт и срок гарантии провайдера. Если провайдер хранит свои ключи ограниченное время, после этого срока поиск по ключу тоже не даст ответа, и состояние остаётся unknown.

Отсюда следует правило проектирования: срок хранения вашей записи ключа должен быть не короче срока, в течение которого вы готовы отвечать на повторы. Если клиент может повторить запрос через сутки, а запись живёт час, второй запрос после истечения создаст второй эффект. Это не ошибка идемпотентности, это несоответствие политики хранения и профиля повторов.

Состояние unknown требует явного обращения. Варианты: эскалация оператору, отложенная сверка по расписанию, запрос к внешнему API по идентификатору операции. Молчаливый повтор в состоянии unknown превращает неизвестность в дубль. Молчаливый отказ превращает неизвестность в потерянный заказ. Оба варианта хуже явной обработки.

Документация Azure Architecture Center даёт рамку для повторов в целом: рассматривайте, является ли операция идемпотентной, и реализуйте логику повтора только там, где полностью понятен контекст сбойной операции. Та же документация предупреждает: агрессивная политика повторов с минимальной задержкой и большим числом попыток может дополнительно нагрузить сервис, работающий на пределе или близко к нему. Повтор — это нагрузка, и её стоит ограничивать.

Порядок обработки истечения записи:

  1. Получить запрос с ключом, которого нет в хранилище.
  2. Проверить внешний факт по идентификатору операции, если внешний API это поддерживает.
  3. Если внешний факт подтверждён, записать локально completed со ссылкой.
  4. Если внешний факт не подтверждён и срок гарантии провайдера истёк, оставить unknown и передать на сверку.
  5. Новый эффект выполнять только после явного решения по шагу 4.

Заполненная матрица контрольных случаев

Ниже — сводка проверок, которые стоит прогнать на своём API перед тем, как считать контракт идемпотентности готовым. Каждая строка — отдельный тест с ожидаемым результатом.

№ Вход Ожидаемый результат
1 Повтор K/H1 после completed Ссылка на R701, число заявок не выросло
2 Запрос K/H2 при сохранённом H1 Явная ошибка конфликта параметров
3 Два одновременных K/H1 Один эффект, второй ждёт или получает pending
4 Rollback до commit Ни ключа, ни заявки, повтор допустим
5 Внешний вызов, ответ потерян Состояние pending, поиск перед повтором
6 Поиск подтвердил внешнюю R900 Локально completed со ссылкой R900
7 Поиск не дал ответа Состояние unknown, сверка
Истечение Запись ключа истекла Проверка внешнего факта до нового эффекта

При проверке своего API используйте следующие инварианты: повтор K/H1 не увеличивает число локальных заявок; K/H2 даёт явный конфликт; конкурентный B не становится вторым исполнителем; rollback не оставляет успешный ключ без заявки; удалённый неизвестный результат остаётся неизвестным; истечение записи не разрешает слепой повтор. Фиксированные коды ответа и срок жизни записи — решение конкретного API, и в этом разборе они не выдуманы.

Как пользоваться матрицей. Прогоняйте строки 1–4 на локальной базе, случаи внешнего вызова и истечения — на тестовой интеграции с внешним сервисом. Строка 3 требует реальной параллельности: два потока с одним ключом, запущенные одновременно. Строка 4 требует принудительного отката между записью ключа и записью заявки. Случай истечения требует сокращённого срока хранения в тестовой среде.

Что матрица проверяет по существу. Она отделяет идемпотентность от exactly-once: строки 5–7 показывают, что при внешнем вызове возможен исход unknown, и это нормальное состояние контракта. Она отделяет идемпотентность от одинаковых ответов: строка 1 допускает разные коды при одном эффекте. Она отделяет ключ от эффекта: строки 2 и 4 показывают, что запись ключа сама по себе ничего не гарантирует.

Промпт для разбора своего API по этой матрице:

ТЕКСТ11 строк
Ты помогаешь разобрать серверный контракт идемпотентности для API.
Вход: [название и версия API], [метод и путь], [какие поля тела участвуют в намерении],
[где хранится ключ идемпотентности], [срок хранения записи ключа],
[вызывает ли операция внешний API и какой].
Задача: заполни матрицу из восьми контрольных случаев.
Для каждого случая укажи вход, ожидаемое поведение сервера, что проверяется в базе
и какой исход остаётся неизвестным.
Отдельно перечисли, какие гарантии контракт даёт клиенту, а какие остаются
за пределами идемпотентности.
Не выдумывай коды ответа, сроки и лимиты: если значение неизвестно, помечай его
как параметр для проверки в документации провайдера.

В промпте замените квадратные скобки на свои значения: название и версию API, метод и путь, состав тела, место хранения ключа, срок хранения и наличие внешнего вызова. Если внешнего вызова нет, внешние сценарии заполняются как неприменимые, и это тоже полезный результат разбора.

Частые вопросы

Что такое идемпотентность простыми словами?
Это свойство операции давать один и тот же намеченный эффект при одном запросе и при нескольких одинаковых запросах. Глоссарий MDN определяет так методы HTTP: намеченный эффект одного запроса совпадает с эффектом нескольких идентичных. Ответы при повторе могут различаться, а состояние данных остаётся соответствующим намерению клиента.

Идемпотентность REST и HTTP методов — это одно и то же?
Речь об одном свойстве на разных уровнях. Метод HTTP объявляет идемпотентность как часть семантики, а конкретный сервер реализует её в своём контракте. MDN напоминает, что серверы поощряются следовать семантике спецификации, однако спецификация этого не предписывает. Проверять поведение приходится на живом API.

Почему DELETE сначала даёт 200, а потом 404?
Первый вызов удаляет ресурс и сообщает об успехе. Второй вызов находит ресурс уже удалённым и сообщает, что объекта нет. Намеченный эффект достигнут в обоих случаях. Глоссарий MDN приводит именно этот пример: первый вызов DELETE, скорее всего, вернёт 200, а последующие — 404.

Зачем нужен ключ идемпотентности, если метод уже идемпотентен?
Метод описывает ожидание, а ключ передаёт конкретную операцию. Документация Stripe описывает механику: клиент генерирует ключ идемпотентности, а сервер использует его для распознавания последующих повторов того же запроса. Без ключа сервер видит два одинаковых POST и не отличает повтор от нового намерения.

Что делать, если ответ внешнего API потерян?
Зафиксировать состояние pending и выполнить документированный поиск по ключу или идентификатору операции. Если поиск подтвердил внешний результат, записать локально completed со ссылкой. Если определённого ответа нет, оставить состояние unknown и запустить сверку. Слепой повтор в этом состоянии может создать второй эффект.

Читайте также

3 материала