GraphQL

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

Создание запроса GraphQLCopy Anchor Link

Выберите Файл › Новый запрос GraphQL или Новый запрос GraphQL в меню + рядом с Запросы в боковой панели. Введите конечную точку в поле адреса: для демо-магазина это {{baseURL}}/graphql. В рабочем пространстве Alpenglow такой запрос уже есть: Catalog › Search products.

В редакторе есть вкладки: Документация, Запрос, Переменные, Заголовки, Параметры, Авторизация, Переменные (собственные переменные запроса), Тесты, Скрипты и Настройки. Заголовки, авторизация, тесты и скрипты работают так же, как у запросов HTTP.

Запрос и переменныеCopy Anchor Link

Напишите запрос на вкладке Запрос:

query SearchProducts($text: String!, $first: Int = 10) {
  search(text: $text, first: $first) {
    totalCount
    nodes { sku name price { amount currency } rating stock { warehouse available } }
  }
}

а его переменные — в виде JSON на вкладке Переменные. Внутри JSON работают {{variables}}:

{
  "text": "{{searchTerm}}"
}

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

Отправьте запрос кнопкой Отправить или клавишами ⌘R.

Как отправляется запросCopy Anchor Link

Значок GQL перед адресом — это меню. В разделе Отправлять как:

Ниже ещё два переключателя:

• Постоянные запросы (APQ) сначала отправляет SHA-256-хеш запроса, без самого запроса. Если сервер отвечает, что не знает этот хеш, Echolot отправляет запрос повторно уже с текстом, чтобы сервер мог его сохранить.
• Объединять все операции в пакет отправляет все именованные операции документа вместе, одним массивом JSON.

СхемаCopy Anchor Link

Меню схемы находится справа на вкладке Запрос. Оно показывает файл схемы и число типов, например shop.graphql · … types, или Нет схемы.

• Загрузить с сервера выполняет запрос интроспекции по адресу запроса и сохраняет результат как файл в папке specs/ рабочего пространства. Выберите его снова, чтобы обновить схему.
• Использовать схему показывает файлы схем, которые уже есть в рабочем пространстве (.graphql, .graphqls и .json), чтобы выбрать один из них.
• Добавить файл схемы… принимает с вашего Mac файл SDL (.graphql) или результат интроспекции (.json).
• Показать обозреватель схемы открывает схему рядом с ответом.
• Не использовать эту схему убирает схему из запроса.

Файл схемы в specs/ могут использовать все запросы GraphQL к этому серверу, и его можно коммитить вместе с рабочим пространством. Когда загрузка заменяет файл схемы и схема изменилась, Схема изменилась перечисляет изменения как Ломающие, Опасные и Безопасные, например удалённое поле или новый обязательный аргумент. Ломающие изменения — те, из-за которых запросы, использующие удалённое или изменённое, перестают работать. В командной строке echolot graphql diff сравнивает две схемы так же: см. echolot graphql.

Если схему не удаётся прочитать, меню показывает Проблема схемы, а панель под запросом объясняет почему.

Дополнение, проблемы и подсказкиCopy Anchor Link

Со схемой редактор запроса помогает по мере ввода:

• Дополнение предлагает поля, аргументы, поля ввода, типы, значения enum, переменные, директивы и фрагменты, подходящие к месту курсора, вместе с их документацией. Устаревшие помечены.
• Проблемы подчёркиваются по мере ввода: неизвестные поля, неверные типы аргументов, пропущенные обязательные аргументы и другое. Панель под запросом показывает первую из них и считает ошибки и предупреждения; наведите на неё указатель, чтобы прочитать все.
• Подсказка при наведении на поле или тип показывает его сигнатуру и документацию, а также устарел ли он.
• Щелчок с ⌘ по полю или типу открывает его тип в обозревателе схемы.

Обозреватель схемы и конструкторCopy Anchor Link

Вкладка Схема области ответа показывает схему запроса, даже до первой отправки. Если у запроса ещё нет схемы, выберите там Загрузить с сервера.

Обзор начинается с Точек входа (Query, Mutation и Subscription). Нажмите тип, чтобы увидеть его поля, поля ввода, значения enum или типы, которые его реализуют или входят в него; устаревшее помечено. «Назад» возвращает к предыдущему типу. Искать типы и поля находит в схеме всё по имени.

Конструктор пишет запрос за вас. Выберите query, mutation или subscription в поле Операция, затем отмечайте поля в дереве: каждая отметка добавляет поле в текст запроса, а снятие отметки убирает его. Всё, что вы напечатали вокруг, сохраняется. Конструктор работает с операцией, названной в поле Операция, или с первой операцией этого вида в документе; если её нет, он добавляет новую.

ОтветыCopy Anchor Link

Ответ появляется на вкладке Тело в виде JSON, как любой ответ. Echolot также читает то, что GraphQL сообщает рядом с данными:

• N ошибок GraphQL в сводке ответа: сервер прислал массив errors, даже при HTTP 200. Нажмите, чтобы прочитать каждое сообщение и путь, к которому оно относится.
• Частичные данные: данные пришли вместе с ошибками, поэтому некоторые поля равны null из-за сбоя.
• Расширения: extensions ответа, например трассировка или сведения о стоимости.

Добавьте проверку Ошибки GraphQL, равную 0, на вкладке Тесты, чтобы прогон падал из-за них. См. скрипты и тесты.

Подписки и поэтапная доставкаCopy Anchor Link

Подписка продолжает присылать результаты, пока не завершится:

• По HTTP (POST или GET) Echolot запрашивает server-sent events, если операция — подписка.
• По WebSocket (graphql-transport-ws) Echolot открывает WebSocket, отправляет подписку с заголовками и авторизацией запроса и отвечает на пинги сервера.

Запрос с @defer или @stream приходит частями (multipart/mixed).

В обоих случаях в области ответа появляется вкладка События: каждое событие или часть по порядку, с номером, видом (например, next или part), идентификатором и ошибками. Для @defer и @stream Объединённый результат вверху показывает первый результат с применёнными ко всем последующим частям. Вкладка следит за новыми событиями, пока идёт поток, и показывает Прослушивание… «Остановить» завершает его. Выберите Отменить (⌘.), чтобы завершить поток. Начавшийся поток не обрывается общим тайм-аутом запроса.

Загрузка файловCopy Anchor Link

Для мутации с переменной Upload добавьте файл в разделе Файлы для переменных на вкладке Переменные:

1. Выберите +.
2. Введите переменную, например file, или files.0 для первого элемента списка.
3. Введите путь к файлу относительно рабочего пространства.

Тогда POST следует спецификации multipart-запросов GraphQL: переменная в operations равна null, а файл идёт в отдельной части.