Как проверить GraphQL Formatter, если он не форматирует непустой запрос

Что проверить перед форматированием GraphQL

GraphQL Formatter предназначен для работы с текстом GraphQL-запроса или схемы. Однако в проверенной конфигурации результат зависит от того, пуст ли ввод: пустая или состоящая только из пробелов строка обрабатывается успешно, а непустой запрос не возвращается в отформатированном виде. Поэтому этот материал полезен прежде всего для диагностики поведения инструмента и проверки формы входных данных, а не для подтверждения корректности GraphQL.

Перед отправкой учитывайте три границы. Ввод должен быть строкой после выбора основного поля или одного из поддерживаемых альтернативных имён. Размер непустого значения в UTF-8 не должен превышать 1 000 000 байт. Кроме того, успешная обработка пустого ввода не означает, что непустой запрос будет отформатирован: для него предусмотрены отдельные этапы обработки, на которых результат не возвращается.

Пошаговая проверка входа и ответа

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

2. Передайте значение в основное поле ввода. Если оно пустое, можно также использовать одно из поддерживаемых альтернативных имён: graphql или gql_input. Альтернативное значение учитывается, когда основное значение является ложным. После выбора значение должно быть строкой; неподходящий тип приводит к ошибке вместо форматирования.

3. Выберите режим. Для непустого текста значение по умолчанию - beautify; оно приводится к нижнему регистру. Только значение minify выбирает путь минификации, а другие значения направляют обработку по пути обычного форматирования. Для пустого ввода это преобразование не выполняется, поэтому возвращённый режим сохраняет переданное значение.

4. При необходимости задайте отступ. Для непустого текста используется значение по умолчанию 2 пробела на уровень. Перед обработкой введённое значение преобразуется в целое число, если это возможно. Значения меньше 0, больше 8 или значения, которые нельзя преобразовать, заменяются на 2. Пустой ввод обходит эту нормализацию и сохраняет переданное значение отступа.

5. Отправьте данные и разберите ответ по его содержимому. Для пустого или пробельного ввода ожидается пустой отформатированный текст; размеры входа и выхода равны 0. Для непустого текста не следует ожидать успешного результата в проверенной конфигурации: обычные пути beautify и minify завершаются до выдачи форматированного текста. Если размер UTF-8 превышен или после выбора поля передан нестроковый ввод, обработка также завершается ошибкой.

Как понимать результат и его ограничения

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

Если запрос содержит хотя бы один непробельный символ, успешный текстовый результат не является ожидаемым исходом. Ошибка в этой ситуации не подтверждает и не опровергает правильность GraphQL: инструмент не должен рассматриваться как средство синтаксической проверки, выполнения или доказательства корректности запроса. Отдельно проверьте размер UTF-8 и тип значения после выбора основного поля или альтернативного имени.

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

Практический пример

Разработчик проверяет, как инструмент отвечает на ввод, в котором нет текста GraphQL.

Передайте в GraphQL Formatter строку из пробелов и задайте режим MINIFY и отступ 12.

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

Ограничения

• Проверенная конфигурация не возвращает отформатированный текст для обычного непустого запроса или схемы. Инструмент также не следует считать средством проверки синтаксиса, выполнения GraphQL или подтверждения корректности текста.

Частые ошибки

• Ошибка возникает, когда после выбора основного поля или альтернативного имени передано нестроковое значение. Передайте текст строкой; если основное значение пусто, проверьте, что значение в graphql или gql_input тоже является строкой.

Частые вопросы

Почему GraphQL Formatter не форматирует непустой запрос?

Пустая или состоящая только из пробелов строка обрабатывается успешно и даёт пустой форматированный текст. Непустой ввод в проверенной конфигурации завершается до возврата отформатированного результата.

Какой режим форматирования выбрать?

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

Можно ли передать GraphQL-текст через альтернативное поле?

Можно использовать основное поле, а при пустом основном значении также graphql или gql_input. После выбора значение должно быть строкой, иначе форматирование не выполняется.