Giriş (.proto şeması)

Çıkış (TypeScript)

Bu araç ne yapar

Elinizde bir Protocol Buffers şeması var ve bu mesajları sunan bir gRPC ya da HTTP transcode edilmiş backend ile konuşması gereken bir TypeScript ön yüzünüz var. Resmi codegen zinciri (protoc ile ts-proto veya protobuf-ts) araç kurulumu, plugin yapılandırması ve build adımı bağlamayı gerektirir. Bu dönüştürücü aynı işi tarayıcınızda yapar — yapıştırın, çıktıyı kopyalayın, projenize bırakın.

Tür eşlemesi gerçek kod tabanlarında elle yazılmış türlerin nasıl göründüğünü izler: string/bytes → string/Uint8Array, bool → boolean, küçük sayısal türler (int32, uint32, float, double) → number, ve 64 bit tam sayı türleri (int64, uint64, fixed64, sfixed64, sint64) → string; bu da proto3 JSON eşleme spesifikasyonuna uyar. repeated T T[] olur, map<K, V> Record<K, V> olur, iç içe mesajlar iç içe interface bildirimlerine dönüşür.

Alan adları snake_case’ten (Protobuf geleneği) camelCase’e (JavaScript/TypeScript geleneği) dönüştürülür — bu, proto3 JSON kodlayıcısının varsayılan davranışıyla örtüşür. Enumlar string-literal union türlerine dönüşür (type OrderStatus = 'ORDER_STATUS_UNSPECIFIED' | 'ORDER_STATUS_PENDING' | ...); çoğu TypeScript kod tabanının gerçekten istediği şey budur — bir enum’un çalışma zamanı yükü gerekmez. Dönüştürücü tamamen tarayıcınızda çalışır; şemanızdan hiçbir şey sayfayı terk etmez.

Nasıl kullanılır

Üç adım. Çıktı, saniyeler içinde bir <code>.ts</code> dosyasına yapıştırılmaya hazır.

.proto şemanızı yapıştırın

Şemayı sol editöre bırakın. Üstteki syntax = "proto3"; sorun değil ama isteğe bağlı. Parser iç içe message bloklarını, enum bildirimlerini, oneof’u, map<K, V>’yi ve alan seçeneklerini işler. import’lar tanınır ama atlanır — gerekiyorsa import edilen türleri satır içine yapıştırın.

Alan adı dönüşümü otomatiktir: .proto’daki order_id, TypeScript’te orderId olur. Mesaj ve enum adları olduğu gibi kalır (zaten PascalCase).

Çıktıyı okuyun

Sağda: her mesaj için export interface ve her enum için string-literal union’lı export type içeren TypeScript. İç içe türler ebeveyninden önce gelir, böylece dosya bildirim sırasındadır. Dosyayı projenize ekleyin ve arayüzleri gRPC istemcinizden ya da fetch handler’ınızdan import edin.

Türleri kullanın

Arayüzleri fetch / gRPC-Web / Connect-RPC istemcinize bağlayın. Şekil proto3 JSON kodlamasıyla uyumludur, bu nedenle JSON yanıtlar manuel dönüşüm olmadan doğrudan tipli şekle parse edilir. Sunucunuz standart dışı JSON kodlama kullanıyorsa int64 işlemesini ayarlayın.

Gerçekten zaman kazandırdığı durumlar

Yeni bir gRPC ön yüzü için tür taslağı çıkarmak

Mevcut bir gRPC servisinin üzerine yeni bir TS uygulaması inşa ediyorsunuz. Henüz tam codegen’e ihtiyacınız yok — fetch çağrılarınızı tiplemek için sadece arayüz şekilleri yeterli. .proto’yu yapıştırın, çıktıyı types.ts’e koyun, tipleriniz hazır.

Bir Protobuf API değişikliğini gözden geçirmek

Backend’deki bir takım arkadaşı bir mesaja alanlar ekledi. Build’i çalıştırmadan bunun frontend tiplerini nasıl etkilediğini görmek istiyorsunuz. Yeni .proto’yu yapıştırın, TypeScript çıktısını mevcut tiplerinizle diff’leyin, odaklanmış bir review yorumu bırakın.

Üretilen türleri çapraz kontrol etmek

Build’iniz protobuf-ts veya ts-proto kullanıyor; bunlar kendi gelenekleriyle türler üretir. Düz TS arayüzlerinin nasıl göründüğüne dair temiz bir referans için şemayı buraya yapıştırın — dokümantasyon ya da göç planlaması için faydalıdır.

Tek seferlik scriptler ve tek atımlık entegrasyonlar

gRPC-gateway’e JSON POST eden hızlı bir Node scripti yazıyorsunuz. 30 satırlık bir script için tüm Protobuf zincirini kurmak fazla. Arayüzleri buradan alın, hiçbir törene gerek kalmadan tip güvenliğine sahip olun.

Sık sorulanlar

Şemam herhangi bir yere gönderiliyor mu?

Hayır. Parser ve TS yayınlayıcı tamamen tarayıcınızda JavaScript olarak çalışır. DevTools’u açıp yapıştırırken Network sekmesini izleyin — sıfır istek. Şemanız iç tür adları, paket yolları ya da üçüncü taraf servise göndermek istemeyeceğiniz bir şey içeriyorsa kullanışlıdır.

int64 alanlar neden string olarak tipleniyor?

JavaScript Number’ları IEEE-754 double’dır ve 2^53’ün üzerinde hassasiyet kaybeder. Resmi proto3 JSON eşlemesi int64, uint64, fixed64, sfixed64 ve sint64’ün JSON string olarak kodlanmasını gerektirir. Bu yüzden TS arayüzü onlar için string kullanır — sunucunuzun gerçekten gönderdiğiyle örtüşür. bigint isterseniz çıktıda find-replace yapın.

Enumlar neden TS enum yerine string union?

Bugün çoğu TypeScript projesi TS enum’lar yerine string-literal union’ları tercih ediyor — çalışma zamanı maliyeti yok, daha iyi tree-shaking, ve enum’ları string adıyla serileştiren proto3 JSON kodlamasıyla örtüşüyor. const enum veya sayısal enum istiyorsanız, union’dan dönüşüm mekanik bir iştir.

map<K, V>’yi nasıl ele alıyor?

Record<K, V> olarak basılır. String dışı anahtarlara sahip Protobuf map’leri (örn. map<int32, string>) Record<number, string> olur. JSON yalnızca string anahtarlara sahiptir, bu yüzden çalışma zamanında proto int dese bile anahtarlar string olur — bu, dönüştürücünün değil, proto3 JSON spesifikasyonunun bir özelliğidir.

Alanlar opsiyonel olarak işaretleniyor mu?

Hayır. proto3 alanları JSON çıktısında her zaman bulunur (varsayılanlarla — boş string, 0, false, [], {}); bu yüzden TypeScript arayüzü her alanı zorunlu olarak işaretler. Gerçekten opsiyonel alanlar istiyorsanız (çünkü çalışma zamanınız onları atlayabilir), her alan adından sonra elle ? ekleyin.

oneof’u destekliyor mu?

Bir oneof’un her alanı normal bir arayüz alanı olarak yayılır. Çıktı, oneof’un ima ettiği "tam olarak bir tane" kısıtını zorlamaz — bunun için ayrımlı bir union gerekir, o da çalışma zamanı semantiğinize bağlıdır. Daha sıkı türler istiyorsanız çıktıyı elle düzenleyin.

İlgili araçlar

Protobuf, JSON ve TypeScript ile çalışıyorsanız bunlar iyi eşleşiyor:

Protobuf’tan TypeScript’e Dönüştürücü