Ошибку в GraphQL-схеме лучше найти до того, как её увидит сервер или генератор кода клиента. Редактор GraphQL «Помощника SA» проверяет схему по мере ввода — по тем же правилам, что эталонная реализация graphql-js, — и пишет понятные сообщения на русском. А ИИ-ревью проверяет то, что синтаксис не ловит: именование, обязательность полей, устройство мутаций и пагинации.
Как проверить схему
- Откройте песочницу GraphQL и вставьте схему или откройте файл: Файл → Открыть файл….
- Ошибки сразу отмечаются в строках кода, а под редактором появляется список: номер строки и сообщение, например «Неизвестный тип «Custmer». Возможно, имелось в виду «Customer»?».
- Пока в схеме есть ошибки, карта показывает последнюю корректную версию — с пометкой «В коде есть ошибки».
- Исправьте ошибки — карта обновится, список исчезнет.

Что проверяется
- Синтаксис SDL: скобки, двоеточия, кавычки описаний, ключевые слова.
- Ссылки на типы: неизвестный тип — с подсказкой похожего имени.
- Повторы: тип, поле, аргумент или значение перечисления объявлены дважды.
- Интерфейсы: тип, реализующий интерфейс, должен повторить все его поля с совместимыми типами.
- Входные и выходные типы:
inputнельзя вернуть из поля, а объектный тип нельзя передать аргументом. - Объединения и директивы: в объединение входят только объектные типы; директива должна быть объявлена и стоять на разрешённом месте.
- Корень: без типа
Queryсхема без запросов — редактор предупредит.
ИИ-ревью по лучшим практикам
Кнопка ИИ-ревью (тарифы «Макс» и выше) проверяет схему по рекомендациям GraphQL: именование типов, полей и значений перечислений, обязательность полей и списков, мутации с входными Input- и Payload-типами, курсорную пагинацию, эволюцию схемы через @deprecated. Замечания можно принять — исправления внесутся в схему, а при сохранении версия получит пометку ИИ. Сами рекомендации — в разделе документации «Рекомендации по проектированию».
Проверка в API и MCP
Той же проверкой пользуются ИИ-агенты: через внешний API и MCP схему можно проверить до сохранения и получить список ошибок с номерами строк. Подключение — «Как подключить ИИ-агента по MCP».
Что ещё
- Основы редактора — «Редактор GraphQL-схемы онлайн».
- Типы, обязательность и списки — раздел «Схема и типы».
Вопросы и ответы
Почему редактор принимает схему, а сервер — нет? Сервер может требовать свои директивы или скаляры, объявленные в коде, а не в SDL (например, директивы федерации). Объявите их в схеме — directive @key(fields: String!) on OBJECT, — и проверка пройдёт.
Что значит предупреждение об операциях? В схеме оказались запросы (query { … }): они не ломают схему, но в неё не входят и на карте не показываются.
Проверяются ли запросы клиентов по схеме? Нет, редактор проверяет саму схему. Как сервер проверяет запросы, описано в разделе «Проверка запросов».
