Girdi

Çıktı

GraphQL Sorgu Biçimlendirici Nedir?

Birinin elle yazdığı her GraphQL isteği, tek satıra sıkıştırılmış küme parantezlerinden oluşan bir duvar olarak başlar. Biçimlendirmeden code review'a yapıştırmak, ilk yorum olarak "lütfen yeniden biçimlendir" almanın en garanti yoludur. Bir frontend build'inden çıkan, bir sunucunun loglarına düşen ya da bir takım arkadaşı "bu neden null dönüyor?" diye sorduğunda Slack thread'ine düşen sorgular için de durum aynı. Bu sayfa bir sorgu, mutasyon, abonelik veya fragment alır ve güzelleştirir: iki boşluk girinti, satır başına bir alan, sığarsa inline argümanlar, düzenlenmiş değişkenler ve GraphQL spec'inin operasyon dilbilgisi baştan sona uygulanır.

Bu sayfanın GraphQL Formatter'ın operasyon tarafındaki tamamlayıcısı olduğunu unutma. O araç şema tanım dilini biçimlendirir — type Order, interface Node, enum Status gibi. Bu araç ise client'ının gönderdiğini ve sunucunun aldığını biçimlendirir: query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutasyonlar, abonelikler ve fragment tanımları. İki dilbilgisi token'ları paylaşır ama yapısal kuralları farklıdır — selection set'ler, alias'lar, fragment spread'ler, inline fragment'lar ve direktif uygulamaları yalnızca operasyonlara özgüdür. Yanlışlıkla SDL yapıştırdıysan, şema biçimlendiriciye git.

Biçimlendirme TypeScript'te elle yazıldı — sayfaya hiçbir graphql-js bundle'ı yüklenmiyor, dolayısıyla ilk paint küçük kalıyor. Çıktı, yaygın durumlarda Prettier'ın GraphQL eklentisinin ürettiğiyle eşleşir, bu yüzden biçimlendirilmiş sorguyu zaten Prettier kullanan bir kod tabanına yapıştırmak diff oluşturmamalı. Her şey yerel çalışır — sorgun tarayıcıyı asla terk etmez.

GraphQL Sorgu Biçimlendirici Nasıl Kullanılır

Üç adım. Convert butonu yok — yazmayı bıraktıktan kısa bir an sonra biçimlendirme otomatik tetiklenir.

Yapıştır, Yükle veya Örnek Aç

Soldaki Girdi paneline bir GraphQL operasyonu yapıştır. .graphql ya da .gql dosyası için Yükle'ye, gerçekçi bir e-ticaret OrderDetails sorgusu artı küçük bir fragment için Örnek'e tıkla. Tipik dağınık bir yapıştırma şuna benzer:

query OrderDetails($id:ID!,$includeItems:Boolean=true){order(id:$id){id placedAt status customer{id name email}items @include(if:$includeItems){sku quantity unitPrice{amountCents currency}}total{amountCents currency}}}

Biçimlendirici, gerçek client kodunda görülen tüm operasyon yapılarını ele alır: varsayılan değerli değişken tanımları, liste türünde varsayılanlar, @include / @skip / özel direktifler, alias'lar, fragment spread'ler (...Money) ve inline fragment'lar (... on PaidOrder { ... }). Tek bir dokümandaki birden fazla operasyon ya da fragment, aralarında bir boş satır olacak şekilde ayrı tutulur — Apollo Client'ın ve çoğu GraphQL aracının dokümanları beklediği düzen budur.

Güzelleştirilmiş Çıktıyı Oku

Sağdaki Çıktı paneli biçimlendirilmiş operasyonu gösterir. Her alan kendi satırını alır. Argümanlar alan 80 karaktere sığdığında inline kalır, sığmadığında ayrı satırlara bölünür — Prettier'daki GraphQL eklentisinin kullandığı kuralın aynısı. Değişken tanımları, operasyon başlığında aynı kuralı izler. Alias'lar iki noktadan sonra tek bir boşluk korur (aliasedAs: fieldName). Yorumlar (# ...) bağlı oldukları satırın girintisinde korunur. Girdi bozuksa — eşleşmeyen küme parantezleri, başıboş bir $, eksik bir : — biçimlendirici hata fırlatmak yerine satır içinde dostça bir hata yazar.

Kopyala veya İndir

Biçimlendirilmiş sorguyu bir PR, doc ya da sohbet mesajı için almak üzere Kopyala'ya bas. query.graphql olarak kaydetmek için İndir'e bas. Clear girdiyi sıfırlar. Tüm boru hattı client-side — bir sorguyu dahili bir API'ye karşı debug ederken üçüncü taraf bir araca yapıştırmak istemiyorsan işine yarar.

Bunu Gerçekten Ne Zaman Kullanırsın

Code Review ve PR Hijyeni

Frontend bir PR yeni bir mutasyon ekliyor. Sorgu string'i, whitespace'i sıyıran bir build adımından çıktı ve diff şimdi 400 karakterlik bir duvar. Mutasyonu biçimlendiriciden geçir, güzelleştirilmiş sürümü PR açıklamasına bırak; reviewer hangi alanları okuduğunu gerçekten görsün. Aynı numara graphql-react, urql, Relay ve sorguların template literal olarak inline yazıldığı her client için işe yarar.

Prodüksiyondaki Bir Sorguyu Debug Etmek

Prodüksiyondaki bir sorgu, beklediğin bir alan için null döndürüyor. Network sekmesinden request body'yi alıp buraya yapıştırırsın ve değişken değerlerini, hangi alanların @include kullandığını ve fragment spread'lerin nereye düştüğünü hemen görürsün. Uzun bir satıra gözünü kısarak bakmaktan iyidir. Request'i curl veya Postman ile elle yeniden üretmen gerektiğinde GraphQL'i HTTP üzerinden sunmaya dair resmi kılavuzla birleştir.

Öğrenme ve Onboarding

GraphQL operasyonlarına yeni misin? Bir tutorial'da bulduğun bir sorguyu yapıştır, biçimlendir, yapı kendiliğinden netleşir — operasyon başlığı, selection set, iç içe selection set'ler, en altta fragment tanımları. Çıktı, graphql.org sorgu kılavuzunda göreceğin düzeni yansıtır, yani öğrenirken docs'a geri eşleştirmek kolay.

Pre-commit ve CI Kapıları

Biçimlendirici deterministik olduğundan — zaten güzelleştirilmiş sorgular değişmeden geri döner — bu sayfayı commit öncesi "sorgum hâlihazırda düzenli mi?" kontrolü olarak kullanabilirsin. Tam otomatik bir pipeline için aynı kaynağı GraphQL eklentisiyle birlikte Prettier'dan geçir ve sıfır olmayan bir diff'te build'i düşür. Aynı fikir, sadece ölçekli.

Sık Sorulan Sorular

Bunun GraphQL Formatter sayfasından farkı nedir?

GraphQL Formatter sayfası şema tanım dilini biçimlendirir — type, interface, enum, union, scalar ve directive bildirimlerini. Bu sayfa operasyonları biçimlendirir: query, mutation, subscription ve fragment. İki dilbilgisi token'ları paylaşır ama yapısal kuralları çok farklıdır, bu yüzden bir operasyonu şema sayfasında biçimlendirmeye çalışmak (ya da tersi) karışık çıktı verir. Yapıştırdığın şeye uygun aracı seç.

Sorgumu bir şemaya karşı doğruluyor mu?

Hayır. Biçimlendirici, pretty-print için yetecek kadar küme, parantez ve köşeli parantez dengesini kontrol eder ama şemanı bilmez, bu yüzden order'ın id: Int! değil id: ID! aldığını söyleyemez. Gerçek doğrulama için operasyonunu sunucunun startup kontrollerinden ya da yukarıdaki GitHub linkindeki referans graphql-js doğrulayıcıdan geçir.

Sorgum bir sunucuya gönderiliyor mu?

Hayır. Biçimlendirme tamamen client-side JavaScript'tir — hiçbir şey yüklenmez, hiçbir şey loglanmaz. Dahili sorgular, hassas değişken değerleri içeren sorgular veya özel API'lere yapılan sorgular için güvenlidir.

Değişken değerlerime veya argümanlarıma dokunur mu?

Hayır. Argüman değerleri, varsayılan değerler ve liste türü varsayılanlar, yalnızca :, = ve , çevresinde tutarlı boşluklarla, yazıldığı şekilde aynen çıkarılır. Biçimlendirici alan, argüman ya da değişken icat etmez, atmaz ya da yeniden sıralamaz — yapıştırdığın şey çıkar, sadece düzgün dizilmiş halde.

Inline fragment'ları ve fragment spread'leri yönetir mi?

Evet. Inline fragment'lar (... on PaidOrder { ... }) iki boşluk girinti ile standart selection set muamelesi görür. Fragment spread'ler (...Money) alan girintisinde tek bir satırda durur, varsa direktifler aynı satırda tutulur. Tek bir dokümandaki birden fazla fragment tanımı, aralarında bir boş satırla ayrı üst düzey tanımlar olarak korunur.

Peki ya anonim sorgular — <code>{ field }</code> — onları <code>query { field }</code>'a açıyor mu?

Hayır. Kısayol formu spec'in bir parçasıdır ve biçimlendirici onu olduğu gibi korur. İsimli bir sorgu istiyorsan kendin isim ver — biçimlendirici operasyonları sessizce yeniden yazmaz.

Diğer GraphQL Araçları

Sorgu biçimlendirici, GraphQL ile çalışmanın bir dilimi. Sitedeki diğer GraphQL araçları: