Girdi

Çıktı

GraphQL Formatlayıcı nedir?

Bir kod üreticisinden, federation composer'dan ya da sohbet penceresinden kopyala-yapıştır ile çıkan bir GraphQL şeması, neredeyse hiçbir zaman istediğiniz boşlukları taşımaz. Tipler birbirine yapışır, alanlar aynı satırı paylaşır, açıklamalar bir sonraki tanıma sıkıştırılır. GraphQL şema tanım dili, frontend ve backend arasındaki okunabilir sözleşme olmalı — ama yalnızca gerçekten formatlandıysa. SDL'inizi sol panele yapıştırın, sağ panel size güzelleştirilmiş halini geri versin: iki boşluk girinti, satır başına bir alan, argümanlar satır içinde ve blok dize açıklamalar belgeledikleri tipin veya alanın üstünde tutuluyor.

Pretty-printer elle yazıldı — sayfaya graphql npm paketi yüklenmiyor, dolayısıyla ilk paint hafif kalıyor. SDL'i tokenize ediyor, süslü parantez yapısını dolaşıyor ve Ekim 2021 GraphQL spesifikasyonuna göre tutarlı bir aralıkla tekrar yayıyor. Gerçek şemalarda görünen her SDL yapısı destekleniyor: type, interface, union, enum, input, scalar, extend, schema, directive, list ve non-null değiştiricileri ([Foo!]!), default değerler, directive'ler ve üçlü tırnaklı açıklamalar. Formatlayıcı idempotenttir — zaten düzgün SDL aynısı olarak geri döner, dolayısıyla bir CI gate'i veya pre-commit hook'u içinde gönül rahatlığıyla çalıştırabilirsiniz.

Her şey tarayıcınızda çalışıyor. Yükleme yok, hiçbir yerde saklanan şema yok. Yapıştır, güzelleştir, kopyala.

GraphQL Formatlayıcı nasıl kullanılır

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

Yapıştırın, yükleyin veya örnek yükleyin

Soldaki Girdi paneline bir GraphQL şeması yapıştırın — yazmayı bıraktıktan saniyenin küçük bir bölümü sonra otomatik olarak formatlanır, yani aranacak bir Convert düğmesi yok. .graphql, .graphqls veya .gql dosyası için Yükle'ye tıklayın ya da gerçekçi bir e-ticaret Order şemasını yüklemek için Örnek'e basın. Tipik dağınık bir yapıştırma şuna benzer:

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

Sunucu tarzı şemalar (extend type Query ile) ve bağımsız tip tanımları, ikisi de çalışır. Kabul edilen biçimler, Apollo Server gibi araçların başlangıçta parse ettikleriyle eşleşir.

Güzelleştirilmiş çıktıyı okuyun

Sağdaki Çıktı paneli, iki boşluk girintili güzelleştirilmiş SDL'i çizer. Her alan, enum değeri ve union üyesi kendi satırını alır. Argümanlar, imzalar doğal okunsun diye alan satırında satır içinde kalır. Blok dize olarak yazılmış açıklamalar ("""...""") tarif ettikleri tipin veya alanın üstünde tutulur ki Relay GraphQL spesifikasyonunun şema belgelemek için önerdiği yol budur. SDL'de dengesiz süslü parantezler veya başka bir parse hatası varsa, formatlayıcı satır içi dostça bir mesaj gösterir — asla exception fırlatmaz veya çökmez.

Kopyalayın veya indirin

Formatlanmış şemayı bir pull request, doküman ya da sohbete götürmek için Kopyala'ya basın. .graphql olarak kaydetmek için İndir'e basın. Girdi panelindeki temizle düğmesi sizi boş duruma döndürür. Formatlama tamamen istemci tarafında olur — şemanız sayfayı asla terk etmez.

Bunu gerçekten ne zaman kullanırsınız

PR review okunabilirliği

Bir takım arkadaşı şemanıza beş yeni tip ekleyen bir PR açar. Codegen çıktısı formatlamayı düşürdüğü için diff tek bir dev blok gibi görünür. Dosyayı formatlayıcıdan geçirin, güzelleştirilmiş sürümü PR açıklamasına bırakın ki review yapanlar gerçekten ne eklendiğini okuyabilsin. Review yapanlar yapıyı görebildiğinde GraphQL şema en iyi uygulamalarını takip etmek çok daha kolay.

Şema registry diff'leri

Çoğu şema registry'si (Apollo Studio, GraphQL Hive, Hasura) diff'leri satır satır metin olarak gösterir. Bir revision sıkıştırılmış, bir sonraki güzelleştirilmişse her satır değişmiş gibi görünür ve gerçek değişiklik gürültüde kaybolur. Yüklemeden önce iki sürümü de güzelleştirin — aynı formatlayıcı, aynı çıktı, gerçek diff.

Doküman ve onboarding

Bir GraphQL API için herkese açık doküman mı yazıyorsunuz, yoksa yeni bir mühendisi onboard mı ediyorsunuz? Şemayı yapıştırın, formatlanmış sürümü wiki veya README'ye kopyalayın. Her tipin üstünde açıklamaları görünen bir şema, codegen aracının tükürdüğü formatsız yığından çok daha dostça bir başlangıç noktasıdır.

Pre-commit ve CI gate'leri

Formatlayıcı idempotent olduğundan, onu pre-commit hook'u veya CI check'i olarak çalıştırabilirsiniz: şemayı formatlayın, sonuç commit edilmiş dosyadan farklıysa build'i fail edin. Katkı verenler arasında artık whitespace drift yok ve diff'in yarısı yeniden formatlama gürültüsü olan PR'lar yok.

Sık sorulan sorular

Şemamı doğruluyor mu, yoksa sadece formatlıyor mu?

Sadece formatlıyor. Formatlayıcı, pretty-print için yetecek kadar süslü parantez ve tırnak dengesini kontrol eder, ancak Query'nin var olup olmadığını, referans verilen tiplerin tanımlı olup olmadığını veya directive argümanlarının tanımlarıyla eşleşip eşleşmediğini doğrulamaz. Tam doğrulama için şemanızı referans uygulama graphql-js'ten ya da sunucunuzun başlangıç check'lerinden geçirin.

Şemam bir sunucuya gönderiliyor mu?

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

Blok dize açıklamaları işliyor mu?

Evet. Üçlü tırnaklı açıklamalar ("""Bir müşteri tarafından verilen sipariş.""") korunur ve belgeledikleri tipin veya alanın üstündeki satıra yazılır. Bu, GraphQL spesifikasyonuna göre SDL belgelemenin standart yoludur.

Peki ya directive'ler ve custom scalar'lar?

İkisi de korunur. @deprecated, @key ve her custom directive alan üzerinde satır içinde kalır. scalar DateTime gibi custom scalar'lar kendi satırında yayılır. Formatlayıcı directive semantiğini yorumlamaya çalışmaz — bu sunucunuzun işidir.

Zaten formatlanmış SDL yeniden formatlanır mı?

İdempotenttir — zaten güzelleştirilmiş SDL'i güzelleştirmek aynı çıktıyı üretir. Yani formatlayıcıyı bir CI check'inde ya da yapıştır-ve-karşılaştır akışında whitespace drift'i hakkında endişelenmeden çalıştırabilirsiniz.

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

Tarayıcınızın rahatça çizebildiği kadarını. Birkaç yüz tipli şemalar sorun değil. 5 MB üstünde Ace editor'ın kendisi yavaşlamaya başlar — darboğaz orada, parser değil.

Diğer GraphQL araçları

Formatlama, GraphQL ile çalışmanın bir parçası. Bu araçlar gerisini hallediyor: