Руководство по переходу на валидацию GraphQL
Reading time: 7 minutes
Вскоре graph-node
будет поддерживать 100-процентное покрытие [спецификации GraphQL Validation] (https://spec.graphql.org/June2018/#sec-Validation).
Предыдущие версии graph-node
не поддерживали все валидации и предоставляли более обтекаемые ответы, поэтому в случаях неоднозначности graph-node
игнорировал недопустимые компоненты операций GraphQL.
Поддержка валидации GraphQL является основой для будущих новых функций и производительности в масштабе The Graph Network.
Это также обеспечит детерминизм ответов на запросы, что является ключевым требованием в сети The Graph.
Включение валидации GraphQL нарушит работу некоторых существующих запросов, отправленных в API The Graph.
Чтобы выполнить эти валидации, следуйте руководству по миграции.
⚠️ Если Вы не перенесете свои запросы до развертывания валидаций, они будут возвращать ошибки и, возможно, повредят ваши интерфейсы/клиенты.
Руководство по миграции
Вы можете использовать инструмент миграции CLI, чтобы найти любые проблемы в операциях GraphQL и исправить их. В качестве альтернативы вы можете обновить конечную точку своего клиента GraphQL, чтобы использовать конечную точку https://api-next.thegraph.com/subgraphs/name/$GITHUB_USER/$SUBGRAPH_NAME
. Проверка запросов на этой конечной точке поможет Вам обнаружить проблемы в Ваших запросах.
Не все субграфы нужно будет переносить, если Вы используете GraphQL ESlint или GraphQL Code Generator, они уже гарантируют корректность Ваших запросов.
CLI-инструмент миграции
Большинство ошибок операций GraphQL можно обнаружить в Вашей кодовой базе заранее.
По этой причине мы обеспечиваем беспрепятственный процесс валидации Ваших операций GraphQL во время разработки или в CI.
@graphql-validate/cli
— это простой инструмент командной строки, который помогает проверять операции GraphQL по заданной схеме.
Начало работы
Вы можете запустить инструмент следующим образом:
npx @graphql-validate/cli -s https://api-next.thegraph.com/subgraphs/name/$GITHUB_USER/$SUBGRAPH_NAME -o *.graphql
Примечания:
- Установите или замените $GITHUB_USER, $SUBGRAPH_NAME соответствующими значениями. Например:
artblocks/art-blocks
- Предоставленный URL-адрес схемы предварительного просмотра (https://api-next.thegraph.com/) сильно ограничен по скорости и будет удален после того, как все пользователи перейдут на новую версию. Не используйте его в рабочей среде.
- Операции идентифицируются в файлах со следующими расширениями [
.graphql
,] (https://www.graphql-tools.com/docs/schema-loading#graphql-file-loader).ts
,.tsx
,.js
,jsx
(-o
option).
Вывод CLI
Инструмент CLI [@graphql-validate/cli](https://github.com/saihaj/graphql-validate)
будет выводить любые ошибки операций GraphQL следующим образом:

Для каждой ошибки Вы найдете описание, путь к файлу и его положение, а также ссылку на пример решения (см. следующий раздел).
Выполняйте локальные запросы по схеме предварительного просмотра
Мы предоставляем конечную точку https://api-next.thegraph.com/
, которая запускает версию graph-node
с включенной валидацией.
Вы можете опробовать запросы, отправив их по адресу:
https://api-next.thegraph.com/subgraphs/id/<Qm...>
или
https://api-next.thegraph.com/subgraphs/name/<GITHUB_USER>/<SUBGRAPH_NAME>
Чтобы работать с запросами, которые были помечены как имеющие ошибки валидации, Вы можете использовать свой любимый инструмент запросов GraphQL, например Altair или GraphiQL и попробовать свой запрос. Эти инструменты также будут отмечать ошибки в своем пользовательском интерфейсе еще до того, как Вы их запустите.
Как решить проблемы
Ниже Вы найдете все ошибки валидации GraphQL, которые могут возникнуть в Ваших операциях GraphQL.
Переменные, операции, фрагменты или аргументы GraphQL должны быть уникальными
Мы применили правила, гарантирующие, что операция включает уникальный набор переменных, операций, фрагментов и аргументов GraphQL.
Операция GraphQL действительна только в том случае, если она не содержит какой-либо неоднозначности.
Для этого нам нужно убедиться, что некоторые компоненты в Вашей операции GraphQL уникальны.
Ниже приведен пример нескольких недопустимых операций, нарушающих эти правила:
Повторяющееся имя запроса (#UniqueOperationNamesRule)
# Следующая операция нарушила UniqueOperationName# правило, так как у нас одна операция с 2-мя запросами# с тем же именемquery myData { id}query myData { name}
Решение:
query myData { id}query myData2 { # rename the second query name}
Повторяющееся имя фрагмента (#UniqueFragmentNamesRule)
# Следующая операция нарушила UniqueFragmentName# правило.query myData { id ...MyFields}fragment MyFields { metadata}fragment MyFields { name}
Решение:
query myData { id ...MyFieldsName ...MyFieldsMetadata}fragment MyFieldsMetadata { # присвоить фрагменту уникальное имя metadata}fragment MyFieldsName { # присвоить фрагменту уникальное имя name}
Повторяющееся имя переменной (#UniqueVariableNamesRule)
# Следующая операция нарушает UniqueVariablesquery myData($id: String, $id: Int) { id ...MyFields}
Решение:
query myData($id: String) { # сохранить соответствующую переменную (здесь: `$id: String`) id ...MyFields}
Повторяющееся имя аргумента (#UniqueArgument)
# Следующая операция нарушила UniqueArgumentsquery myData($id: ID!) { userById(id: $id, id: "1") { id }}
Решение:
query myData($id: ID!) { userById(id: $id) { id }}
Повторяющийся анонимный запрос (#LoneAnonymousOperationRule)
Кроме того, использование двух анонимных операций нарушит правило LoneAnonymousOperation из-за конфликта в структуре ответа:
# Это приведет к ошибке, если выполнить их вместе в# одной операции со следующими двумя запросами:query { someField}query { otherField}
Решение:
query { someField otherField}
Или назовите эти два запроса:
query FirstQuery { someField}query SecondQuery { otherField}
Перекрывающиеся поля
Набор выбора GraphQL считается допустимым, только если он правильно разрешает конечный набор результатов.
Если конкретный набор элементов или поле создают неоднозначность либо из-за выбранного поля, либо из-за используемых аргументов, служба GraphQL не сможет валидировать операцию.
Вот несколько примеров недопустимых операций, нарушающих это правило:
Псевдонимы конфликтующих полей (#OverlappingFieldsCanBeMergedRule)
# Псевдонимы полей могут вызвать конфликты либо с# другими псевдонимами или другими полями, существующими в# схеме GraphQL.query { dogs { name: nickname name }}
Решение:
query { dogs { name: nickname originalName: name # alias the original `name` field }}
Конфликтующие поля с аргументами (#OverlappingFieldsCanBeMergedRule)
# Разные аргументы могут привести к разным данным,# поэтому мы не можем предположить, что поля будут одинаковыми.query { dogs { doesKnowCommand(dogCommand: SIT) doesKnowCommand(dogCommand: HEEL) }}
Решение:
query { dogs { knowsHowToSit: doesKnowCommand(dogCommand: SIT) knowsHowToHeel: doesKnowCommand(dogCommand: HEEL) }}
Кроме того, в более сложных случаях использования Вы можете нарушить это правило, используя два фрагмента, которые могут вызвать конфликт в ожидаемом в конечном итоге наборе:
query { # В конце концов, у нас есть два определения "x", указывающие # на разные поля! ...A ...B}fragment A on Type { x: a}fragment B on Type { x: b}
Кроме того, директивы GraphQL на стороне клиента, такие как @skip
и @include
, могут привести к неоднозначности, например:
fragment mergeSameFieldsWithSameDirectives on Dog { name @include(if: true) name @include(if: false)}
Подробнее об алгоритме можно прочитать здесь.
Неиспользуемые переменные или фрагменты
Операция GraphQL также считается действительной, только если используются все определенные в операции компоненты (переменные, фрагменты).
Вот несколько примеров операций GraphQL, которые нарушают эти правила:
Неиспользуемая переменная (#NoUnusedVariablesRule)
# Неверно, потому что $someVar никогда не используется.query something($someVar: String) { someData}
Решение:
query something { someData}
Неиспользуемый фрагмент (#NoUnusedFragmentsRule)
# Неверно, так как фрагмент AllFields никогда не используется.query something { someData}fragment AllFields { # unused :( name age}
Решение:
# Неверно, так как фрагмент AllFields никогда не используется.query something { someData}# удалить фрагмент `AllFields`
Недопустимый или отсутствующий набор элементов выбора (#ScalarLeafsRule)
Кроме того, выбор поля GraphQL действителен только в том случае, если подтверждено следующее:
- Поле объекта должно иметь заданный набор выбора.
- Краевое поле (скалярное, перечислимое) не должно иметь заданного набора выбора.
Вот несколько примеров нарушения этих правил со следующей схемой:
type Image { url: String!}type User { id: ID! avatar: Image!}type Query { user: User!}
Недопустимый набор выбора
query { user { id { # Неверно, так как "id" имеет тип ID и не имеет подполей } }}
Решение:
query { user { id }}
Отсутствует набор выбора
query { user { id image # `image` требует набора выбора для подполей! }}
Решение:
query { user { id image { src } }}
Неверные значения аргументов (#VariablesInAllowedPositionRule)
Операции GraphQL, которые передают жестко запрограммированные значения в аргументы, должны быть допустимыми на основе значения, определенного в схеме.
Вот несколько примеров недопустимых операций, нарушающих эти правила:
query purposes { # Если в схеме "name" определено как "String", # этот запрос не пройдёт валидацию. purpose(name: 1) { id }}# Это также может произойти, если определена неверная переменная:query purposes($name: Int!) { # Если "name" определено в схеме как `String`, # этот запрос не пройдёт валидацию, потому что # используемая переменная имеет тип `Int` purpose(name: $name) { id }}
Неизвестный тип, переменная, фрагмент или директива (#UnknownX)
API GraphQL вызовет ошибку, если используется какой-либо неизвестный тип, переменная, фрагмент или директива.
Эти неизвестные ссылки необходимо исправить:
- переименуйте, если это опечатка
- в противном случае удалите
Фрагмент: недопустимый спред или определение
Неверный разворот фрагмента (#PossibleFragmentSpreadsRule)
Фрагмент не может быть распространен на неприменимый тип.
Например, мы не можем применить фрагмент Cat
к типу Dog
:
query { dog { ...CatSimple }}fragment CatSimple on Cat { # ...}
Недопустимое определение фрагмента (#FragmentsOnCompositeTypesRule)
Все фрагменты должны быть определены (используя on ...
) для составного типа, короче говоря: для объекта, интерфейса или объединения.
Следующие примеры недопустимы, так как определение фрагментов на скалярах недопустимо.
fragment fragOnScalar on Int { # мы не можем определить фрагмент на скаляре (`Int`) something}fragment inlineFragOnScalar on Dog { ... on Boolean { # `Boolean` не является подтипом `Dog` somethingElse }}
Применение директив
Директива не может быть использована в данном месте (#KnownDirectivesRule)
Можно использовать только директивы GraphQL (”@…”), поддерживаемые The Graph API.
Вот пример с директивами, поддерживаемыми GraphQL:
query { dog { name @include(true) age @skip(true) }}
Примечание: @stream
, @live
, @defer
не поддерживаются.
Директива может быть использована в этом месте только один раз (#UniqueDirectivesPerLocationRule)
Директивы, поддерживаемые The Graph, можно использовать только один раз в каждом месте.
Следующее является недопустимым (и избыточным):
query { dog { name @include(true) @include(true) }}