Docs
⌘ K

7 minutes

GraphQL Validations Migration Guide

Brzy bude graph-node podporovat 100% pokrytí GraphQL Validations specifikace⁠.

Předchozí verze graph-node nepodporovaly všechny validace a neposkytovaly šetrnější odpovědi - v případě nejednoznačnosti tak graph-node ignoroval neplatné komponenty operací GraphQL.

Podpora ověřování GraphQL je pilířem pro nadcházející nové funkce a výkon v měřítku Síť Graph.

Zajistí také determinismus odpovědí na dotazy, což je klíčový požadavek sítě Graf.

Povolení ověřování GraphQL naruší některé existující dotazy odeslané do Grafu API.

Chcete-li být v souladu s těmito validacemi, postupujte podle průvodce migrací.

⚠️ Pokud neprovedete migraci dotazů před zavedením validací, budou vracet chyby a možná rozbijí vaše frontends/klienty.

Průvodce migrací

Pomocí migračního nástroje CLI můžete najít případné problémy v operacích GraphQL a opravit je. Případně můžete aktualizovat koncový bod svého klienta GraphQL tak, aby používal koncový bod https://api-next.thegraph.com/subgraphs/name/$GITHUB_USER/$SUBGRAPH_NAME. Testování dotazů proti tomuto koncovému bodu vám pomůže najít problémy ve vašich dotazech.

Not all Subgraphs will need to be migrated, if you are using GraphQL ESlint⁠ or GraphQL Code Generator⁠, they already ensure that your queries are valid.

Migrační nástroj CLI

Většinu chyb při operacích GraphQL můžete najít ve své kódové základně předem.

Z tohoto důvodu poskytujeme hladký průběh ověřování operací GraphQL během vývoje nebo v CI.

@graphql-validate/cli⁠ je jednoduchý nástroj CLI, který pomáhá ověřovat operace GraphQL proti danému schéma.

začínáme

Nástroj můžete spustit následujícím způsobem:

npx @graphql-validate/cli -s https://api-next.thegraph.com/subgraphs/name/$GITHUB_USER/$SUBGRAPH_NAME -o *.graphql

Poznámky:

Výstup CLI

Nástroj [@graphql-validate/cli](https://github.com/saihaj/graphql-validate) CLI vypíše všechny chyby operací GraphQL takto:

Error output from CLI

U každé chyby naleznete popis, cestu a pozici souboru a odkaz na příklad řešení (viz následující část).

Spouštění místních dotazů proti schéma náhledu

Poskytujeme koncový bod https://api-next.thegraph.com/, který spouští verzi graph-node se zapnutými validacemi.

Dotazy si můžete vyzkoušet zasláním na:

  • https://api-next.thegraph.com/subgraphs/id/<Qm...>

nebo

  • https://api-next.thegraph.com/subgraphs/name/<GITHUB_USER>/<SUBGRAPH_NAME>

Chcete-li pracovat s dotazy, které byly označeny jako dotazy s chybami validace, můžete použít svůj oblíbený nástroj pro dotazy GraphQL, například Altair nebo GraphiQL⁠, a vyzkoušet svůj dotaz. Tyto nástroje také tyto chyby označí ve svém uživatelském rozhraní, a to ještě předtím, než jej spustíte.

Jak řešit problémy

Níže naleznete všechny chyby validace GraphQL, které se mohou vyskytnout u vašich stávajících operací GraphQL.

Proměnné, operace, fragmenty nebo argumenty jazyka GraphQL musí být jedinečné

Použili jsme pravidla pro zajištění toho, aby operace obsahovala jedinečnou sadu proměnných GraphQL, operací, fragmentů a argumentů.

Operace GraphQL je platná pouze tehdy, pokud neobsahuje žádnou nejednoznačnost.

Abychom toho dosáhli, musíme zajistit, aby některé součásti operace GraphQL byly jedinečné.

Zde je příklad několika neplatných operací, které porušují tato pravidla:

Duplicitní název dotazu (#UniqueOperationNamesRule)

# The following operation violated the UniqueOperationName# rule, since we have a single operation with 2 queries# with the same namequery myData {  id}query myData {  name}

Řešení:

query myData {  id}query myData2 {  # rename the second query  name}

Duplicitní název fragmentu (#UniqueFragmentNamesRule)

# The following operation violated the UniqueFragmentName# rule.query myData {  id  ...MyFields}fragment MyFields {  metadata}fragment MyFields {  name}

Řešení:

query myData {  id  ...MyFieldsName  ...MyFieldsMetadata}fragment MyFieldsMetadata { # assign a unique name to fragment  metadata}fragment MyFieldsName { # assign a unique name to fragment  name}

Duplicitní název proměnné (#UniqueVariableNamesRule)

# The following operation violates the UniqueVariablesquery myData($id: String, $id: Int) {  id  ...MyFields}

Řešení:

query myData($id: String) {  # keep the relevant variable (here: `$id: String`)  id  ...MyFields}

Duplicate argument name (#UniqueArgument)

# The following operation violated the UniqueArgumentsquery myData($id: ID!) {  userById(id: $id, id: "1") {    id  }}

Řešení:

query myData($id: ID!) {  userById(id: $id) {    id  }}

Duplicitní anonymní dotaz (#LoneAnonymousOperationRule)

Použitím dvou anonymních operací se také poruší pravidlo LoneAnonymousOperation kvůli konfliktu ve struktuře odpovědi:

# This will fail if executed together in# a single operation with the following two queries:query {  someField}query {  otherField}

Řešení:

query {  someField  otherField}

Nebo tyto dva dotazy pojmenujte:

query FirstQuery {  someField}query SecondQuery {  otherField}

Překrývající pole

Výběrová sada GraphQL je považována za platnou, pouze pokud správně řeší případnou sadu výsledků.

Pokud konkrétní výběrová sada nebo pole způsobí nejednoznačnost buď vybraného pole, nebo použitých argumentů, služba GraphQL operaci neověří.

Zde je několik příkladů neplatných operací, které toto pravidlo porušují:

Překrývající se aliasy polí (#OverlappingFieldsCanBeMergedRule)

# Aliasing fields might cause conflicts, either with# other aliases or other fields that exist on the# GraphQL schema.query {  dogs {    name: nickname    name  }}

Řešení:

query {  dogs {    name: nickname    originalName: name # alias the original `name` field  }}

Konfliktní pole s argumenty (#OverlappingFieldsCanBeMergedRule)

# Different arguments might lead to different data,# so we can't assume the fields will be the same.query {  dogs {    doesKnowCommand(dogCommand: SIT)    doesKnowCommand(dogCommand: HEEL)  }}

Řešení:

query {  dogs {    knowsHowToSit: doesKnowCommand(dogCommand: SIT)    knowsHowToHeel: doesKnowCommand(dogCommand: HEEL)  }}

Ve složitějších případech použití můžete toto pravidlo porušit také použitím dvou fragmentů, které by mohly způsobit konflikt v očekávané sadě:

query {  # Eventually, we have two "x" definitions, pointing  # to different fields!  ...A  ...B}fragment A on Type {  x: a}fragment B on Type {  x: b}

Kromě toho mohou vést k nejasnostem například direktivy GraphQL na straně klienta jako @skip a @include:

fragment mergeSameFieldsWithSameDirectives on Dog {  name @include(if: true)  name @include(if: false)}

Více informací o algoritmu najdete zde.⁠

Nepoužívané proměnné nebo fragmenty

Operace GraphQL je také považována za platnou, pouze pokud jsou použity všechny součásti definované operací (proměnné, fragmenty).

Zde je několik příkladů operací GraphQL, které tato pravidla porušují:

Nepoužitá proměnná (#NoUnusedVariablesRule)

# Invalid, because $someVar is never used.query something($someVar: String) {  someData}

Řešení:

query something {  someData}

Nepoužitý fragment(#NoUnusedFragmentsRule)

# Invalid, because fragment AllFields is never used.query something {  someData}fragment AllFields { # unused :(  name  age}

Řešení:

# Invalid, because fragment AllFields is never used.query something {  someData}# remove the `AllFields` fragment

Neplatná nebo chybějící výběrová sada (#ScalarLeafsRule)

Výběr pole GraphQL je také platný pouze v případě, že je potvrzeno následující:

  • Pole objektu musí mít zadanou výběrovou sadu.
  • Okrajové pole (skalár, enum) nesmí mít zadanou výběrovou sadu.

Zde je několik příkladů porušení těchto pravidel s následujícím schématem:

type Image {  url: String!}type User {  id: ID!  avatar: Image!}type Query {  user: User!}

Neplatná výběrová sada

query {  user {    id { # Invalid, because "id" is of type ID and does not have sub-fields    }  }}

Řešení:

query {  user {    id  }}

Chybějící výběrová sada

query {  user {    id    image # `image` requires a Selection-Set for sub-fields!  }}

Řešení:

query {  user {    id    image {      src    }  }}

Nesprávné hodnoty argumentů (#VariablesInAllowedPositionRule)

Operace GraphQL, které předávají pevně zadané hodnoty argumentů, musí být platné na základě hodnoty definované ve schéma.

Zde je několik příkladů neplatných operací, které porušují tato pravidla:

query purposes {  # If "name" is defined as "String" in the schema,  # this query will fail during validation.  purpose(name: 1) {    id  }}# This might also happen when an incorrect variable is defined:query purposes($name: Int!) {  # If "name" is defined as `String` in the schema,  # this query will fail during validation, because the  # variable used is of type `Int`  purpose(name: $name) {    id  }}

Neznámý typ, proměnná, fragment nebo směrnice (#UnknownX)

Pokud je použit neznámý typ, proměnná, fragment nebo direktiva, rozhraní GraphQL API vyhodí chybu.

Tyto neznámé odkazy je třeba opravit:

  • přejmenovat, pokud se jedná o překlep
  • v opačném případě odstraňte

Fragment: neplatné rozšíření nebo definice

Neplatné rozložení fragmentů (#PossibleFragmentSpreadsRule)

Fragment nelze rozložit na nepoužitelný typ.

Příklad: fragment Kočka nemůžeme použít na typ Pes:

query {	dog {		...CatSimple  }}fragment CatSimple on Cat {  # ...}

Neplatná definice fragmentu (#FragmentsOnCompositeTypesRule)

Všechny fragmenty musí být definovány na (pomocí on ...) složeném typu, zkráceně: objektu, rozhraní nebo svazu.

Následující příklady jsou neplatné, protože definování fragmentů na skalárech je neplatné.

fragment fragOnScalar on Int {  # we cannot define a fragment upon a scalar (`Int`)  something}fragment inlineFragOnScalar on Dog {  ... on Boolean {    # `Boolean` is not a subtype of `Dog`    somethingElse  }}

Použití směrnic

Direktiv nelze na tomto místě použít (#KnownDirectivesRule)

Lze použít pouze direktivy GraphQL (@...) podporované Graf API.

Zde je příklad s direktivami podporovanými GraphQL:

query {  dog {    name @include(true)    age @skip(true)  }}

Poznámka: @stream, @live, @defer nejsou podporovány.

Direktiv lze v tomto umístění použít pouze jednou (#UniqueDirectivesPerLocationRule)

Směrnice podporované nástrojem Grafu lze v jednom umístění použít pouze jednou.

Následující text je neplatný (a nadbytečný):

query {  dog {    name @include(true) @include(true)  }}