Giriş

Çıkış

GraphQL Küçültücü Nedir?

Bir GraphQL şemasını dağıtım çıktısının, bir Lambda paketinin ya da CDN üzerinden servis edilen bir SDL dizisinin parçası olarak gönderdiğinizde, açıklamalar ve `#` yorumları hızla birikir. Gerçek bir üretim şeması bayt sayısının kolayca %40-60’ı oranında dokümantasyon olabilir — bunu insanlar okuduğunda işe yarar, bir istemciyi ayağa kaldırmak için telden geçerken ölü ağırlıktır. GraphQL belirtimi yorumları, blok dizgi açıklamalarını ve çoğu boşluğu yok sayılan token olarak tanımlar; yani makul bir ayrıştırıcı bunları zaten yok sayar. Bu küçültücü hepsini söker ve ayrıştırıcı açısından orijinaliyle bayt bayt eşdeğer tek satırlık bir SDL döndürür.

Küçültücü elle yazılmıştır — sayfaya hiçbir graphql npm paketi yüklenmez, böylece ilk boyama hafif kalır. SDL’yi tokenlere ayırır, her yorum ve blok dizgi tokenını atar ve yapısal tokenları tekrar yayarken bitişik name tokenlarını ayırt etmek için gereken kesin minimum boşluğu bırakır (belirtime uygun bir SDL’nin gerçekten boşluğa ihtiyaç duyduğu tek yer burasıdır). Çıktı, biçimlendiricide kullanılan aynı hafif ayrıştırıcı ile doğrulanır, böylece açılışta graphql-js ya da Apollo Server üzerinden gidiş-dönüş, orijinaliyle aynı şekilde davranır.

Her şey tarayıcınızda çalışır. Yükleme yok, hiçbir yerde saklanan şema yok. Yapıştırın, küçültün, kopyalayın.

GraphQL Küçültücü Nasıl Kullanılır

Üç hızlı adım. Aşağıda anlatılan düğmeler bu sayfadaki gerçek düğmelerdir — küçültme otomatik çalıştığı için Küçült düğmesi yoktur.

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

Soldaki Giriş paneline bir GraphQL şeması yapıştırın — yazmayı bıraktığınızdan saniyenin küçük bir kısmı sonra küçültme otomatik gerçekleşir, yani aranacak bir Dönüştür düğmesi yoktur. .graphql, .graphqls veya .gql dosyası için Yükle’ye tıklayın ya da Örnek’e basıp yorumlar ve blok dizgi açıklamaları içeren gerçekçi bir e-ticaret Sipariş şemasını yükleyin ve bunların çıkarılışını izleyin. Tipik bir giriş şöyle görünür:

"""An order placed by a customer."""
type Order {
  # The unique order identifier
  id: ID!
  placedAt: DateTime!
  customer: Customer!
  items: [OrderItem!]!
  status: OrderStatus!
}

Hem sunucu tarzı şemalar (extend type Query ile) hem de bağımsız tip tanımları çalışır. Kabul edilen biçimler GraphQL şema tanım dilinin desteklediği biçimlerle örtüşür.

Küçültülmüş Çıktıyı Okuyun

Sağdaki Çıkış paneli, küçültülmüş SDL’yi tek satırda gösterir; ne kadar kazandığınızı bir bakışta görebilmeniz için panel başlığında kazanılan bayt rozeti yer alır. Yorumlar (# ...) ve blok dizgi açıklamaları ("""...""") tamamen çıkarılır — Relay GraphQL belirtimine göre anlamsal değerleri sıfırdır ve introspeksiyon tabanlı her araç açıklamaları zaten resolver katmanınızdan toplar. SDL’nin dengesiz süslü parantezleri varsa ya da başka bir ayrıştırma hatası bulunursa, küçültücü sıcak bir satır içi mesaj gösterir — asla istisna fırlatmaz veya çökmez.

Kopyalayın veya İndirin

Küçültülmüş şemayı bir dağıtım betiğine, bir Lambda env değişkenine ya da bir yapılandırma dosyasına satır içine almak için Kopyala’ya basın. .graphql olarak kaydetmek için İndir’e basın. Giriş panelindeki temizle düğmesi sizi boş duruma döndürür. Küçültme tamamen istemci tarafında gerçekleşir — şemanız sayfayı asla terk etmez.

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

Daha Küçük Dağıtım Çıktıları

Şemanızı bir sunucusuz fonksiyona ya da bir Docker katmanına paketliyor musunuz? Açıklamaları ve yorumları çıkarmak bayt sayısını genelde yarıya iner. Bunu her soğuk başlatma ve her katman indirmesiyle çarpın, kazanç faturanıza yansımaya başlar. Çalışma anındaki ayrıştırıcı umursamaz — açıklamalar yalnızca introspeksiyon meta verisidir ve çoğu üretim dağıtımı zaten Apollo Router üretim rehberine uyup introspeksiyonu kapatır.

CDN Üzerinden Sunulan Şemalar

Geçidiniz açılışta SDL’yi bir CDN’den çekiyorsa (Federation supergraph oluşturma, şema kayıt çekme), her bayt soğuk yolda gecikme demektir. Küçültülmüş SDL aynı şekilde ayrıştırılır ve tel boyutundan iyi bir parça keser — çoğu zaman gzip’in yapacağından da fazla, çünkü gzip zaten kaldırılmış olanı sıkıştıramaz.

Şemaları Kaynağa Gömme

Bazen bir yapılandırma dosyasına, bir env değişkenine ya da elle yazılmış bir araca şema dizisini gömmeniz gerekir. Tek satırlık küçültülmüş bir sürüm, her yeni satırı kaçırmadan TypeScript şablon değişmezine veya YAML skalerine temiz şekilde oturur.

Diff Gürültüsünü Azaltma

Bir şemanın iki revizyonu yalnızca açıklamalarda veya yorumlarda farklılaştığında, gerçek yapısal diff dokümantasyon değişikliklerinin altına gömülür. Diff almadan önce her iki tarafı küçültmek gerçek şema farkını izole eder ki bu değişiklik yönetimi ve kırıcı değişiklik tespiti için yararlıdır.

Sık Sorulan Sorular

Küçültülmüş şema hâlâ geçerli GraphQL mi?

Evet — belirtimin yok sayılabilir kabul ettiği her token (yorumlar, açıklamalar, gereksiz boşluk, virgül) çıkarılır, ama her ad, noktalama, dizgi sabiti ve sayı korunur. Çıktı, girdi ile tıpatıp aynı AST’ye ayrıştırılır. Her ikisini de graphql-js üzerinden geçirip ortaya çıkan belgeleri karşılaştırarak doğrulayabilirsiniz.

Şema dokümantasyonumu kaybeder miyim?

Evet — bütün mesele bu. Açıklamalar ve `#` yorumları çıkarılır. Küçültülmemiş kaynağınızı sürüm denetiminde tutun ve yalnızca çıktıyı yayınlamak üzereyken küçültün. İstemcilere gerçekten göstermek istediğiniz dokümantasyon, dağıtılan SDL dizisinden değil, çalışma anındaki resolver meta verilerinden üretilen introspeksiyon yanıtınızda yaşar.

Şemam bir sunucuya gönderiliyor mu?

Hayır. Küçültme tamamen tarayıcınızda çalışır. Hiçbir şey yüklenmez, hiçbir şey günlüklenmez. Dahili veya yayımlanmamış şemaları yapıştırmak güvenlidir.

Ne kadar tasarruf edebilirim?

Şemanızın ne kadar belgelendiğine bağlı. Açıklaması olmayan sade bir SDL %10-15 tasarruf eder (yalnız boşluklar). Her tip ve alanda blok dizgi açıklamaları olan iyi belgelenmiş bir şema genellikle %40-60 tasarruf eder. Çıkış paneli başlığındaki kazanılan bayt rozeti, girdiniz için kesin sayıyı söyler.

Direktifleri, özel skalerleri ve federation’ı işliyor mu?

Evet. @deprecated, @key, @external, scalar DateTime ve her özel direktif veya skaler korunur. Küçültücü yalnızca yok sayılabilir tokenları çıkarır — anlamsal olan her şey kalır. Federation direktifleri gidiş-dönüşü temiz şekilde tamamlar.

Ne büyüklükte şema küçültebilirim?

Tarayıcınızın rahatça gösterebildiği her şeyi. Birkaç yüz tipi olan şemalar sorun değil. Yaklaşık 5 MB’ı aşınca Ace düzenleyicinin kendisi yavaşlamaya başlar — darboğaz odur, küçültücü değil.

Diğer GraphQL Araçları

Küçültme, GraphQL ile çalışmanın bir parçası. Geri kalanını şu araçlar halleder: