Docs
⌘ K

7 dakika

GraphQL Validations Migration Guide

Yakında “graph-node”, GraphQL Validasyon Özelliklerinin⁠’in %100’ünü destekleyecektir.

“graph-node”un önceki sürümleri tüm doğrulamaları desteklemiyordu ve daha zarif yanıtlar veriyordu - bu nedenle, belirsizlik durumlarında “graph-node” geçersiz GraphQL işlem bileşenlerini görmezden geliyordu.

GraphQL validasyon desteği, yaklaşan yeni özelliklerin ve Graph Ağı ölçeğindeki performansın temel direğidir.

Ayrıca, Graph ağında önemli bir gereklilik olan sorgu yanıtlarının belirleyiciliğini de sağlayacaktır.

GraphQL validasyonlarını etkinleştirmek, Graph API’ye gönderilen bazı mevcut sorguları bozacaktır.

Bu doğrulamalarla uyumlu olmak için lütfen taşıma kılavuzunu takip edin.

⚠️ Doğrulamalar kullanıma sunulmadan önce sorgularınızı taşımazsanız, bunlar hata döndürecek ve muhtemelen ön uçlarınızı/istemcilerinizi bozacaktır.

Taşıma Kılavuzu

GraphQL işlemlerinizdeki sorunları bulmak ve düzeltmek için CLI taşıma aracını kullanabilirsiniz. Alternatif olarak, https://api-next.thegraph.com/subgraphs/name/$GITHUB_USER/$SUBGRAPH_NAME uç noktasını kullanmak için GraphQL istemcinizin uç noktasını güncelleyebilirsiniz. Sorgularınızı bu uç noktaya göre test etmek, sorgularınızdaki sorunları bulmanıza yardımcı olacaktır.

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.

Geçiş CLI Aracı

GraphQL işlem hatalarının çoğu kod tabanınızda önceden bulunabilir.

Bu nedenle, geliştirme sırasında veya CI’de GraphQL işlemlerinizi doğrulamak için sorunsuz bir deneyim sağlıyoruz.

@graphql-validate/cli⁠, GraphQL işlemlerini belirli bir şemaya göre doğrulamaya yardımcı olan basit bir CLI aracıdır.

Başlarken

Aracı aşağıdaki gibi çalıştırabilirsiniz:

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

Notlar:

  • $GITHUB_USER, $SUBGRAPH_NAME değerini uygun değerlerle ayarlayın veya değiştirin. artblocks/art-blocks⁠ gibi.
  • Sağlanan önizleme şeması URL’si (https://api-next.thegraph.com/⁠) büyük oranda hız sınırlamasına sahiptir ve tüm kullanıcılar yeni sürüme geçtikten sonra kullanımdan kaldırılacaktır. Çıktıda kullanmayın.
  • İşlemler, aşağıdaki .graphql,⁠.ts, .tsx, .js, jsx⁠ (-o option) uzantılarına sahip dosyalarda tanımlanır.

CLI Çıktısı

[@graphql-validate/cli](https://github.com/saihaj/graphql-validate) CLI aracı, tüm GraphQL işlemleri hatalarını aşağıdaki gibi verir:

Error output from CLI

Her hata için bir açıklama, dosya yolu ve konumu ve bir çözüm örneğine bağlantı bulacaksınız (aşağıdaki bölüme göz atın).

Yerel sorgularınızı önizleme şemasına göre çalıştırın

Doğrulamaların açık olduğu bir “Graph Node” sürümünü çalıştıran bir uç nokta https://api-next.thegraph.com/ sağlıyoruz.

Sorguları şu adrese göndererek deneyebilirsiniz:

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

yada

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

Doğrulama hataları içerdiği işaretlenen sorgular üzerinde çalışmak için Altair veya GraphiQL⁠ gibi en sevdiğiniz GraphQL sorgulama aracını kullanabilir ve sorgunuzu deneyebilirsiniz. Bu araçlar, siz çalıştırmadan önce bile kullanıcı arayüzlerinde bu hataları işaretleyecektir.

Sorunları nasıl çözeceğiz?

Aşağıda, mevcut GraphQL işlemlerinizde meydana gelebilecek tüm GraphQL doğrulama hatalarını bulacaksınız.

GraphQL değişkenleri, işlemleri, parçaları veya bağımsız değişkenleri benzersiz olmalıdır

Bir işlemin benzersiz bir GraphQL değişkenleri, işlemler, parçalar ve bağımsız değişkenler kümesi içermesini sağlamak için kurallar uyguladık.

Bir GraphQL işlemi, yalnızca herhangi bir belirsizlik içermiyorsa geçerlidir.

Bunu başarmak için, GraphQL işleminizdeki bazı bileşenlerin benzersiz olmasını sağlamamız gerekiyor.

Aşağıda, bu kuralları ihlal eden birkaç geçersiz işleme örnek verilmiştir:

Yinelenen Sorgu Adı (#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}

Solution:

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

Duplicate Fragment name (#UniqueFragmentNamesRule)

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

Solution:

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

Duplicate variable name (#UniqueVariableNamesRule)

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

Solution:

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  }}

Solution:

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

Duplicate anonymous query (#LoneAnonymousOperationRule)

Ayrıca, iki anonim işlemin kullanılması, yanıt yapısındaki çakışma nedeniyle LoneAnonymousOperation kuralını ihlal edecektir:

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

Solution:

query {  someField  otherField}

Veya iki sorguyu adlandırın:

query FirstQuery {  someField}query SecondQuery {  otherField}

Çakışan Alanlar

Bir GraphQL seçim seti, yalnızca nihai sonuç setini doğru bir şekilde çözerse geçerli kabul edilir.

Belirli bir seçim kümesi veya bir alan, seçilen alan veya kullanılan bağımsız değişkenler nedeniyle belirsizlik yaratırsa, GraphQL hizmeti işlemi doğrulamada başarısız olur.

Bu kuralı ihlal eden geçersiz işlemlere birkaç örnek:

Conflicting fields aliases (#OverlappingFieldsCanBeMergedRule)

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

Solution:

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

Conflicting fields with arguments (#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)  }}

Solution:

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

Ayrıca, daha karmaşık kullanım durumlarında, sonunda beklenen kümede bir çakışmaya neden olabilecek iki parça kullanarak bu kuralı ihlal edebilirsiniz:

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}

Buna ek olarak, “@skip” ve “@include” gibi müşteri tarafı GraphQL yönergeleri belirsizliğe yol açabilir, örneğin:

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

Algoritma hakkında daha fazla bilgiyi buradan edinebilirsiniz.⁠

Kullanılmayan Değişkenler veya Parçalar

Bir GraphQL işlemi, yalnızca tüm işlem tanımlı bileşenler (değişkenler, parçalar) kullanılıyorsa geçerli kabul edilir.

İşte bu kuralları ihlal eden GraphQL işlemleri için birkaç örnek:

Kullanılmayan Değişken (#NoUnusedVariablesRule)

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

Solution:

query something {  someData}

Unused Fragment (#NoUnusedFragmentsRule)

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

Solution:

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

Geçersiz veya Eksik Seçim Kümesi (#ScalarLeafsRule)

Ayrıca, bir GraphQL alan seçimi yalnızca aşağıdakiler doğrulanırsa geçerlidir:

  • Bir nesne alanında olması gereken seçim kümesi belirtildi.
  • Bir kenar alanı (scalar, enum) belirtilen bir seçim kümesine sahip olmamalıdır.

Aşağıda, aşağıdaki şema ile bu kuralların ihlaline ilişkin birkaç örnek verilmiştir:

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

Invalid Selection-Set

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

Solution:

query {  user {    id  }}

Missing Selection-Set

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

Solution:

query {  user {    id    image {      src    }  }}

Yanlış Bağımsız Değişken Değerleri (#VariablesInAllowedPositionRule)

Sabit kodlu değerleri bağımsız değişkenlere ileten GraphQL işlemleri, şemada tanımlanan değere göre geçerli olmalıdır.

Aşağıda, bu kuralları ihlal eden geçersiz işlemlere ilişkin birkaç örnek verilmiştir:

query purposes {  # If "name" is defined as "String" in the schema,  # this query will fail during validation.  purpose(name: 1) {    id  }}# Bu, yanlış bir değişken tanımlandığında da olabilir: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  }}

Bilinmeyen Tür, Değişken, Parça veya Yönerge (#UnknownX)

Herhangi bir bilinmeyen tür, değişken, parça veya yönerge kullanılırsa GraphQL API bir hata verir.

Bu bilinmeyen referanslar düzeltilmelidir:

  • bir yazım hatasıysa yeniden adlandır
  • aksi halde kaldır

Parça: Geçersiz Yayılma Veya Tanım

Geçersiz Parça Yayılması (#PossibleFragmentSpreadsRule)

Bir parça, geçerli olmayan bir türe yayılamaz.

Örnek olarak, “Dog” türüne bir “Cat” parçası uygulayamayız:

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

Geçersiz Fragment Tanımı (#FragmentsOnCompositeTypesRule)

Tüm parçalar (‘on …’ kullanılarak) bir bileşik tipte tanımlanmalıdır, kısacası: nesne, arayüz veya birleşim.

Aşağıdaki örnekler geçersizdir, çünkü skalerler üzerinde parça tanımlama geçersizdir.

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  }}

Direktif kullanımı

Yönerge bu konumda kullanılamaz (#KnownDirectivesRule)

Yalnızca Graph API tarafından desteklenen GraphQL yönergeleri (”@…”) kullanılabilir.

İşte GraphQL tarafından desteklenen direktiflere bir örnek:

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

Not: @stream, @live, @defer desteklenmez.

Yönerge bu konumda yalnızca bir kez kullanılabilir (#UniqueDirectivesPerLocationRule)

Graph tarafından desteklenen direktifler, lokasyon başına sadece bir kez kullanılabilir.

Aşağıdakiler geçersiz (ve gereksiz):

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