Girdi (.proto şeması)

Çıktı (Kotlin)

Bu araç ne yapar

Elinde bir Protocol Buffers şeması var — belki backend ekibinden, belki üçüncü taraf bir API sözleşmesinden — ve bu şemaya karşılık tipli formlara ihtiyaç duyan bir Kotlin kod tabanı var. Ya bir gRPC backend’ine seslenen bir Android uygulaması, ya da JSON ile kodlanmış Protobuf mesajlarını parse eden sunucu tarafı Kotlin. Sadece data class formlarına ihtiyacın varsa grpc-kotlin’in tam codegen pipeline’ını kurmak abartı olur — yapıştır, kopyala, içeri at.

Tip eşlemesi Kotlin deyimlerini takip eder: string → String, bool → Boolean, bytes → ByteArray, int32/sint32/fixed32 → Int, int64/sint64/fixed64 → Long, double → Double, float → Float. repeated T, varsayılanı emptyList() olan List<T>’ye dönüşür; map<K, V>, varsayılanı emptyMap() olan Map<K, V>’ye dönüşür. Tekil iç içe mesaj alanları, varsayılanı null olan nullable’dır (?) — proto3’ün has-value semantiği ile örtüşür.

Alan adları proto’daki snake_case’den Kotlin’deki camelCase’e (order_id → orderId) dönüştürülür — resmi Kotlin stiline göre standart Kotlin kodlama kuralı budur. Sınıf ve enum adları PascalCase olarak kalır. Her enum, Int taban değeriyle bir enum class’a dönüşür. Dönüşüm tamamen tarayıcında çalışır — .proto dosyan sayfayı asla terk etmez.

Nasıl kullanılır

Üç adım. Çıktı doğrudan yapıştırılabilir Kotlin.

.proto şemanı yapıştır

Şemayı sol editöre bırak. Üstteki syntax = "proto3"; uygundur ama isteğe bağlı. İç içe message blokları, enum tanımları, oneof, map<K, V> ve alan seçenekleri tamamen ele alınır.

Kotlin kodlama kuralları property’ler için camelCase’i tercih eder — dönüştürücü bunu senin için yapar. Orijinal snake_case adlarını tercih ediyorsan (bazı serileştirme kütüphaneleri alan adlarını birebir eşler), çıktıda bul-değiştir uygula.

Kotlin çıktısını oku

Sağda: her mesaj, her property için varsayılan değerleri olan bir data class’a dönüşür. Her enum, wire formatını gidiş-geliş yapabilmen için enum class(val value: Int)’a dönüşür. Sadece tepe seviye (iç içe değil) — tek dosyaya koymak veya parçalamak kolay.

Projene bağla

Dosyayı projene bırak, bir package bildirimi ekle ve import et. Android veya JVM’de gerçek gRPC kodu için yine de marshal metotları ve stub’ları almak adına grpc-kotlin codegen’ini çalıştırmak isteyeceksin. Bu çıktı; tipli JSON işleme, struct taslakları ve incelemeler içindir.

Gerçekten zaman kazandırdığı durumlar

Backend .proto’dan Android tiplerini taslaklamak

Android uygulaman bir gRPC backend’iyle konuşuyor. .proto backend ekibine ait. Henüz codegen kurmadan view model’lerini tipleyebilmek için data class formlarını istiyorsun. Yapıştır, Models.kt’ye bırak, tiplisin.

JSON ile kodlanmış Protobuf’u parse eden sunucu tarafı Kotlin

Sunucu tarafı Kotlin’in (Ktor / Spring Boot) proto3 JSON kodlamasına uyan JSON tüketiyor. Eşleşen data class’lara ihtiyacın var. .proto’yu yapıştır, Kotlin çıktısını kopyala ve seçtiğin serileştiriciye tak.

Bir Protobuf API değişikliğini incelemek

Bir takım arkadaşı bir mesaja alan ekledi. Yeni .proto’yu yapıştır, Kotlin çıktısını mevcut Models.kt’nle diff’le, tüm toolchain’i ayağa kaldırmadan odaklı bir review bırak.

Tek seferlik script’ler ve hızlı prototipler

Bir gRPC-gateway’e vuran 50 satırlık bir Kotlin script’i. Sırf onun için grpc-kotlin ve protoc kurmak abartı. Data class’ları burada üret, içine bırak.

Sık sorulan sorular

Bu protoc-gen-kotlin’in yerine geçer mi?

Hayır. Gerçek codegen marshal/unmarshal metotlarını, descriptor’ları ve gRPC stub’larını üretir. Bu araç yalnızca data class formlarını verir. Üretim gRPC kodu için grpc-kotlin çalıştır. Bunu taslaklar, JSON parsing, incelemeler ve tek seferlik script’ler için kullan.

Tekil mesaj alanları neden nullable?

proto3’te mesaj tipi alanların "has value" anlamı vardır — atanmamış olabilirler. Bunun en temiz Kotlin karşılığı varsayılanı null olan nullable bir property’dir. Verinin bu alanları her zaman doldurduğunu biliyorsan ?’yi ve varsayılanı kaldır — dümdüz bul-değiştir.

uint32 ve uint64 nasıl ele alınıyor?

İkisi de işaretli tiplere (Int ve Long) eşlenir. Kotlin’in 1.5’ten beri kararlı UInt ve ULong tipleri var, ancak işaretli tipler mevcut serileştirme kütüphaneleri ve çoğu Android kod tabanıyla daha uyumlu. İşaretsiz varyantlara özellikle ihtiyacın varsa çıktıda değiştir.

Enum’lar nasıl üretiliyor?

Her biri, wire formatındaki tamsayıyı koruyabilmen için enum class WithValue(val value: Int)’a dönüşür. Her değer orijinal proto adını alır (örn. ORDER_STATUS_PENDING) — Kotlin enum girişleri zaten gelenek olarak SCREAMING_SNAKE_CASE olduğu için bu uyumludur.

Alan adları nasıl dönüştürülüyor?

Kotlin kodlama kurallarına göre snake_case → camelCase. order_id, orderId’ye; customer_name, customerName’e dönüşür. Sınıf ve enum adları proto’daki gibi PascalCase kalır.

İç içe mesajları ele alıyor mu?

Evet — iç içe message blokları çıktıda tepe seviye data class bildirimlerine düzleştirilir. Bu, dosyayı okuması kolay tutar ve birden fazla dosyaya bölmeyi basitleştirir. Kotlin iç içe sınıfları tercih ediyorsan elle sar.

İlgili araçlar

Protobuf ve Kotlin ile çalışıyorsan bunlar iyi gider:

Protobuf → Kotlin Dönüştürücü