GraphQL Sorgu Biçimlendirme

Nasıl çalışır?

Tarayıcının ağ sekmesinden, bir hata kaydından ya da JavaScript kodunun içinden kopyaladığınız GraphQL sorgusu çoğu zaman tek satırdır ve hangi alanın hangisinin içinde olduğu görünmez. Sorguyu sol panele yapıştırın; sağ panelde her alan kendi satırına iner, iç içe seçimler 2 boşlukla girintilenir ve argümanlar (ilk: $adet, durum: TESLIM_EDILDI) iki nokta ile virgülden sonra birer boşlukla düzenlenir. Örneğin {user(id:1){name}} beş satırlık okunur bir sorguya dönüşür. Fragment'lar, değişken tanımları ($musteri: ID!), yönergeler (@include) ve şema tanımı (type, input, enum) de aynı standart biçimle yazılır. Tek satır seçerseniz tersini yapar: gereksiz boşluklar atılır ama tırnak içindeki metinlere dokunulmaz, sorgu bir URL'ye ya da koda gömülebilecek hâle gelir. Sözdizimi hatası varsa satırı ve sütunu gösterilir. # ile yazılmış yorumlar standart yazıcıda korunmaz; sonuç satırı kaç yorumun atıldığını söyler.

Bu araç graphql formatter, graphql beautifier, graphql query formatter, graphql pretty print aramalarıyla da biliniyor.

GraphQL nedir?

GraphQL, bir API'den hangi verinin isteneceğini istemcinin tarif ettiği bir sorgu dilidir. REST'te her adres sabit bir yanıt döndürürken GraphQL'de tek bir adrese gönderilen sorgu, istenen alanları iç içe süslü parantezlerle sayar ve yanıt tam o biçimde gelir. Facebook tarafından geliştirildi; GitHub, Shopify ve pek çok uygulama API'si GraphQL kullanır. Sorgu, mutation (değişiklik) ve fragment (yeniden kullanılan alan grubu) başlıca yapı taşlarıdır.

Fragment nedir?

Fragment, GraphQL'de birden çok sorguda tekrar eden alan grubuna verilen addır: fragment Adres on Siparis { sokak sehir } bir kez tanımlanır, sonra ...Adres yazılarak istenen yere eklenir. Böylece aynı alan listesini her sorguda yeniden yazmak gerekmez ve bir alan eklendiğinde tek yer değişir. Biçimlendirici fragment tanımını ayrı bir blok olarak, kullanıldığı yeri de ...Adres satırı olarak yazar.

GraphQL sorgusu ile GraphQL şeması arasındaki fark nedir?

Sorgu (query, mutation) istemcinin API'den ne istediğini söyler: hangi alanlar, hangi argümanlarla. Şema (schema, SDL) ise sunucunun neler sunduğunu tanımlar: type Siparis { id: ID! tutar: Float } gibi türler, alanlar ve bunların türleri. Sorgu şemaya göre doğrulanır; şemada olmayan bir alan istenirse sunucu hata verir. Bu araç ikisini de biçimlendirir ama sorguyu şemaya göre doğrulamaz, yalnız sözdizimini denetler.

Biçimlendirme sorgunun sonucunu değiştirir mi?

Hayır. GraphQL'de boşluk, satır sonu ve virgül anlam taşımaz; sunucu biçimlenmiş ve tek satırlık sorguya aynı yanıtı verir. Araç sorguyu graphql-js ayrıştırıcısıyla okuyup aynı ağacı standart biçimle yeniden yazar; alan sırası, takma adlar (alias), argüman değerleri ve dizeler korunur.

Tek fark yorumlardır: # ile başlayan satırlar sözdizimi ağacına girmez, bu yüzden standart yazıcı onları çıktıya almaz. Yorumlarınız önemliyse orijinal metni saklayın; araç kaç yorum satırının atıldığını sonuç satırında söyler. Açıklama dizeleri ("""...""") ise şemanın parçası olduğu için korunur.

Bu araç neyi denetler, neyi denetleyemez?

Araç sözdizimini denetler: kapanmamış süslü parantez, eksik iki nokta, yanlış yerde virgül ya da tırnak gibi hataları satır ve sütunuyla gösterir. Bu, sorgunun sunucuya ulaşmadan önce bozuk olup olmadığını anlamak için yeterlidir.

Şemaya göre doğrulama yapmaz: sorguladığınız alanın gerçekten var olup olmadığını, bir argümanın doğru türde olup olmadığını bilemez, çünkü elinde API'nin şeması yoktur. O denetim için API'nin kendi GraphiQL ya da Apollo Studio ekranını kullanın.

• Loglardaki tek satır sorguyu okumak → Okunaklı
• Sorguyu bir URL parametresine ya da koda gömmek → Tek satır
• Alan adı var mı, tür doğru mu → API'nin kendi GraphiQL ekranı

Sık sorulanlar

Tek satırlık GraphQL sorgusu nasıl okunur hale getirilir?

Sorguyu bu sayfadaki sol panele yapıştırın. Her alan kendi satırına iner ve iç içe seçimler 2 boşlukla girintilenir. Sonucu kopyalayabilir ya da .graphql dosyası olarak indirebilirsiniz.

Şema tanımı (type, input, enum) da biçimlenir mi?

Evet. Araç sorgu dilinin yanında şema tanım dilini (SDL) de okur: type, interface, input, enum, union ve scalar tanımları aynı standart biçimle yazılır, açıklama dizeleri korunur.

Yorumlarım neden kayboldu?

GraphQL'in resmî yazıcısı # yorumlarını taşımaz, çünkü yorumlar sorgunun sözdizimi ağacına girmez. Araç kaç yorum satırı atıldığını sonuç satırında söyler; yorumları korumak istiyorsanız orijinal metni saklayın.

Sorgum bir sunucuya gönderiliyor mu?

Hayır. Biçimlendirme tamamen tarayıcınızda yapılır; sorgu, içindeki kimlik ya da değerlerle birlikte bu sayfadan çıkmaz ve hiçbir API'ye gönderilmez.