Это многоразовый рабочий шаблон, а не результат измерений Folkbench для какого-либо прокси. Измерением Folkbench считается только опубликованный срез данных, в котором указаны прогон, время, выборка и ограничения.
Цель
Прежде чем подключать API-прокси к рабочей интеграции, убедитесь, что работает минимальный путь запроса, и разделите сбои на четыре класса: ошибки клиента, протокола, вышестоящего поставщика и самого сервиса. Другой инженер должен суметь повторить проверку с тем же запросом.
Перед началом
Подготовьте фиксированный образец запроса без реальных пользовательских данных. Запишите ID модели, тело запроса, режим потоковой передачи, таймаут, лимит повторных попыток и время теста. Тестовые учётные данные храните в локальном менеджере секретов или во временной переменной окружения и никогда не записывайте их в логи, на скриншоты, в репозиторий или на публичную страницу.
Шаг 1. Зафиксируйте запрос и границы наблюдения
Начните с минимального запроса и сверьте HTTP-статус, заголовки и тело ответа с документацией провайдера. Занесите в тестовую таблицу ID запроса, ID модели, статус и общую длительность. Не вставляйте в тикет полный заголовок Authorization или необработанный ответ.
Если эндпоинт поддерживает потоковую передачу, выполните отдельный потоковый запрос. Зафиксируйте время до первого полезного фрагмента данных, продолжают ли фрагменты поступать, появляется ли событие завершения и получает ли клиент явный результат при закрытии соединения. SSE — это поток событий: разбирайте его по границам событий, а не пытайтесь угадать токены по границам сетевых пакетов.
Шаг 2. Классифицируйте сбои
На фиксированных входных данных проверьте каждый случай:
- Ошибка клиента: неверная модель, отсутствующий параметр или превышение лимита запросов должны давать ответ 4xx, по которому можно определить причину.
- Ошибка аутентификации: просроченные учётные данные или учётные данные без нужных прав должны однозначно отклоняться, причём ответ не должен раскрывать другие учётные данные или внутренние адреса.
- Ошибка вышестоящего поставщика: при таймаутах, ограничении частоты запросов и временной недоступности на его стороне должно быть понятно, допустим ли повтор.
- Сбой потока: обрыв соединения, отсутствие события завершения или неполное JSON-событие должны уводить запрос в ветку обработки сбоя, а не считаться завершённым текстом.
Для каждого сбоя сохраняйте как минимум статус, класс ошибки, время наблюдения на клиенте и короткую сводку без чувствительных данных. Необработанные ответы, трассировки и скриншоты — это доказательства процесса: храните их по правилам закрытого объектного хранилища и не допускайте в публичные статьи и рейтинги.
Шаг 3. Задайте границы повторных попыток
Повторяйте только запросы с явной семантикой идемпотентности или те, которые заведомо безопасно отправить ещё раз. Задайте общий бюджет повторных попыток и свяжите ID первого и последнего запросов. Не повторяйте вслепую запросы, отклонённые из-за ошибки аутентификации, неверных параметров или модерации контента.
Наглядная таблица приёмки может выглядеть так:
| Проверка | Условие прохождения | Действие при сбое |
|---|---|---|
| Статус | Соответствует документированному контракту | Сохранить сводку без чувствительных данных и классифицировать |
| Первый байт | Полезные данные приходят в пределах согласованного таймаута | Проверить сеть, маршрут и вышестоящего поставщика |
| Завершение потока | Приходит корректное событие завершения или полный ответ | Отметить сбой соединения |
| Класс ошибки | 4xx, 5xx и таймауты различимы | Никогда не считать ошибку ответом модели |
| Повтор | Число попыток и общее время можно отследить | Остановиться, когда бюджет исчерпан |
Критерии прохождения и очистка
Запишите критерии прохождения до начала теста, например: «фиксированный запрос возвращает полный результат в трёх независимых попытках, у потока есть явное событие завершения, а сбои аутентификации никогда не повторяются». Не меняйте критерии после того, как увидели результат.
После теста отзовите временные учётные данные, удалите локальные необработанные ответы и сохраните запись, в которой есть только сводки, временные метки и версии. Чтобы опубликовать результат в Folkbench, сначала свяжите его с реальным прогоном и попыткой (run/attempt), манифестом доказательств и опубликованным срезом данных; эта статья такие факты не заменяет.
