Как проверить интеграцию на повторы и потерю ответа

Что записать в контракт интеграции и как проверить повтор, конкурентную доставку, тайм-аут и нарушение порядка. Без обещаний exactly-once по одному успешному запросу.

Интеграция может выполнить действие и потерять ответ по дороге к отправителю. Тогда тайм-аут оставляет неопределённость: действие не произошло или произошло, но подтверждение не дошло. Простое повторение запроса не всегда разрешает эту неопределённость безопасно.

Поэтому приёмка обмена должна включать повторы и восстановление. Ниже — авторская схема проверки для условной передачи задания между системами. Это не отчёт о проверенной клиентской интеграции.

Различайте событие и попытку

Событие обозначает рабочий факт или поручение, а попытка — отдельную доставку. При повторе прежнего события не стоит выдавать ему новый идентификатор: иначе приёмник может посчитать повтор новым действием.

До реализации договоритесь о ключе, области его уникальности и неизменном содержании. Отдельно определите реакцию на тот же ключ с другими данными. Это может быть конфликт, который нужно остановить и разобрать, а не очередная попытка.

В HTTP идемпотентность означает одинаковый ожидаемый эффект нескольких одинаковых запросов и одного запроса; ответы при этом могут различаться. RFC 9110, раздел 9.2.2 также ограничивает автоматический повтор неидемпотентных методов: нужны основания считать операцию идемпотентной или знать, что прежний запрос не был применён. Правило «повторять любой POST после тайм-аута» не описывает такой контракт.

Уточните, что означает подтверждение

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

Для условного задания можно предложить два состояния: «принято» и «выполнено». Если обработка происходит позже, нужен способ получить итог. Без него положительный ответ на доставку легко принять за успешное рабочее действие.

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

Проверьте матрицу сбоев

Каждый случай проверяют в согласованном тестовом окружении с условными данными. До запуска теста записывают ожидаемый эффект и свидетельство, по которому его можно установить.

Ситуация Что проверить
Тот же ключ доставлен повторно Второго рабочего изменения нет; результат повтора понятен
Две попытки пришли одновременно Применено одно допустимое изменение; конфликт обработан
Изменение выполнено, ответ потерян Отправитель может установить результат без слепого нового действия
Приёмник остановился в середине обработки После восстановления нет принятого за успех частичного результата
Тот же ключ пришёл с другим содержимым Система обнаруживает несовпадение
Более раннее событие пришло позже Оно не отменяет более новое состояние без предусмотренного правила

Таблицу можно прокручивать по горизонтали.

Порядок доставки зависит от провайдера. Например, Stripe документирует повторные доставки webhook-событий и не гарантирует их порядок. Это конкретный контракт Stripe, а не универсальная характеристика любого API. У своего приёмника проверьте документацию отдельно.

Отделите подлинность от обработки повтора

Проверка подписи отвечает на вопрос об источнике и целостности сообщения. Она не заменяет решение о том, применялось ли это рабочее событие ранее.

У провайдера должны быть собственные правила проверки сообщения. Для проверки webhook-подписи Stripe требуется исходное тело запроса без преобразований. Это требование указано в той же официальной документации. Переносить его технические детали на другого поставщика без чтения его контракта нельзя.

В тестах включите недопустимое сообщение и убедитесь, что рабочее состояние не изменилось. Само тестирование не требует раскрывать секреты в журнале или передавать реальные клиентские данные.

Опишите сверку и ручное восстановление

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

Для ручного повтора зафиксируйте разрешённое действие и способ установить его итог. Кнопка «повторить» без видимого результата не делает восстановление управляемым.

Если внешний API не позволяет распознать повтор или запросить результат, сообщите об этом как об ограничении. Не обещайте exactly-once — выполнение ровно одного эффекта — только потому, что один запрос прошёл успешно. Для обсуждения подготовьте контракт API, матрицу сбоев и доступные способы сверки: по ним можно согласовать реалистичный результат интеграции.

Что входит в интеграции и автоматизацию

Ещё по теме