← Все гайды

Проверка GraphQL-схемы: ошибки SDL и ИИ-ревью по лучшим практикам

· 2 мин чтения

GraphQL

Какие ошибки GraphQL-схемы редактор находит по мере ввода — неизвестные типы, повторы, реализация интерфейсов, входные и выходные типы — и что проверяет ИИ-ревью.

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

Как проверить схему

  1. Откройте песочницу GraphQL и вставьте схему или откройте файл: Файл → Открыть файл….
  2. Ошибки сразу отмечаются в строках кода, а под редактором появляется список: номер строки и сообщение, например «Неизвестный тип «Custmer». Возможно, имелось в виду «Customer»?».
  3. Пока в схеме есть ошибки, карта показывает последнюю корректную версию — с пометкой «В коде есть ошибки».
  4. Исправьте ошибки — карта обновится, список исчезнет.
Ошибки в GraphQL-схеме: неизвестный тип и повторное поле отмечены в коде и перечислены под редактором
Ошибки отмечены в строках и перечислены под редактором; карта показывает последнюю корректную версию

Что проверяется

  • Синтаксис SDL: скобки, двоеточия, кавычки описаний, ключевые слова.
  • Ссылки на типы: неизвестный тип — с подсказкой похожего имени.
  • Повторы: тип, поле, аргумент или значение перечисления объявлены дважды.
  • Интерфейсы: тип, реализующий интерфейс, должен повторить все его поля с совместимыми типами.
  • Входные и выходные типы: input нельзя вернуть из поля, а объектный тип нельзя передать аргументом.
  • Объединения и директивы: в объединение входят только объектные типы; директива должна быть объявлена и стоять на разрешённом месте.
  • Корень: без типа Query схема без запросов — редактор предупредит.

ИИ-ревью по лучшим практикам

Кнопка ИИ-ревью (тарифы «Макс» и выше) проверяет схему по рекомендациям GraphQL: именование типов, полей и значений перечислений, обязательность полей и списков, мутации с входными Input- и Payload-типами, курсорную пагинацию, эволюцию схемы через @deprecated. Замечания можно принять — исправления внесутся в схему, а при сохранении версия получит пометку ИИ. Сами рекомендации — в разделе документации «Рекомендации по проектированию».

Проверка в API и MCP

Той же проверкой пользуются ИИ-агенты: через внешний API и MCP схему можно проверить до сохранения и получить список ошибок с номерами строк. Подключение — «Как подключить ИИ-агента по MCP».

Что ещё

Вопросы и ответы

Почему редактор принимает схему, а сервер — нет? Сервер может требовать свои директивы или скаляры, объявленные в коде, а не в SDL (например, директивы федерации). Объявите их в схеме — directive @key(fields: String!) on OBJECT, — и проверка пройдёт.

Что значит предупреждение об операциях? В схеме оказались запросы (query { … }): они не ломают схему, но в неё не входят и на карте не показываются.

Проверяются ли запросы клиентов по схеме? Нет, редактор проверяет саму схему. Как сервер проверяет запросы, описано в разделе «Проверка запросов».