Şema A (eski)

Şema B (yeni)

Diff

Her panele bir şema yapıştırın — siz yazarken diff güncellenir.

GraphQL Şema Diff Nedir?

Her API değişikliği birinin client'ını kırar. Bir şema PR'ını merge etmeden önce ihtiyacınız olan ilk şey, gerçekten neyin değiştiğinin net bir listesidir — boşlukları, yeniden formatlamayı ve gerçek değişiklikleri tek bir kırmızı-yeşil duvarına karıştıran 600 satırlık bir GitHub diff'i değil. Eski şemanızı sola, yenisini sağa yapıştırın; bu araç size üç liste verir: ne eklendi, ne kaldırıldı ve mevcut hangi alanlar tip değiştirdi. Şemalar, Ekim 2021 GraphQL spesifikasyonuna göre parse edilir; yani aracın "tip" veya "alan" olarak gördüğü şey, sunucunuzun gördüğüyle eşleşir.

Diff yapısaldır, metinsel değil. Bir tip içindeki alanları yeniden sıralamak görünmezdir. SDL'i yeniden formatlamak görünmezdir. Bir argümanı yeniden adlandırmak görünür. Order.total üzerinde Int'i Float'a çevirmek görünür. OrderStatus.REFUNDED gibi yeni enum değerleri eklemeler altında görünür. Bir union üyesini kaldırmak kaldırmalar altında görünür. Çıktı stili, GraphQL Inspector'ın ve Apollo schema checks'in kullandığı kategorizasyona uyar; böylece check'i sonunda CI'a taşıdığınızda workflow o araçlara aktarılır.

Her şey tarayıcınızda çalışır. Upload yok, log yok. Yayımlanmamış dahili şemalar için güvenli.

GraphQL Şema Diff Nasıl Kullanılır

Yapıştır, yapıştır, oku. Karşılaştır butonu yok — siz yazarken diff güncellenir.

Eski şemayı Panel A'ya yapıştırın

Mevcut production şemasını Şema A (eski) etiketli sol panele bırakın. Bir .graphql, .graphqls veya .gql dosyası için Yükle'ye basın ya da eşleştirilmiş başlangıç / iterasyon örneğini yüklemek için Örnek'e basın. Şemanın güzel olması gerekmez — formatlama farklılıkları yok sayılır.

Yeni şemayı Panel B'ye yapıştırın

Aday şemayı (PR'ınızdakini) Şema B (yeni) etiketli sağ panele bırakın. Araç her iki şemayı da tokenize eder, her tip tanımını dolaşır ve siz yazmayı bıraktıktan saniyenin çok altında bir süre sonra diff'i yeniden hesaplar. Referans parser'ın semantiği, burada görünenle sunucunuzun göreceği şeyin aynı olacak kadar graphql-js'i yakından takip eder.

Üç listeyi okuyun

Alt panelde üç bölüm var. Eklemeler (yeşil) yeni tipleri, yeni alanları, yeni enum değerlerini ve yeni union üyelerini listeler. Kaldırmalar (kırmızı) aynı kategorileri tersine listeler — genellikle breaking change'ler bunlardır, bu yüzden önce bu listeyi tarayın. Değişiklikler (kehribar) tipi değişen alanları ve argümanları listeler, örneğin Order.total: Int → Float. Şemalar denkse, bunu söyleyen tek bir yeşil banner görürsünüz.

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

PR Review

Bir takım arkadaşınız beş yeni alan ekleyen ve bir argümanı yeniden adlandıran bir PR açar. Şemayı bir formatter'dan da geçirdiği için GitHub diff'i okunamaz. Her iki sürümü buraya yapıştırın ve gerçek değişiklik listesini alın — genelde üç yüz değil, üç dört madde. Reviewer'lar girinti yerine gerçek semantiği tartışabilir.

Breaking Change'leri Yakalama

Bir alanı kaldırmak, bir return tipini daraltmak veya zorunlu bir argümanı yeniden adlandırmak, üretimdeki client'lar için breaking change'lerdir. Kaldırmalar ve Değişiklikler listeleri bunları doğrudan ortaya çıkarır. Merge'den önce diff'i çalıştırarak breaking change'in kasıtlı olduğunu doğrulayın. Aynı check sonunda CI'a aittir — bu workflow'un üretim sürümü için Apollo schema checks dökümanına bakın.

Onboarding Dökümantasyonu

Yeni bir mühendis "geçen sprint'te ne değişti?" diye sorduğunda, Pazartesi sürümünü ve Cuma sürümünü panellere yapıştırın ve diff'i sprint notlarınıza kopyalayın. Commit'leri kaydırmaktan daha hızlı ve çok daha okunabilir.

Federation Composition Sanity Check

Apollo Rover gibi federe bir composer çalıştırdıktan sonra önceki composed şemayı ve yenisini yapıştırın. Diff size composition'ın subgraph PR'ından beklediğiniz değişikliği yakalayıp yakalamadığını — ya da başka bir yerde sessizce bir şeyin değişip değişmediğini — söyler.

Sık Sorulan Sorular

Diff özellikle breaking change'leri yakalıyor mu?

Kaldırmalar ve Değişiklikler listelerindeki her şey potansiyel olarak breaking'tir — bir alanı kaldırmak, bir return tipini daraltmak, bir argümanı yeniden adlandırmak. Araç, GraphQL Inspector'ın yaptığı gibi her değişikliği "breaking" vs "non-breaking" olarak sınıflandırmaz, ancak yapılandırılmış liste hangilerine bakmanız gerektiğini açıkça gösterir.

Alan sırası bir değişiklik sayılır mı?

Hayır. Bir tip içindeki alanları yeniden sıralamak yapısal olarak özdeştir ve yok sayılır. Enum değerlerini, union üyelerini ve argümanları yeniden sıralamak için de aynısı geçerli. Yalnızca eklenen, kaldırılan veya tip-değiştiren öğeler raporlanır.

Açıklamalar ve yorumlar?

Block-string açıklamaları ve yorumlar yapı karşılaştırmasında yok sayılır. Bir alana açıklama eklemek diff'te görünmez. Doküman değişikliklerini takip etmek istiyorsanız, bunu burada değil, PR'ınızdaki formatlanmış SDL diff'inde yapın.

Şemalarım bir sunucuya gönderiliyor mu?

Hayır. Tokenizer ve diff tamamen tarayıcınızda çalışır. Hiçbir şey upload edilmez, hiçbir şey loglanmaz. Dahili veya yayımlanmamış şemaları yapıştırmak güvenlidir.

Ne kadar büyük bir şema yapıştırabilirim?

Sayfa her girişi 5 MB ile sınırlar. Bunun ötesinde Ace editörünün kendisi takılmaya başlar. Birkaç yüz tipli şemalar sorun değil.

Bunu CI'da çalıştırabilir miyim?

PR push etmeden önceki yerel sanity check'ler için bu sayfa iyi. Breaking change'de build'i fail eden CI gate'leri için, özel GraphQL Inspector CLI'sini veya Apollo schema checks'i kullanın — her ikisinin de uygun exit-code semantiği ve policy konfigürasyonu var.

Diğer GraphQL Araçları

Diff, GraphQL ile çalışmanın bir parçası. Bu araçlar geri kalanını halleder: