Giriş (.proto şeması)

Çıkış (JSON örneği)

Bu araç ne yapar

Bir Protocol Buffers şeman var ve o mesajlardan birinin nasıl bir JSON görüneceğine dair bir örneğe ihtiyacın var — bir test fixture’ı, bir OpenAPI örneği, mocklanmış bir gRPC yanıtı, ne olursa olsun. Uzun bir .proto dosyasından elle JSON şekli yazmak yorucudur ve hata yapmak çok kolaydır. Bu dönüştürücü şemayı okur, en son tanımlanan message’ı (tipik "dış" tip) seçer ve ona alan-alan uyan bir JSON nesnesi üretir.

Çıkış resmi proto3 varsayılan değerlerini kullanır: string ve bytes için boş string, sayısal tipler için 0, bool için false, repeated için [], map için {} ve enum alanları için sıfır değerli enum sabiti. İç içe mesajlar özyinelemeli olarak açılır. 64-bit tamsayılar proto3 JSON eşleme spesifikasyonuna uymak için JSON string olarak çıkar — JS Number içine int64 koyamazsın, hassasiyet kaybedersin.

Her şey tarayıcında yerel olarak gerçekleşir — .proto upload’ı yok, sunucuya gönderilen şema yok, AI çıkarım çağrısı yok. Sadece syntax/package/import direktiflerini, yorumları (satır ve blok), iç içe message ve enum bloklarını, oneof, map<K, V>, repeated, optional ve alan opsiyonlarını (okunur ama yok sayılır) işleyen elle yazılmış bir parser çalışır. protobufjs tarzı tam bir runtime gerekiyorsa o ayrı bir mesele — ama "bu şemadan bana bir JSON şekli ver" için bu daha hızlı.

Nasıl kullanılır

Üç adım. Çıktı JSON; bir fixture’a, örnek bloğuna veya istek gövdesine doğrudan yapıştırmaya hazır.

.proto şemanı yapıştır

Şemayı sol editöre bırak. Üstteki syntax = "proto3"; sorun değil ama opsiyonel — parser umursamıyor. Yorumlar, package bildirimleri ve import ifadeleri temiz bir şekilde atlanır. Birden fazla mesajın varsa, parser kök seviyedeki son message’ı (tipik dış/bileşik tip) kök olarak kullanır.

Farklı bir mesajı dönüştürmek mi istiyorsun? İlgilendiğin mesajı dosyanın en altına taşı. Şema iç içe tipler, enum’lar ve oneof blokları içerebilir — hepsi çözümlenir.

Convert’e bas

Yeşil Convert düğmesine tıkla. Parser şemayı tokenleştirir, bir mesaj ağacı oluşturur ve kök mesajı dolaşarak her alan için proto3 varsayılanlarını yazar. İç içe mesajlar inline açılır. repeated alanlar element şekli hakkında ipucu olarak tek elemanlı bir dizi üretir — boş dizi yapıyı göstermezdi.

JSON’u kullan

Sonucu test fixture’ına, OpenAPI örnek bloğuna, gRPC-Web mock’una veya request/response şekli gerektiği yere kopyala. Anahtarlar tam olarak .proto alan adlarıyla eşleşir — codegen’in yapıyorsa sonra camelCase’e geçirirsin.

Gerçekten zaman kazandırdığı yerler

Testler için gRPC yanıtlarını stub’lamak

Servis handler’ın bir Protobuf yanıtı döndürüyor. Unit test mesaj şekliyle eşleşen bir JSON fixture’ı istiyor. <code>.proto</code>’yu yapıştır, JSON’u kap, fixtures klasörüne bırak. 30 alanı elle yazıp birini unutmak artık yok.

gRPC-gateway için OpenAPI örnekleri

Protobuf servislerini REST olarak sunmak için grpc-gateway veya benzeri mi çalıştırıyorsun? Her operasyon bir JSON örneği ister. Her .proto mesajını JSON iskeletine çevir ve spec’indeki example anahtarının altına yapıştır.

JSON Schema için başlangıç noktası

Bir <code>.proto</code> sözleşmesine uyan JSON isteklerini doğrulamak istiyorsun. Önce JSON örneğine dönüştür, JSON-Schema-from-sample aracına ver, saniyeler içinde başlangıç şeması elinde olur.

API client’larda istek gövdelerini doldurmak

HTTP transcode edilmiş bir gRPC API’yi Postman veya curl ile mi test ediyorsun? .proto’yu yapıştır, JSON iskeletini istek gövdesine kopyala, gerçekten göndermek istediğin değerleri doldur.

Sık sorulan sorular

.proto şemam herhangi bir yere gönderiliyor mu?

Hayır. Parsing tamamen tarayıcında JavaScript ile yapılır. Şemandan hiçbir şey — mesaj adları, alan adları, package yolları — makineni terk etmez. DevTools’u aç, Network sekmesine bakarken Convert’e tıkla. Sıfır istek.

proto2’yi proto3 kadar destekliyor mu?

Çoğunlukla. Parser required ve optional gibi proto2 sözdizim token’larını işler, ama çıkış değerleri proto3 varsayılanlarını kullanır (proto3 JSON eşlemesinin belirttiği şey). [default = ...] ile açıkça varsayılanlar verilmiş bir proto2 dosyan varsa, o varsayılanlar çıkışa uygulanmaz.

Hangi mesajı dönüştüreceğini nasıl seçiyor?

Dosyada bildirilmiş kök seviyedeki son message’ı kullanır. Gerçek şemalarda dış/bileşik tip genellikle bağımlılıklarından sonra bildirilir, bu yüzden bu istediğinle örtüşür. Yanlışını seçerse, istediğin mesaj sonda olacak şekilde dosyayı yeniden sırala.

int64 değerleri çıktıda neden string?

Çünkü JSON’da yalnızca IEEE-754 double’lar var ve bunlar 2^53 üzerinde hassasiyet kaybeder. Resmi proto3 JSON eşlemesi int64, uint64, fixed64, sfixed64, sint64’ün JSON string olarak kodlanmasını ister. Biz bu konvansiyona uyuyoruz.

oneof, map ve repeated ne olacak?

Üçü de çalışır. oneof alanları normal alanlar gibi parse edilir (JSON nesnesi birini seçmek yerine hepsini içerir — istemediklerini tipik olarak silersin). map<K, V> boş bir {} nesnesi yazar. repeated element şeklini gösteren tek elemanlı bir dizi yazar — gerçek verine uydurmak için çoğaltabilir veya silebilirsin.

import’ları takip ediyor mu?

Hayır. import ifadeleri tanınır ve atlanır. Dosyalar arası mesaj tipleri çıktıda null’a çözümlenir. Dosyalar arası çözümleme gerekiyorsa, import edilen dosyalardan ilgili mesajları aynı girişe yapıştır.

Şema ne kadar büyük olabilir?

On binlerce satır, sorun değil. Her şey yerel, dolayısıyla upload yok, rate limit yok, ağ gecikmesi yok.

İlgili araçlar

Protobuf, JSON ve şemalarla cebelleşiyorsan bunlar iyi tamamlar:

Protobuf’tan JSON’a Dönüştürücü