Giriş (JSON)

Çıkış (.proto şeması)

Bu araç ne yapar

Elinde gerçek bir JSON payload’u var mı — örnek bir API yanıtı, bir webhook gövdesi, bir NoSQL deposundan bir satır — ve bunu Protocol Buffers message’ı olarak modellemek mi istiyorsun? Şemayı el ile yazmak yavaş ve hata yapmaya açık, özellikle iç içe nesneler ve diziler varken. Bu dönüştürücü JSON’u dolaşır, her alan için Protobuf tipi çıkarsar ve doğrudan projene yapıştırabileceğin temiz bir proto3 şeması verir.

Tip çıkarsama, kendi yazacağın şeyi izler: stringler için string, boolean’lar için bool, 32 bit’e sığan tam sayılar için int32, geri kalanlar için int64, tam sayı olmayan sayılar için double, eleman tipi tek biçimli diziler için repeated <T> (nesne dizilerinde tek bir iç içe message yeniden kullanılır) ve iç içe nesneler için iç içe message blokları. JSON, struct ile map’i ayırt edemez, bu yüzden tüm nesneler iç içe message olarak çıkar — verin gerçekten map ise el ile map<K, V> ile değiştir.

Alan adları camelCase veya kebab-case’den Protobuf’ta yaygın olan snake_case’e çevrilir. Alan numaraları, tanımlanma sırasına göre 1, 2, 3, … şeklinde atanır. Çıktı geçerli proto3’tür — bir .proto dosyasına yapıştır, protoc veya buf çalıştır, seçtiğin dilde üretilmiş kodun olur. Dönüştürme tamamen tarayıcında çalışır — ne JSON, ne alan adları, ne de değerler hiçbir yere gönderilmez.

Nasıl kullanılır

Üç adım. İyi biçimlendirilmiş herhangi bir JSON nesnesiyle çalışır — API yanıtları, log girdileri, fixture dosyaları, ne olursa.

JSON’unu yapıştır

JSON’u soldaki editöre bırak. Kök bir nesne olmalı ({ ... }) — verin dizi köklü ise önce bir nesnenin içine sar, örn. { "items": [...] }. Gerçekçi veri kullan: örnek ne kadar temsil edici olursa, çıkarsanan tipler uzun vadede istediğine o kadar yakın olur.

JSON’unda tırnaksız anahtarlar, sondaki virgüller veya başka acayiplikler varsa, önce JSON Fixer’dan geçir — Protobuf çalışmak için temiz bir nesne ister.

Dönüştür’e bas

Yeşil Dönüştür butonuna tıkla. Dönüştürücü JSON’daki her anahtarı dolaşır, bir Protobuf tipi seçer, iç içe nesneler için iç içe message blokları kurar ve şemayı en üstte syntax = "proto3"; olacak şekilde verir. Alan numaraları kaynak sırasıyla atanır.

.proto’yu kullan

Şemayı repondaki bir .proto dosyasına kopyala. Çıkarsanan tipleri gözden geçir — JSON örneğinin boş olduğu (boş dizi, null) alanlarda, tipin tahmin edildiğini belirten bir yorum görürsün. Gerektiği yerde ayarla, sonra protoc veya buf generate çalıştır ve dilinde kod üret.

Gerçekten zaman kazandırdığı durumlar

Bir üçüncü taraf API’sini Protobuf olarak modellemek

Bir tedarikçi JSON döndürüyor. Senin servisin Protobuf saklıyor. Gerçek bir yanıtı al, buraya yapıştır, o tip için bir başlangıç şeması elde et, sonra parlat. Dokümanı okuyup 50 alanı el ile yazmaktan iyidir.

JSON tabanlı bir servisi gRPC’ye taşımak

Bir HTTP+JSON mikroservisini gRPC’ye taşıyorsun. Her istek ve yanıt biçimi için bir .proto lazım. Yakaladığın her payload’u Protobuf şemasına çevir, hepsini tek bir dosyaya yapıştır, sözleşmenin taslağı çıkmış olur.

Bir Buf modülünü ayağa kaldırmak

Yeni bir Buf modülü kuruyorsun ve başlamak için gerçekçi şemalar mı lazım? Mevcut JSON fixture’larını dönüştür ve çıktıyı .proto dosyaların için tohum olarak kullan — sıfırdan yazmaktan çok daha hızlı.

Protobuf kodu için test fixture’ları yazmak

Takımın JSON test verisine sahip. Yeni kod Protobuf tüketiyor. JSON’dan <code>.proto</code> üret, sonra codegen tipleri inşa etsin — fixture’lar ile kodun senkron kalır.

Sık sorulanlar

JSON’um bir yere gönderiliyor mu?

Hayır. Dönüştürücü tamamen tarayıcında JavaScript olarak çalışır. JSON’un — anahtarlar, değerler, hassas her şey — makineni asla terk etmez. DevTools’u aç, Dönüştür’e tıklarken Network sekmesine bak. Sıfır istek.

int32, int64 ve double arasında nasıl seçim yapıyor?

Tam sayı değerler için, değerin işaretli 32 bit aralığa (-2^31 ile 2^31-1) sığıp sığmadığına bakar. Sığıyorsa int32. Sığmıyorsa int64. Tam sayı olmayan sayılar her zaman double olur. Verinin işaretsiz olduğunu biliyorsan veya fixed32 gibi belirli bir genişlik istiyorsan, çıktıyı düzenle — kullanılabilir tüm sayısal tipler ve tel üzerindeki kodlama tercihleri için skaler tip tablosuna bak.

Bir nesne ne zaman map olur, ne zaman iç içe message olur?

Her zaman iç içe message — asla map değil. JSON, struct ile map’i ayırt edemez, bu yüzden ikisinden birini tahmin etmek vakaların yarısında yanlış olur. Verin gerçekten anahtar-değer map’i ise (örn. metadata, header’lar, feature flag’ler), çıktıyı aç ve el ile message Foo { ... }’u map<string, V> foo = N; ile değiştir. Düzeltme verini görür görmez mekanik ve aşikar olur.

null ve boş diziler ne oluyor?

İkisi de çıktıda tipin yozlaşmış bir örnekten tahmin edildiğini bildiren bir yorum üretir. null varsayılan olarak "nullable" notuyla string’e düşer. Boş diziler varsayılan olarak "empty array" notuyla repeated string’e düşer. O tipleri gerçekten beklediğin şeyle değiştir.

Karışık tipli diziler neden repeated string olarak çıkıyor?

Protobuf heterojen listeleri doğrudan desteklemez. JSON dizinde karışık tipler varsa (bazıları string, bazıları sayı), temiz bir Protobuf karşılığı yoktur — ya google.protobuf.Value, ya bir oneof ya da veri biçimini yeniden düzenlemek gerekir. Dönüştürücü, sen karar veresin diye bunu bir yorumla işaretler.

Çok derin iç içe JSON’u kaldırıyor mu?

Evet. Her iç içe nesne, türetilmiş bir PascalCase adıyla iç içe bir message olur. İç içe geçme derinliği dönüştürücü tarafından değil, yalnızca yığın derinliğiyle sınırlıdır — çok derin iç içe API yanıtları bile temiz şekilde dönüşür.

Bu iki araçla JSON ↔ Protobuf gidiş-geliş yapabilir miyim?

Çoğunlukla. JSON’dan Protobuf’a sana bir şema verir; Protobuf’tan JSON’a sana bir örnek verir. JSON örneğinin temsili bir değere sahip olduğu alanlarda biçimler örtüşür. JSON’un null veya boş diziye sahip olduğu yerlerde, çıkarsanan Protobuf tipi tahmindir ve gidiş-geliş ancak tipi düzelttikten sonra tam olur.

İlgili araçlar

JSON ve şemalarla uğraşıyorsan, bunlar iyi gider:

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