GraphQL SDL

TypeScript

Bu dönüştürücü ne yapar

Bir GraphQL şeman var. Frontend'in TypeScript. Aralarda bir yerde, şemayla alan-alan eşleşen bir tip seti gerekiyor — hem de şimdi: beş dakikalık codegen build'inden sonra değil, yeni bir projeye graphql-code-generator'ı bağlamadan sonra değil, junior'a hangi plugin'i kuracağını anlattıktan sonra değil. GraphQL SDL'i sol panele yapıştır, sağ panel deyimsel TypeScript geri verir: object ve input tipler için interface, enum'lar için enum, union ve scalar'lar için sade type takma adları.

Eşleme, çoğu TypeScript kodunun beklediği kurallara uyar. Yerleşik scalar'lar TypeScript ilkel karşılıklarına oturur: String ve ID, string'e döner; Int ve Float, number'a; Boolean, boolean'a. DateTime gibi özel scalar'lar varsayılan olarak string'e düşer, ileride genişletmeyi unutma diye yanına // custom scalar işareti gelir. Non-null alanlar (name: String!) zorunlu property olarak yazılır; nullable alanlar ? niteleyicisiyle çıkar. Liste tipleri [Order!]!, Order[]'a dönüşür. type Order implements Node, interface Order extends Node'a döner — GraphQL'deki interface ilişkisi TS'in yapısal extends'ine temizce eşlenir.

Yükleme yok, ağ çağrısı yok, yapay zekâ yok. Dönüşüm, elle yazılmış bir SDL tokenizer'da istemci tarafında olur — şeman sayfayı asla terk etmez. Şema iç kullanım ya da yayın öncesi olduğunda istediğin de tam budur.

Nasıl kullanılır

Üç adım. Dönüşüm otomatik — Convert düğmesi yok.

Yapıştır, yükle ya da örneği aç

SDL'ini sol GraphQL SDL paneline bırak. Yazmayı bırakır bırakmaz sağ panel güncellenir. .graphql / .graphqls / .gql dosyası için Yükle, gerçekçi bir e-ticaret şeması yüklemek için Örnek'e tıkla. Küçük bir SDL parçası şöyle görünür:

type Order implements Node { id: ID! placedAt: DateTime! status: OrderStatus! items: [OrderItem!]! } enum OrderStatus { PENDING PAID SHIPPED DELIVERED CANCELLED }

Hem sunucu tarzı şemalar (extend type Query içerenler) hem de tek başına tip tanımları çalışır. Block-string açıklamaları ("""...""") yakalanır ve üretilen tipin üstüne JSDoc yorumu olarak yazılır — bu, GraphQL referans uygulamasının belgelediği konvansiyondur.

Üretilen TypeScript'i oku

Sağ panel tipleri türlerine göre gruplayarak yazar: önce scalar'lar, sonra enum, union, interface, input tipleri ve en son object tipleri. Her grup içinde tanımlar kaynak sırasını korur, böylece elle yazdığın tiplere karşı diff mümkün olduğunca küçük olur. SDL'de bir parse hatası varsa (eşlenmemiş süslüler, kapatılmamış block-string vb.) çıktı paneli istisna fırlatmak yerine tek bir // Invalid GraphQL: ... yorumu gösterir — başlangıç parse'ı başarısız olduğunda Apollo Server'ın kullandığı kalıpla aynı.

Kopyala ya da indir

Kopyala'ya bas, tipleri projendeki bir schema.types.ts dosyasına doğrudan yapıştır. İndir'e bas, .ts dosyası olarak kaydet. Çıktı düz metin — modül import'u yok, runtime kodu yok — bu yüzden frontend ya da backend, herhangi bir TS projesine doğrudan oturur.

Gerçekten ne zaman kullanırsın

Codegen kurmadan hızlıca tip almak

Mevcut bir GraphQL endpoint'ine karşı bir frontend prototipliyorsun ve sırf üç sorgunun tipini almak için tam bir codegen pipeline'ı ayağa kaldırmak istemiyorsun. Şemayı yapıştır, çıktıyı types.ts'e kopyala, prototipi at. Proje gerçekleşmeye başladığında düzgün bir codegen pipeline'ına sonra geçersin.

Codegen'in ne üreteceğini önden kontrol etmek

Şemaya yeni bir tip eklemeden önce, önerilen SDL'i buraya yapıştırarak TypeScript çağıranlarının nasıl bir biçim alacağını gör. Bazen SDL'de güzel okunan bir alan tuhaf TS üretir — nullable'lardan oluşan opsiyonel bir liste, TS'in rezerve kelimesiyle çakışan değer içeren bir enum gibi — ve bunu PR merge'den sonra fark etmek yerine burada görmek çok daha ucuza geliyor.

TypeScript ağırlıklı bir ekip için şema dokümanı

TS odaklı bir ekibi GraphQL API'sine alıştırıyor musun? Şemayı yapıştır, üretilen tipleri wiki'ye kopyala. TS interface'leriyle düşünen mühendisler şemayı ham SDL'den çok TS görünümünden daha hızlı kavrar — veri biçimleri aynı, sözdizimi sadece her gün akıcı okudukları biçim.

GraphQL endpoint'ine giden tek seferlik scriptler

Bir kerelik bir CLI aracı, bir Node script'i, bir admin görevi — yanıtın etrafında biraz tip istediğin ama tam codegen kurulumuna girmek istemediğin her şey. Yapıştır, kopyala, yanıtı tipize et, script'i çalıştır. Tek seferlik, ama kendini rezil etmemeye yetecek kadar tip güvenli.

Sık sorulan sorular

Operasyon tiplerini (Query / Mutation sonuç tipleri) üretiyor mu, yoksa sadece şema tiplerini mi?

Sadece şema tiplerini — SDL'de tanımlananları. Operasyon sonuç tipleri istemcinin çalıştırdığı belirli sorgu ya da mutation'a bağlıdır ve bu tam olarak graphql-code-generator'ın typed-document-node plugin'iyle yaptığı iştir. Bu sayfa şema yarısını kapsar: SDL'indeki her type, interface, enum, input, union ve scalar bir TS tanımına dönüşür.

Nullable ile non-null alanlar nasıl ele alınıyor?

Non-null alanlar (name: String!) zorunlu, opsiyonel olmayan TS property'leri olarak çıkar: name: string;. Nullable alanlar (name: String) opsiyonel olarak çıkar: name?: string;. Çıktı temiz kalır — her yerde | null union'u yok — ki çoğu tüketicinin istediği de budur. Onun yerine strict null checks istersen, çıktı üzerinde bir find-and-replace çekersin.

[Order] ya da [Order!]! gibi liste tipleri ne olur?

Listeler TS dizilerine döner. [Order!]!, zorunlu bir alanda Order[] olarak çıkar. [Order], opsiyonel bir alanda Order[] olarak çıkar. Eleman düzeyindeki nullability okunabilirlik için ezilir — korumak istersen üretilen bir T[]'yi elle (T | null)[]'a çevirebilirsin, ama pratikte gerçek hayattaki neredeyse hiçbir kod tabanı iç nullability'i ayrı ayrı okumuyor.

Özel scalar'lar nasıl ele alınıyor?

Özel scalar'lar (ID, String, Int, Float ya da Boolean dışındaki her şey) varsayılan olarak string'e düşer ve bulup genişletmesi kolay olsun diye yanlarına // custom scalar işareti gelir. DateTime scalar'ı için string | Date'e genişletebilirsin; JSON scalar'ı için unknown'a ya da tipli bir biçime. Varsayılan string, çoğu sunucunun JSON olarak hatta yolladığıyla örtüşüyor.

Şemam bir sunucuya gönderiliyor mu?

Hayır. Dönüşüm tamamen tarayıcında çalışır — SDL istemci tarafında tokenize edilir ve TypeScript çıktısı doğrudan sağ panele basılır. Hiçbir şey yüklenmez, hiçbir şey loglanmaz. İç kullanım veya yayımlanmamış şemaları yapıştırmak güvenli.

Çıktı tekrar aynı SDL'e döner mi?

Hayır — amacı da bu değil. Çıktı TypeScript, yani başka bir dil. TS çıktısını SDL paneline geri yapıştırmak parse hatası verir. Kendi GraphQL SDL'ini biçimlendirmek istiyorsan, aşağıda linkli GraphQL Formatter'ı kullan; bunun için yapıldı.

Diğer GraphQL araçları

Tip üretmek bir parça. Bu araçlar GraphQL akışının geri kalanını halleder:

GraphQL Şemasından TypeScript'e