GraphQL Fixer
Bozuk GraphQL SDL onarımı — eksik iki nokta üst üsteler, mükerrer alanlar, dengesiz süslü parantezler
GraphQL Fixer nedir?
Bir GraphQL şemasını bir araca yapıştırıp Syntax Error: Expected ":", found Name aldıysan ya da birinin alan adından sonra iki nokta üst üste koymayı unuttuğu için Schema Registry diff'inin patladığını gördüysen, bu acıyı bilirsin. SDL affetmez — bir tek noktalama eksiği bütün dokümanın parse olmasını engeller. Bu araç sık görülen bozulmaları onarır: alan adlarından sonra eksik kalan iki nokta üst üsteler, bir type içindeki mükerrer alanlar, dengesiz süslü parantezler, sarkan virgüller, yanlış yazılmış scalar referansları. Bozuk şemayı sol editöre yapıştır, yeşil Fix GraphQL!! butonuna bas, sağda temiz bir SDL gelir.
Onarım, type, field ve argument grameri için GraphQL Ekim 2021 spesifikasyonunu izler. Gramer küçük ama katıdır — kuralların tamamı için resmî Schemas and Types kılavuzuna bak. Fixer alan adlarına, type'lara ve directive'lere dokunmadan sadece yapıyı normalleştirir, bu sayede registry'ne karşı diff'in temiz kalır. Çıktıyı ekstra denemek istersen Apollo Server şema dokümanlarındaki doğrulayıcıya at ya da graphql-js ile gelen referans parser'dan geçir.
Şema, sadece söz dizimini onarması söylenmiş küçük bir AI servisine gönderilir — alan uydurma, yeniden adlandırma ya da silme yok. Onarılmış SDL düz metin olarak geri döner, projene yapıştırmaya hazırdır. Bizim tarafta hiçbir şey log'lanmaz.
GraphQL Fixer'ı nasıl kullanırsın
Üç adım. Her biri bu sayfadaki gerçek butonları kullanır.
Bozuk SDL yapıştır ya da örneği yükle
Bozuk GraphQL SDL'ini sol editöre bırak. Bu aracın ele aldığı türden bozulmaları — eksik iki nokta üst üsteler, bir mükerrer alan, eksik kapanış süslü parantezi — kasıtlı olarak içeren bir Order/Customer şeması yüklemek için Örnek GraphQL'a tıkla.
type Order {
id: ID!
placedAt DateTime!
total Money!
}Fixer, senin yazmadığın alanları uydurmaz. Sadece GraphQL gramerinin reddettiği söz dizimini onarır. Geçerli söz diziminin üstüne gelen adlandırma ve tasarım kuralları için GraphQL en iyi uygulamalar kılavuzu okumaya değer.
Fix GraphQL!! 'a tıkla
Yeşil butona bas. Fixer bozuk SDL'i okur, yapısal ve noktalama hatalarını tespit edip dokümanı yeniden yazar. Çalışırken bir yükleniyor göstergesi belirir. İki editör de SDL söz dizimi vurgulaması kullanır, böylece öncesi ve sonrasını yan yana inceleyebilirsin.
Temizlenmiş şemayı kopyala
Sağ panel onarılmış SDL'i gösterir. Alan adları, type'lar, açıklamalar ve directive'ler değişmez — sadece söz dizimi hataları düzeltilir. Çıktıyı kopyalayıp schema.graphql dosyana ya da registry'ne yapıştır.
Gerçekten ne zaman kullanırsın
Elle düzenlenmiş şemaları toparlama
Büyük bir schema.graphql dosyasını elle düzenlerken placedAt ile DateTime! arasında iki nokta üst üste koymayı kaçırdın mı? Hata mesajı sadece bir satır numarasıyla "Expected :" der. Fixer, alan alan dolaşmadan iki nokta üst üsteyi yerine koyar.
AI üretimi SDL'i onarma
Yeni bir özellik için bir LLM'e şema taslağı çıkarttın ve içinde mükerrer bir alan, süslü parantez yerine virgül ve eşleşmemiş bir { ile geri geldi. Klasik hata modu. Yapıştır, Fix'e bas, yeniden yazmadan parse edilebilir bir şema al.
Log'lardan şema çıkarma
Escape'lenmiş ya da yeni satırları silinmiş bir log satırından SDL parçası mı çektin? Fixer yapıyı normalleştirir, böylece kurtarılan şema gerçekten yeniden parse olur.
Schema Registry öncesi kontrol
Federe bir registry'ye değişiklik push'lamadan önce SDL'i fixer'dan geçir ki diff'i tıkayacak noktalama hatalarını yakala. Registry yüklemeyi reddedip seni gidiş-dönüş yaptırmaktan kurtarır.
Sık sorulan sorular
Hangi tür hataları onarır?
Bir alan adı ile type'ı arasındaki eksik iki nokta üst üsteler (en sık görülen bozulma), tek bir type içindeki mükerrer alanlar, eksik veya fazla kapanış süslü parantezleri, input object'lerdeki sarkan virgüller ve list type'ları çevreleyen eşleşmemiş köşeli parantezler. Alan, type ya da argument uydurmaz — sadece parser'ın reddettiği söz dizimini onarır.
Alan adlarımı veya type'larımı değiştirir mi?
Hayır. Alan adları, scalar adları, type adları, açıklamalar ve directive'ler aynen geçer. Fixer sadece yapısal söz dizimine dokunur — yazdığın adlar tam yazdığın gibi kalır.
Özel scalar'ları ve directive'leri destekler mi?
Evet. scalar Money, scalar DateTime, özel @auth ya da @deprecated directive'leri — hepsi korunur. Fixer, özel bir scalar'ın sunucunda kayıtlı olduğunu doğrulamaz, sadece SDL'in parse olduğunu doğrular.
Federe subgraph'lar (Apollo Federation) ne olacak?
Federation directive'leri (@key, @external, @requires) aynen geçer. Fixer salt bir söz dizimi onarım katmanıdır — federation composition çalıştırmaz. Temizlenmiş çıktıyı sonradan registry'nin composition adımından geçir.
Şemam bir sunucuya gönderiliyor mu?
Evet — dil modeli orada barındırıldığı için onarım küçük bir backend servisinde çalışır. Girdiyi log'lamayız ve cevap doğrudan tarayıcına döner. İstek başına 64 KB boyut limiti vardır.
Her zaman parse edilebilir bir şema üretir mi?
Yukarıda anlatılan sık bozulmalar için evet. Girdi, asıl niyetin belirsizleşeceği kadar yapı eksiğindeyse (örneğin bir type'ın gövdesi tamamen silinmişse), çıktı tahmin etmek yerine bir hata gösterebilir. Bu durumda bariz boşluğu elle doldur ve sonucu tekrar geçir.
Diğer GraphQL araçları
Onarım, GraphQL akışının bir parçasıdır. Geri kalanını bu araçlar kapsar: