Giriş

Çıktı

GraphQL Görüntüleyici nedir?

Daha önce tek satıra sıkışmış halde dönen bir GraphQL SDL parçasını yapıştırıp okumaya çalıştıysan, sorunu biliyorsundur. Tipler, alanlar, argümanlar, direktifler ve union üyeleri hep birbirine yapışır ve yapı kaybolur. Bu araç onu düzeltir. Şemanı sol panele yapıştır; sağ panel iki boşluk girintilemeyle, satır başına bir alanla, argümanlar satır içinde ve block-string açıklamaları belgelendirdiği tipin veya alanın üstünde tutarak render eder.

Düzgün biçimlendirici el yapımı — sayfaya hiçbir graphql npm paketi yüklenmiyor, böylece ilk paint küçük kalıyor. SDL’i tokenize eder, süslü parantez yapısını dolaşır ve Ekim 2021 GraphQL spesifikasyonuna uygun tutarlı boşluklarla yeniden yazar. Gerçek dünyada gördüğün her SDL yapısını idare eder: type, interface, union, enum, input, scalar, extend, schema, liste ve non-null değiştiricileri ([Foo!]!), varsayılan değerler, direktifler ve üçlü tırnaklı açıklamalar. Zaten düzgün olan girdi, aynısı olarak geri döner.

Her şey tarayıcında çalışır. Yükleme yok, hiçbir yerde saklanan şema yok. Yapıştır, oku, kopyala.

GraphQL Görüntüleyici nasıl kullanılır

Üç hızlı adım. Aşağıda tarif edilen düğmeler bu sayfadaki gerçek düğmelerdir.

Yapıştır, yükle veya bir örnek aç

Sol Giriş paneline bir GraphQL şeması yapıştır. .graphql, .graphqls veya .gql dosyası için Yükle’ye tıkla, ya da gerçekçi bir e-ticaret şeması açmak için Örnek’e bas. Sıkıştırılmış SDL’in nasıl göründüğüne dair hızlı bir örnek:

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]! total:Money! status:OrderStatus!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

Hem sunucu tarzı şemalar (extend type Query içerenler) hem de bağımsız tip tanımları çalışır. Kabul edilen biçimler, Apollo Server gibi araçların parse ettikleriyle eşleşir.

Biçimlendirilmiş çıktıyı oku

Sağ Çıktı paneli, parse edilmiş SDL’i iki boşluk girintilemeyle render eder. Her alan, enum değeri ve union üyesi kendi satırını alır. Argümanlar alan satırında satır içi kalır, böylece imzalar doğal okunur. Block-string olarak yazılmış açıklamalar ("""..."""), Relay GraphQL spesifikasyonunun bir şemanın belgelenmesi için önerdiği biçimde, açıkladıkları tipin veya alanın üstünde tutulur. SDL’de dengesiz süslü parantezler veya başka parse hataları varsa, görüntüleyici çökmek yerine dostça bir mesaj gösterir.

Kopyala veya indir

Bir pull request, doküman veya sohbet için biçimlendirilmiş şemayı yanına almak için Kopyala’ya bas. .graphql olarak kaydetmek için İndir’e bas. Giriş panelindeki temizleme düğmesi seni boş duruma döndürür. Parse tamamen istemci tarafında olur — şeman sayfayı asla terk etmez.

Bunu gerçekten ne zaman kullanırsın

Şema pull request review’ları

Bir şema PR’ını review ediyorsun ve dosya biçimlendirmesini sıyıran bir code generator’dan geçtiği için diff zor okunuyor mu? Yeni sürümü buraya yapıştır, yapıyı gözle tara, sonra neyin değiştiğine dair daha net bir zihin haritasıyla diff’e dön. Özellikle ekip iyi şema tasarımı sayılan şey üzerinde iterasyon yaparken çok faydalı.

Federation ve subgraph hata ayıklama

Bir Apollo federation gateway’i debug ediyorsun ve oluşturulan supergraph şeması dev bir blok olarak mı dönüyor? Birleştirilmiş SDL’i yapıştır, yanlış davranan tipi bul, hangi alanın hangi subgraph’tan geldiğini gör. Çıktıda görünen federation direktifleri, şema sözdiziminin geri kalanıyla birlikte gösterilir.

Bir API’yi belgelemek

Ekibinin sahibi olduğu bir GraphQL API için herkese açık dokümantasyon mu yazıyorsun? Şemayı görüntüleyiciye bırak, biçimlendirilmiş sürümü wiki’ye veya README’ye kopyala. Tipler, arabirimler ve union’lardan oluşan ağaç biçimi, satır başına bir alanla yerleştirildikten sonra doğal okunur.

Yeni mühendislerin onboarding’i

Yeni bir takım arkadaşı GraphQL API’nin biçimini öğrenmeye çalışıyor. Her tipin üstünde açıklamaların görünür olduğu biçimlendirilmiş bir şema, codegen çıktısındaki biçimsiz bloktan çok daha dostça bir başlangıç noktasıdır.

Sık sorulanlar

Şemamı doğruluyor mu, yoksa sadece biçimlendiriyor mu?

Sadece biçimlendiriyor. Görüntüleyici, biçimlendirebilmek için süslü parantez ve tırnak dengesini yeterince kontrol eder ama Query’nin var olup olmadığını, referans verilen tiplerin tanımlı olup olmadığını veya direktif argümanlarının tanımlarıyla eşleşip eşleşmediğini doğrulamaz. Tam doğrulama için referans graphql-js uygulamasını kullan ya da sunucunun başlangıç kontrollerinden geçir.

Şemam bir sunucuya gönderiliyor mu?

Hayır. Düzgün biçimlendirici tamamen tarayıcında çalışır. Hiçbir şey yüklenmez, hiçbir şey loglanmaz. Dahili veya yayınlanmamış şemaları yapıştırmak güvenli.

Block-string açıklamalarını işliyor mu?

Evet. Üçlü tırnaklı açıklamalar ("""Bir müşterinin verdiği sipariş.""") korunur ve belgeledikleri tipin veya alanın üstündeki satırda yayınlanır. Bu, GraphQL spesifikasyonuna göre SDL belgelendirmesinin standart yoludur.

Direktifler ve özel scalar’lar ne olacak?

İkisi de korunur. @deprecated, @key ve her özel direktif, alanın üzerinde satır içi kalır. scalar DateTime gibi özel scalar’lar kendi satırlarında yayınlanır. Görüntüleyici, direktif anlamlarını yorumlamaya çalışmaz — bu, sunucunun işidir.

Zaten biçimlendirilmiş SDL yeniden biçimlendirilir mi?

Idempotenttir — zaten düzgün bir SDL’i biçimlendirmek aynı çıktıyı üretir. Yani görüntüleyiciyi bir CI kontrolünde veya yapıştır-ve-karşılaştır iş akışında, boşluk farklılığı endişesi olmadan çalıştırabilirsin.

Ne kadar büyük bir şema yapıştırabilirim?

Tarayıcının rahatça render edebildiği her şey. Birkaç yüz tipli şemalar sorun değil. 5 MB’ı geçince Ace editor’ün kendisi yavaşlamaya başlar — darboğaz orası, parse eden değil.

Diğer GraphQL araçları

Görüntülemek GraphQL ile çalışmanın bir parçası. Bu araçlar gerisini halleder: