01
Используйте старую версию как базу
Оценка идёт от действующей схемы к новой. Если поменять стороны местами, удаление станет добавлением и классификация пересчитается; сначала убедитесь в правильной последовательности.
Документы GraphQL
сравнение схем GraphQLпроверить контракт до выпуска
Слева вставьте полную действующую схему SDL, справа — предлагаемую. Направление определяет риск удаления и добавления.
сравнение схем GraphQL
Старая схема SDL
Новая схема SDL
Различия
Введите две полные схемы SDL или загрузите пример.
Оба текста SDL разбираются в этом браузере. Без API-запросов, загрузки на сервер, сохранения истории и передачи ввода через URL.
Параметры
GraphQL.js определяет критические и потенциально опасные изменения. Остальные структурные различия и отметки устаревания показаны отдельно, без обещания безопасности.
Для каждого SDL: до 100 000 символов, 20 000 токенов и 100 уровней вложенности. Через 8 секунд сравнение останавливается.
Введите две полные схемы SDL или загрузите пример.
Сравнение схем GraphQL помогает при ревью, когда текстовый diff заполнен перестановкой объявлений и пробелами. Клиентам важнее, сохранились ли типы, поля и аргументы, на которые опираются запросы.
В отчёте отдельно показаны структурные различия и правила совместимости. Новые поля или метки @deprecated остаются в списке, даже если GraphQL.js не относит их к критическим: отсутствие срабатывания не доказывает безопасность.
Зачем нужно сравнение схем GraphQL
Смотрите на изменения контракта, а не на перестановку строк.
От текста к точному пути
Сравнение схем GraphQL строит обе схемы из SDL и сопоставляет типы, поля и аргументы по именованным путям. Изменённый порядок объявлений не создаёт ложного отличия, а удалённое поле видно вместе со старым типом.
Разделяйте риск и устаревание
Новое значение enum может нарушить логику клиента с полным перебором вариантов. Метка @deprecated не удаляет поле. Сравнение схем GraphQL показывает эти события отдельно и не называет остальные структурные изменения безопасными.
Проверьте направление и актуальность отчёта
02
Выберите способ запуска
По умолчанию сравнение начинается после паузы около 350 мс. Для большого SDL выключите автоматику и запустите сравнение кнопкой или Ctrl/Cmd+Enter, когда обе версии готовы.
03
Экспортируйте только свежий результат
После любого редактирования прежний отчёт устаревает, копирование и скачивание блокируются. Исправьте ошибку на указанной стороне, по строке и столбцу, затем повторите запуск. Файл содержит все записи, даже если экран показывает их по 100.
Какие изменения попадают в отчёт
Структурные пути GraphQL
Сопоставляются типы, поля, аргументы, входные поля, enum, union и директивы. Пробелы и порядок определений не считаются изменением API.
Правила GraphQL.js
Библиотека назначает категории критического и потенциально опасного изменения. Код правила виден рядом; другие структурные отличия не получают необоснованной отметки «безопасно». Критические изменения отделены от потенциального риска.
Отдельное устаревание и полный экспорт
Новая или изменённая причина @deprecated записывается отдельно. Удаление ранее устаревшего поля всё равно остаётся критическим по стандартным правилам.
Пределы статического сравнения SDL
- Нужны две полные корректные схемы
- Отдельный тип без корня Query или ссылка на неизвестный тип не образуют полноценную схему. Сравнение схем GraphQL остановится и покажет сторону ошибки и доступную позицию, не выдавая ложный отчёт без изменений.
- Использование клиентами неизвестно
- Критическая пометка означает возможность сбоя старых операций. Инструмент не видит трафик и запросы конкретных клиентов, поэтому фактическое влияние проверяйте отдельно. Обратная совместимость зависит и от операций, которых в двух SDL нет.
- Нет URL и JSON-интроспекции
- Принимаются только два текста SDL. Инструмент не обращается к эндпоинту, не выполняет запросы и не загружает файлы. JSON-интроспекцию сначала преобразуйте в полную SDL-схему.
- Переименование не угадывается
- По двум снимкам нельзя доказать миграционное намерение. Старое имя будет удалено, новое добавлено; даже прежняя метка @deprecated не отменяет риск удаления. Устаревшие поля тоже могут использоваться клиентами.
Вопросы про сравнение схем GraphQL
Изменение аргумента мутации на nullable нарушит совместимость?
Если обязательный аргумент мутации сделать nullable, набор допустимых входных значений обычно расширится. GraphQL.js не считает это направление критическим; обратное изменение может сломать старые вызовы без аргумента.
Добавление значения enum в GraphQL считается критическим изменением?
Новое значение enum считается потенциально опасным: старый запрос остаётся допустимым, но клиент с исчерпывающей обработкой значений может не распознать новый вариант.
Можно ли переименовать тип GraphQL без нарушения совместимости?
Две SDL-схемы не содержат намерения переименования. Сравнение схем GraphQL отдельно показывает удаление прежнего типа и добавление нового; плавный переход нужно планировать на уровне API.
Можно ли пометить мутацию GraphQL как устаревшую?
Мутация — поле корневого типа Mutation, поэтому её можно пометить @deprecated. Старые операции остаются допустимыми, а фактическое удаление поля позже всё равно классифицируется как критическое.
Изменение поля с non-null на nullable нарушит совместимость?
Переход выходного поля из non-null в nullable меняет ожидания сгенерированных клиентов, и GraphQL.js помечает его критическим. Для обратного перехода также проверьте, что resolver не возвращает null.
Документ дал неожиданный результат?
Запустите сравнение схем GraphQL перед выпуском
Разместите старый и новый SDL рядом, изучите все категории и скачайте актуальный отчёт.