GraphQL Validasyon Geçiş Kılavuzu

Reading time: 7 min

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.

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.

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.

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.

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

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).

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.

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

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 name
query 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 UniqueVariables
query 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 UniqueArguments
query 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
}

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.

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

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

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

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

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

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