Claude API: контрактный тест streaming до релиза

Сделайте контракт узким и проверяемым

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

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

Обрабатывайте отключение клиента отдельно

Браузер может закрыть соединение, пока сервер ещё получает фрагменты. Свяжите соединение с внутренним request ID и прекратите локальную доставку, когда клиент исчез. Не делайте вывод о результате модели только по этому событию: для приложения это может быть неизвестный итог, который требует безопасного завершения.

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

Проверяйте stop reason в своём слое

Причину завершения сначала нормализуйте в небольшое локальное множество: ожидаемое завершение, локальный дедлайн, ошибка схемы, отключённый клиент или неизвестное состояние. Не превращайте текстовое поле внешнего ответа в бизнес-разрешение. Для чувствительного действия ваш код должен требовать собственное подтверждение независимо от того, как завершился поток.

Тестируйте пропущенное событие, лишнее поле, пустой фрагмент и окончание без ожидаемого маркера. Успешный результат — не отсутствие ошибок в логах, а предсказуемое действие на каждом варианте. В частности, неизвестное состояние не должно считаться готовым ответом или поводом скрытно отправить запрос заново.

Публикуйте после canary и rollback-плана

Перед расширением трафика проведите canary для разрешённого сценария и наблюдайте локальные метрики: процент корректных цепочек, обрывы, ошибки схемы и размер буфера. Не записывайте сами фрагменты ответа ради метрик. При расхождении выключите streaming-ветку или направьте сценарий на review согласно своей policy.

Для смежных проверок используйте обработку stop reason, проверку tool result и частичный streaming-ответ. Эти ссылки помогают проектировать локальный адаптер, но не доказывают постоянную совместимость внешнего API.

Сначала зафиксируйте границу решения

Название модели, HTTP-статус или успешный тест не заменяют решение приложения. До интеграции команда определяет, кто может запускать задачу, какой сценарий разрешён, что считать неизвестным результатом и когда требуется человек. Такая граница защищает продукт от скрытого автопереключения и от неверного вывода, будто внешний маршрут гарантирует бизнес-результат.

Проверяйте правила на синтетических значениях. Не кладите в fixture настоящий prompt, пользовательское вложение, cookie, авторизационный заголовок или ключ. Для технической записи обычно достаточно времени, версии адаптера, внутреннего operation ID, категории исхода и хэша нормализованной структуры. Это позволяет искать регрессии, не превращая журнал в копию пользовательских данных.

Проверяйте контракт небольшим сценарием

Минимальный контрактный тест должен различать корректный ответ, ошибку валидации, отказ локальной policy, временную сеть и неизвестный итог. Для каждого состояния заранее назначьте действие: безопасно остановить, повторить только идемпотентную операцию или передать её на review. Бесконечный retry не исправляет несовместимый формат и не доказывает, что внешнее действие не случилось.

Запишите дату, версию клиента и условия проверки. Если обновились SDK, каталог, формат ответа или ваш адаптер, повторите короткий синтетический тест до расширения трафика. Один удачный вызов показывает лишь наблюдаемый путь в конкретной конфигурации; он не является обещанием постоянной совместимости, качества или пропускной способности.

Минимизируйте технические данные

Не делайте секрет, полный пользовательский текст, исходный media URL или сырой ответ модели стандартным полем лога. Отделите понятное сообщение для пользователя от защищённой server-side записи. Доступ к журналам ограничьте ролями, а срок хранения определите локальной политикой и классификацией данных, а не предположением о правилах поставщика.

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

Оставьте обратимый путь

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

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

Разделите локальную policy и внешний сервис

Локальная allowlist, лимит очереди, ручная проверка и журнал — это функции вашего приложения. Они не равны каталогу моделей, внешнему rate limit, остаткам, SLA или сертификации поставщика. Такое разделение делает ответ пользователю честным: приложение управляет собственным риском, а свойства маршрута нужно подтверждать отдельно в актуальном каталоге, договоре и документации.

Ключ RussiaAPI используйте только на сервере через переменную окружения или совместимое хранилище секретов. Не переносите в новый gateway чужой ключ, cookie или Authorization header. Перед реальным запросом подтвердите доступный маршрут и model ID в своём аккаунте; пример ниже намеренно не вызывает сеть и не доказывает поддержку endpoint.

Планируйте отрицательные тесты

Happy path полезен, но не показывает, как система поведёт себя при пустом идентификаторе, неизвестном параметре, повторном событии, обрыве клиента или устаревшей версии policy. Добавьте такие случаи до релиза. Если проверка не может определить безопасный итог, верните локальную понятную ошибку или запросите review, а не пытайтесь угадать состояние задачи.

Регулярно пересматривайте владельца policy, тестовую дату и условия rollback. Чем проще структура решения, тем легче обнаружить изменение контракта. Не записывайте для этого полный prompt и не расширяйте права «на всякий случай»: наблюдаемость должна помогать разбирать проблему, а не создавать новую поверхность утечки.

Server-side пример без сетевого вызова

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

function acceptStreamEvent(state, event) {
  if (state.closed) return { ...state, action: 'ignore_after_close' };
  if (!['start', 'delta', 'stop'].includes(event.type)) return { ...state, closed: true, action: 'review_unknown_event' };
  if (event.type === 'delta' && event.text.length > 4096) return { ...state, closed: true, action: 'buffer_limit' };
  if (event.type === 'stop') return { ...state, closed: true, action: 'complete_if_schema_valid' };
  return { ...state, action: 'continue' };
}

Проверьте синтаксис через node --check, добавьте аутентификацию своего маршрута и негативные тесты. Не логируйте тело запроса или заголовки лишь ради отладки.

Источники для дальнейшей проверки

• Anthropic API: Streaming Messages
• MDN: Using server-sent events

Ссылки дают общий инженерный контекст. Перед production-изменением сопоставьте их со своим договором, текущим каталогом RussiaAPI и тестом конкретного маршрута.

FAQ

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

• Обработка Claude stop reason
• Проверка Claude tool result
• Частичный streaming-ответ