Если вы используете gRPC- или GraphQL-сервисы в продакшене, вы, вероятно, сталкивались с такой проблемой: в вашей коллекции Postman уже настроен запрос с правильной аутентификацией, переменными и тестовыми скриптами, но когда вы пытаетесь запланировать его выполнение в качестве Monitor, отображаются только HTTP-запросы. В результате вам приходится либо писать отдельную синтетическую проверку в другом инструменте, либо создавать небольшой скрипт для запуска CLI по cron. Оба варианта работают. Но оба далеки от идеала.
Этот пробел постепенно закрывается. Postman Monitors теперь запускают gRPC и GraphQL запросы в режиме бета-тестирования. Я расскажу, как запланировать gRPC-вызов (включая стриминг), как отслеживать GraphQL-запрос (query) или мутацию (mutation), как выглядят ваши тестовые скрипты для каждого случая и куда отправлять отзывы, пока функция находится в разработке.
Что входит в бета-версию
Вот что бета-версия поддерживает на данный момент:
- Унарные gRPC-вызовы — стандартный паттерн запрос/ответ.
- gRPC со стримингом со стороны сервера (server-streaming), клиента (client-streaming) и двунаправленный (bidirectional), с некоторыми оговорками относительно стриминга, о которых я упомяну позже.
- GraphQL-запросы и мутации по протоколу HTTP.
- Существующие данные аутентификации, переменные и тестовые скрипты, которые переносятся из вашей коллекции без необходимости переписывания.
Что еще не вошло: подписки GraphQL (subscriptions), клиентский стриминг с несколькими сообщениями и более богатый набор хелперов для проверки стримов. Они находятся в дорожной карте.
Стоит отметить: это та же самая модель выполнения Monitors, которую вы уже знаете. Планировщик берет вашу коллекцию, выполняет запросы по порядку, оценивает тестовые скрипты и публикует результаты. Единственное, что изменилось, — это набор протоколов, которые понимает механизм выполнения.
Мониторинг gRPC-вызова
Начнем с самого простого случая: унарный gRPC-вызов к пользовательскому сервису. У вас уже есть запрос в коллекции, подключенный к .proto-файлу с выбранным методом. Чтобы запланировать его, нажмите правой кнопкой мыши по коллекции, выберите Create a monitor (Создать монитор) и настройте нужное расписание.
Для валидации gRPC-ответы используют тот же объект pm.response, который вы применяете для HTTP-тестов. Свойства просто адаптированы под gRPC:
Если статус gRPC возвращается отличным от OK, например UNAVAILABLE, DEADLINE_EXCEEDED или PERMISSION_DENIED, ваш монитор завершается с ошибкой, и вы получаете уведомление. Это полезное поведение по умолчанию. На практике я также проверяю структуру сообщения, поскольку нормальный статус с пустым телом ответа с точки зрения вызывающей стороны все равно означает сломанную конечную точку.
Для authentication, если вы используете gRPC-метаданные для Bearer-токенов, настройте их один раз для запроса, и они будут передаваться при каждом запуске монитора. Храните сам токен в переменной среды (Environment) монитора, но никогда — в определении запроса.
Мониторинг gRPC-стримов
Стриминг — это то, где все становится интереснее. Серверный стриминг (server-streaming) — главная особенность этой бета-версии: вы отправляете одно сообщение, сервер отправляет много, и вы можете проверять сообщения по мере их поступления.
У вас есть два варианта тестирования. Первый — хук скрипта On message, который выполняется для каждого сообщения, отправляемого сервером:
Второй вариант — проверка после завершения стрима на обычной вкладке Tests:
Лично я склоняюсь к проверкам после завершения стрима именно для Monitors. Проверки каждого сообщения полезны при отладке в реальном времени в клиенте, но когда монитор падает в 3 часа ночи, сообщение «стрим вернул 2 сообщения вместо 5» является гораздо более понятным сигналом, чем 20 результатов проверки отдельных сообщений.
Предупреждение о клиентском стриминге и двунаправленном стриминге: бета-версия в настоящее время поддерживает только одно клиентское сообщение на вызов. Если ваш двунаправленный поток зависит от отправки последовательности сообщений обратно на сервер, дождитесь обновления с поддержкой множества сообщений, прежде чем переносить эту проверку в монитор. Унарный и серверный стриминг — это те сценарии, которые отлично работают уже сегодня.
Мониторинг GraphQL-запросов и мутаций
Запросы GraphQL «под капотом» являются HTTP-запросами, но модель сбоев в них отличается настолько, что о ней стоит упомянуть отдельно. GraphQL-сервер может вернуть статус 200 OK с телом, полным ошибок, поэтому простая проверка кода состояния покажет успех, даже если ваше API сломано.
Вот запрос, который я использую в качестве шаблона для GraphQL Monitors:
pm.response.data и pm.response.errors — это два свойства, которые здесь имеют наибольшее значение. Вместе они показывают, действительно ли операция прошла успешно с точки зрения клиента, что и должен проверять монитор.
Для мутации я бы также проверял возвращаемую сущность, чтобы отловить случаи, когда сервер принимает мутацию, но молча отбрасывает поля. Что-то вроде:
Подписки (Subscriptions) пока не входят в бета-версию. Если вы зависите от них, пока оставьте свои текущие проверки подписок на месте.
Настройка расписания
Как только в ваших запросах появятся тесты, настройка расписания будет такой же, как и для любого другого монитора. Выберите частоту (от каждых 5 минут до еженедельной), укажите регион, если вам важен географический охват, прикрепите Environment с вашими учетными данными и включите уведомления. Обычно для нового монитора я начинаю с 15-ми интервалов и сокращаю их после недели стабильной работы. Запуск ресурсоемких запросов каждую минуту во время настройки быстро накапливается.
Два совета из опыта запуска этого на моих собственных сервисах:
- Используйте выделенную среду (Monitor Environment). Не используйте повторно вашу локальную среду разработки. Создайте среду только с теми переменными, которые нужны монитору, используйте секретные переменные для токенов и обновляйте их по тому же графику, что и все остальное.
- Держите коллекцию сфокусированной. Монитор должен проверять что-то одно: критическое чтение, мутацию для проверки работоспособности (health-check) или пульс стриминга. Если он падает, вы хотите точно знать, что сломалось. Коллекция из 30 запросов с одним падающим тестом посередине — это квест по отладке, который вам вряд ли захочется решать в 3 часа ночи.
Отзывы во время бета-тестирования
Это бета-версия, и команда внимательно прислушивается к отзывам. Если вы столкнетесь с шероховатостями — например, хук скрипта ведет себя не так, как ожидалось, .proto-файл не загружается или вам не хватает какой-то метрики в отчете о запуске, — откройте тикет в репозитории postman-app-support на GitHub. Четко пометьте его (gRPC или GraphQL, Monitors) и включите структуру коллекции вместе с выводом ошибок. Что команда просила указать в первую очередь:
- Какие паттерны стриминга вы хотели бы видеть поддерживаемыми в следующем релизе
- Сценарии использования подписок GraphQL, которые вы бы перенесли в Monitors, если бы они были доступны
- Вспомогательные функции для проверок (assertion helpers), которые вам нужны для стриминговых ответов
Дорожная карта уже включает клиентский стриминг с множеством сообщений, подписки GraphQL и более богатый набор проверок для стримов, но порядок реализации зависит от того, что именно люди пытаются сделать на практике.
Итоги
Краткая версия: если у вас в коллекции был gRPC- или GraphQL-запрос, который вы хотели запускать по расписанию, теперь вы можете сделать это без переключения инструментов. Унарный gRPC, gRPC со стримингом от сервера, а также GraphQL-запросы и мутации уже готовы. Клиентский стриминг с несколькими сообщениями, двунаправленный стриминг с несколькими сообщениями и подписки GraphQL находятся в разработке.
Что мне нравится в этом релизе — он не требует от вас ничего переписывать. Тот же запрос, та же аутентификация, те же тестовые скрипты — теперь они просто работают по расписанию. Именно так и нужно выпускать функции для Monitors.
Попробуйте запустить монитор для сервиса, который вам действительно важен, понаблюдайте за несколькими запусками и отправьте отзыв с тем, что бы вы хотели увидеть дальше. Бета-версии развиваются быстрее, когда отзывы носят конкретный характер.
Ресурсы
- Документация по Postman Monitors: Обзор принципов работы мониторов, параметров планирования и настройки уведомлений.
- Написание тестов в Postman: Справочник по pm.test, pm.response и модели скриптов, используемой в мониторах gRPC и GraphQL.
- gRPC в Postman: Как работают gRPC-запросы, файлы .proto и потоковая передача в клиенте Postman.
- GraphQL в Postman: Как создавать и отправлять запросы и мутации GraphQL в коллекции.
- Проблемы postman-app-support на GitHub: Место для отправки отзывов о бета-версии, сообщений об ошибках и запросов функций.
- Официальная документация gRPC: Справочные материалы по унарным, серверным потоковым, клиентским потоковым и двунаправленным шаблонам RPC.
