Introspection JSON

GraphQL SDL

Introspection JSON to SDL Dönüştürücü Nedir?

Apollo Studio, Postman, Insomnia üzerinden bir şema çektiğinizde ya da canlı bir endpoint'e karşı get-graphql-schema çalıştırdığınızda elinize geçen, sizin yazdığınız o sevimli SDL değildir — query { __schema { ... } }'in sonucudur: her tipi, her alanı ve her modifier'ı kind / name / ofType nesnelerinden oluşan bir ağaçta tarif eden, 600+ satırlık iç içe geçmiş JSON. Bir araca yararlı, bir insana ise okunmaz. Bu dönüştürücü o JSON'u alıp, gerçekten bir repoya commit'leyeceğiniz SDL olarak yeniden basar; bunu yaparken Ekim 2021 GraphQL spec'inin introspection kurallarını izler.

Her şey tarayıcınızda olur — yükleme yok, yapay zeka yok, hiçbir şema hiçbir yere gönderilmez. Dönüşüm mantığı, graphql-js'in buildClientSchema ve printSchema ile içeride yaptığını birebir yansıtır: __schema ağacında dolaşır, sadece introspection'a özgü tipleri (__Schema, __Type, __Field, …) ve yerleşik scalar'ları atlar, kalan her tanımı açıklamaları, alanları, argümanları, varsayılan değerleri ve deprecation gerekçeleriyle birlikte aynen yazar. İster tüm { "data": { "__schema": ... } } zarfını, ister sadece { "__schema": ... }'yi, isterseniz çıplak __schema değerini yapıştırın — sayfa üç biçimi de işler.

Çıktı önce scalar'lar, sonra enum, interface, union, input tipleri ve son olarak object tipleri şeklinde gruplanır — her grup içinde alfabetik, iki boşluk girintili ve tanımlar arasında bir boş satır. Reponuzdaki bir <code>.graphql</code> dosyasına doğrudan koyabilecek kadar idempotent.

Dönüştürücüyü Nasıl Kullanırsınız

Üç adım. Aşağıdaki düğmeler bu sayfadaki gerçek düğmeler.

Yapıştırın, Yükleyin veya Bir Örnek Açın

Introspection JSON'unuzu soldaki Giriş paneline yapıştırın — yazmayı bıraktığınız andan saniyenin küçük bir kesri sonra dönüşüm otomatik gerçekleşir, yani aranacak bir Convert düğmesi yok. Apollo Studio veya Postman'den dışa aktardığınız bir .json dosyası için Yükle'ye basın, gerçekçi bir Order/Customer/Money introspection sonucunu yüklemek için Örnek'e dokunun. Tipik bir yapıştırma şöyle başlar:

{
  "data": {
    "__schema": {
      "queryType": { "name": "Query" },
      "types": [
        { "kind": "OBJECT", "name": "Order", "fields": [...] },
        ...
      ]
    }
  }
}

İçerideki { "__schema": ... } değerini ya da çıplak __schema nesnesini de yapıştırabilirsiniz — sayfa üç biçimi de dener. get-graphql-schema ve Apollo Server'ın introspection endpoint'i gibi araçlar varsayılan olarak bu biçimlerden birini üretir.

SDL Çıktısını Okuyun

Sağdaki Çıktı paneli şemayı SDL olarak render eder. Her tip iki boşluk girintiyle kendi tanımında olur, alanlar bir satıra bir, açıklamalar tipin ya da alanın üzerinde üç tırnaklı blok string olarak korunur, deprecation gerekçeleri aynı satırda @deprecated(reason: "...") olarak render edilir. Yerleşik scalar'lar ve __ introspection tipleri filtrelenir — elinize geçen tam olarak sunucunuzun yayımladığı şema, üstelik Relay'in GraphQL spec'inin belgelenmesini önerdiği biçimde. JSON bozuksa veya __schema alanı eksikse, stack trace yerine satır içi dostça bir mesaj alırsınız.

Kopyalayın veya İndirin

Bir PR açıklamasına, dokümana veya sohbete SDL'yi taşımak için Kopyala'ya basın. schema.graphql olarak kaydetmek için İndir'e basın — doğrudan reponuza bırakın. Giriş panelindeki temizle düğmesi sizi boş duruma döndürür. Dönüşüm tamamen istemci tarafında; introspection sonucu sayfayı asla terk etmez.

Bunu Gerçekten Ne Zaman Kullanırsınız

Canlı Bir Endpoint'ten Şema Yakalayın

Repoda hiç şema dosyası olmayan, sadece çalışan sunucusu olan bir GraphQL servisini devraldınız. Bir introspection sorgusu çalıştırın, JSON'u buraya yapıştırın ve beş dakika içinde commit'lenmiş bir başlangıç schema.graphql'iniz olur. Bunu sadece bir kez yapmak için graphql-js'ten buildClientSchema ve printSchema'yı bağlamaktan çok daha kolay.

Apollo Studio veya Postman İhracını Okuyun

Apollo Studio'nun şema ihracı introspection JSON'dur. Postman'in GraphQL isteğindeki "Save schema" düğmesi de aynı. Burada dönüştürün ve şemayı JSON'a gözlerinizi kısarak bakmak yerine bir kod editöründe gerçekten gözden geçirebilin.

Canlı Bir Şemanın İki Anlık Görüntüsünü Diff'leyin

Staging ve production'a karşı introspection çalıştırın, her birini SDL'ye dönüştürün ve iki dosyayı diff'leyin. Eksik bir alanı veya yeniden adlandırılmış bir enum değerini fark etmek SDL'de çocuk oyuncağı, ham introspection JSON'unda ise neredeyse imkânsız.

Sahibi Olmadığınız Bir Servisten Tip Stub'ları Üretin

Üçüncü taraf bir GraphQL API için TypeScript tipleri veya React hook'ları lazım mı? Çoğu kod üreteci SDL ister, introspection JSON değil. Burada dönüştürün, sonra SDL'yi codegen pipeline'ınıza besleyin — graphql-react, graphql-codegen veya stack'inizin kullandığı her ne ise.

Sık Sorulan Sorular

Tam { "data": { "__schema": ... } } zarfı şart mı?

Hayır. Sayfa üç biçimi kabul eder: tam GraphQL yanıt zarfı, sadece { "__schema": ... } ya da çıplak __schema nesnesi. Hangisini yapıştırırsanız yapıştırın, __schema kökünü bulur ve oradan çalışır.

JSON'umda __schema alanı yoksa ne olur?

Dostça bir mesaj alırsınız: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Çökme yok, stack trace yok.

Açıklamalar ve deprecation gerekçeleri korunuyor mu?

Evet. Tip ve alan açıklamaları tanımın üzerinde üç tırnaklı blok string olarak basılır. Deprecate edilmiş alanlar ve enum değerleri aynı satırda @deprecated(reason: "...") alır. Bu, graphql-js'in printSchema çıktısıyla eşleşir.

Yerleşik scalar'lar ve __ introspection tipleri ne olur?

Filtrelenir. String, Int, Float, Boolean ve ID SDL'de örtülüdür — yalnızca alan tiplerinde görünürler, üst düzey tanım olarak değil. __Schema, __Type, __Field ve diğer introspection meta-tipleri için de aynısı geçerlidir.

Çıktı orijinal introspection sonucuna birebir geri dönmeyi garanti eder mi?

Anlamsal olarak evet — SDL aynı şemayı tarif eder. Bayt bayt hayır, çünkü tiplerin ve alanların sırası orijinal kaynak dosyanızdan farklı olabilir. Çıktı, kararlı diff'ler için her tanım grubu içinde alfabetik sıralanır.

Introspection sonucum bir sunucuya gönderiliyor mu?

Hayır. Dönüşüm tamamen tarayıcınızda çalışır. Hiçbir şey yüklenmez, hiçbir şey loglanmaz. Dahili veya henüz yayımlanmamış servislerin şemalarını yapıştırmak güvenlidir.

Diğer GraphQL Araçları

SDL elinize geçtiğinde, geri kalanını şunlar halleder:

Introspection JSON'dan GraphQL SDL'ye