Girdi (.proto şeması)

Çıktı (biçimlendirilmiş .proto)

Bu araç ne yapar

Karışık girintili, üst üste yapışmış alan bildirimleri olan ya da bir kopyala-yapıştırdan kalmış rastgele boş satırlarla dolu bir Protocol Buffers şemasını yapıştırırsın ve bunun reponun geri kalanına benzemesini istersin. Bu biçimlendirici dosyayı her süslü parantez seviyesi için iki boşluk girinti, = etrafında tam bir boşluk, , sonrasında bir boşluk ve bloklar arasında en fazla bir ardışık boş satırla yeniden yazar. Yorumlar — hem // satır yorumları hem de /* ... */ blok yorumları — koyduğun yerde aynen kalır.

Şemayı parse etmez ya da doğrulamaz, yani buf format ya da editörünün “Format Document” özelliğinin kabul etmeyeceği biraz bozuk girdilerde de çalışır. .proto dosyanın bir yerinde sözdizimi hatası varsa, dosyanın geri kalanı yine de etrafında biçimlendirilir. Madalyonun öbür yüzü: gerçek bir parser tabanlı biçimlendiricinin yapabileceği gibi alanları yeniden sıralayamaz, import sırasını normalize edemez veya kullanılmayan seçenekleri çıkartamaz. Bunun için build pipeline’ında buf format çalıştır.

Her şey tarayıcında çalışır — yükleme yok, oran sınırı yok, şema hiçbir yere gönderilmez. Şemada dahili paket adları, tip adları veya üçüncü taraf bir API’ye göndermek istemeyeceğin başka şeyler varsa işine yarar. Tarayıcının belleğe sığdırabildiği herhangi bir boyutta dosyada çalışır; on binlerce satır bile bir saniyenin çok altında biçimlendirilir.

Nasıl kullanılır

Üç adım. Yazmayı bıraktıktan ~300 ms sonra çıktı güncellenir.

.proto şemanı yapıştır

Şemayı sol editöre bırak. syntax, package, import direktifleri, message blokları, iç içe enum’lar, oneof, map<K, V> — hepsi işlenir. Karışık satır sonları (CRLF) çıkışta LF’ye normalize edilir.

Biçimlendirici hiçbir şeyi yeniden sıralamaz — alanlar, importlar ve seçenekler yazdığın sırada kalır. Kanonik sıralama istiyorsan, sonrasında buf format çalıştır.

Biçimlendirilmiş çıktıyı oku

Sağda: aynı şema, her { seviyesi için 2 boşluk girintilenmiş. } ile başlayan satırlar yazılmadan önce bir seviye dışarı alınır. Birden fazla ardışık boş satır tek satıra düşer. Satır sonu boşluğu silinir. Yorumlar göreli konumları dahil olduğu gibi korunur.

Sonucu kullan

Editörüne geri yapıştır ya da formatted.proto olarak indir. protoc açısından çıktı, girdiyle bayt bayt eşdeğerdir — sadece boşluklar değişir — yani wire format ya da üretilen kod farklarından endişelenmeden geri yerine koyabilirsin. Doğrulamak için protoc --descriptor_set_out=before.pb input.proto komutunu girdiye, aynısını biçimlendirilmiş çıktıya çalıştır: descriptor’lar eşleşecektir.

Gerçekten zaman kazandırdığı durumlar

Sohbetten ya da dokümandan yapıştırılan .proto’yu temizleme

Bir takım arkadaşı Slack’e bir şema parçası yapıştırıyor, girinti darmadağın, sen bunu repona almak istiyorsun. Buraya bırak, biçimlendirilmiş sürümü kopyala, dosyana yapıştır. Editörde “tümünü seç, yeniden tab’la” dansından daha hızlı.

Eski bir repodaki legacy .proto’ları standartlaştırma

Her dosyanın farklı girinti kullandığı bir Protobuf reposu devraldın. Her dosyayı bu biçimlendiriciden geçir, tek bir normalizasyon commit’i olarak push’la, sonra CI’da buf format’ı aç ki öyle kalsın.

Üretilmiş bir .proto’yu hızlıca kontrol etme

Bazı kod üreticileri (JSON Schema → Protobuf, OpenAPI → Protobuf) geçerli ama çirkin şemalar üretir. Çıktıyı biçimlendir, göz at, üreticiyi olduğu gibi tutmaya mı yoksa elle düzenlemeye mi karar ver.

protoc ya da buf yükleyemediğin durumlar

Kilitli bir makinedesin, misafir ağındasın ya da sadece tarayıcıdan bir PR review’u yapıyorsun. Tarayıcı-yalnız biçimlendirici, Protocol Buffers toolchain’ini kurmadan aynı okunabilir çıktıyı verir.

Sık sorulanlar

Şemam bir yere gönderiliyor mu?

Hayır. Biçimlendirici tamamen tarayıcında JavaScript olarak çalışır. Şemayla ilgili hiçbir şey — message adları, paket yolları, yorumlar — makineyi terk etmez. DevTools’u aç, yapıştırırken Network sekmesine bak; sıfır istek göreceksin.

Yorumları koruyor mu?

Evet — hem // tek satır yorumları hem de /* ... */ blok yorumları koyduğun yerde aynen kalır. Kendi satırındaki yorumlar göreli konumlarını korur; alan satırının sonundaki trailing yorumlar o alana yapışık kalır. Yorumların bozulmadan kalabilmesi için satır tabanlı yaklaşım özellikle seçildi.

buf format’tan farkı ne?

buf format şemayı bir sözdizim ağacına parse eder ve yeniden yazar. Bu daha güçlü garantiler verir — kanonik seçenek sıralaması, tutarlı enum büyük-küçük harf kullanımı vb. — ama şemanın temiz parse edilmesini gerektirir. Bu biçimlendirici satır tabanlıdır, dolayısıyla buf’ın reddedeceği biraz bozuk girdilerde de çalışır ve kanonik sıralama dayatmaz. Tamamlanmış kod için buf format çalıştır. Düzenleme aşamasındaki şemalar ya da üçüncü taraf parçaları için bunu kullan.

Şemanın anlamını değiştirir mi?

Hayır — yalnızca boşluklar değişir. protoc hem girdiden hem de çıktıdan aynı FileDescriptorProto’yu üretir. protoc --descriptor_set_out=before.pb input.proto komutunu girdi ve biçimlendirilmiş dosya üzerinde çalıştırarak doğrulayabilirsin; ikili descriptor’lar, source-info span değişiklikleri (ki onlar reflection meta verisidir, wire format değildir) dışında özdeştir.

Girinti genişliği — 2 boşluğun dışında bir şeye değiştirebilir miyim?

Çıktı, resmi Protocol Buffers stil rehberindeki kuralla uyumlu olarak her süslü parantez seviyesi için 2 boşluğa sabitlenmiştir. 4 boşluk ya da tab gerekiyorsa çıktıyı sed’den ya da editörünün tab dönüşümünden geçir. Biçimlendiricinin çıktısını kanonik tutmak takımlar arası konfigürasyon kaymasını önler.

CRLF satır sonlarını işliyor mu?

Evet — girdideki CRLF (\r\n) çıkışta LF’ye (\n) normalize edilir. Kaydedilen dosyada CRLF gerekiyorsa, editörün kayıt sırasında satır sonu ayarına göre yeniden kodlayacaktır.

İlgili araçlar

Protobuf şemalarıyla çalışıyorsan bunlar iyi gider:

Protobuf Biçimlendirici