Giriş (.proto şeması)

Çıktı (doğrulama raporu)

Bu araç ne yapar

Bir Protocol Buffers dosyasını kaydediyorsunuz, protoc ya da buf çalıştırıyorsunuz, ve build anlaşılmaz bir satır/sütun hatasıyla ölüyor. Bu doğrulayıcı, sıkı bir derleyicinin uyguladığı kurallarla .proto’nuzu parse eder ve nerede ne yanlış, onu sade bir dille söyler — siz commit etmeden ve CI pipeline’ı sizin için yakalamadan önce.

"Parse oldu mu" sorusunun ötesinde, araç spec’in gerçekten zorunlu kıldığı kontrolleri lint adımı olarak çalıştırır: alan numaraları 1..536870911 aralığında olmalı, 19000..19999 aralığı Google tarafından dahili olarak ayrılmış, bir message içindeki her alan numarası benzersiz olmalı ve alan adları tekrar etmemeli. Gerçek build başarısızlıklarını üreten ihlaller bunlardır ve doğrulayıcı, derleyicinin yaptığı gibi hata-hata değil, hepsini tek seferde yüzeye çıkarır.

Her şey tarayıcınızda çalışır — .proto’nuz, message adlarınız, package yollarınız makinenizden hiç çıkmaz. Parser; syntax/package/import direktiflerini, satır ve blok yorumlarını, iç içe message ve enum bloklarını, oneof, map<K, V>, repeated, optional, servisleri (atlanır) ve alan opsiyonlarını işler. Resmi proto3 dil rehberiyle aynı iş akışı için tasarlanmıştır.

Nasıl kullanılır

Üç adım, siz yazarken çalışır. Çıktı editörü, yazmayı bıraktıktan ~300 ms sonra güncellenir.

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

Şemayı sol editöre bırakın — tek dosya, uzunluğu fark etmez. En üstteki syntax = "proto3"; olabilir ama opsiyonel. Parser import ifadelerini tanır ama atlar — dosyalar arası çözümleme buranın kapsamı dışında, doğrulanmasını istediğiniz import edilen message’ları aynı girdiye satır içi yapıştırın. Tüm yorumlar parse edilmeden önce kaldırılır.

Editörünüz yapıştırırken akıllı tırnak karakterleri ekliyorsa, doğrulayıcı tokenizasyon hatası bildirebilir. Onları kaldırın ya da düz metin kaynaktan yapıştırın.

Raporu okuyun

Sağda: şema temizse yeşil bir tik, değilse sorunların listesi. Her sorun tam olarak hangi message ve hangi alan olduğunu gösterir, böylece grep’e gerek kalmadan editörünüzde düzeltirsiniz. Rapor ayrıca message sayısını, enum sayısını ve toplam alan sayısını da özetler.

Düzeltin ve yeniden yapıştırın

Düzeltmeyi editörünüzde uygulayın, güncellenmiş şemayı yapıştırın. Çıktı bir saniyenin altında yeniden doğrulanır. Yeniden yükleme yok, yeniden derleme yok, CI’nın kırmızı dönmesini beklemek yok. Şema temizlendiğinde, doğrulamanın bir kaydını tutmak isterseniz raporu PR yorumuna kopyalayabilirsiniz.

Bunun gerçekten zaman kazandırdığı yerler

CI’a push’lamadan önce hataları yakalamak

Ekibiniz CI’da buf lint çalıştırıyor. Önce yerelde doğrulamak; push at, bekle, kırmızı gör, düzelt, tekrar push at döngüsünden kurtulmak demek — tüm döngü tek bir tarayıcı sekmesine çöker.

Bir arkadaşın Protobuf PR’ını review etmek

Bir takım arkadaşının şema değişikliğini review ediyorsunuz ama yerelde protoc toolchain’i kurulu değil. Yeni .proto’yu buraya yapıştırın, yapısal olarak temiz mi bakın ve "iyi görünüyor, gönder" yerine odaklı bir review bırakın.

proto2’den proto3’e geçiş

Eski şemalar sıklıkla required kullanır (proto3’te yok) ya da kontrol edene kadar uygun görünen alan numaralarına sahiptir. Doğrulayıcı, tekrarları ve aralık dışı numaraları tek seferde işaretler; bu, 800 satırlık bir .proto’yu elle okumaktan çok daha hızlıdır.

Bir code-gen aracından üretilmiş .proto’yu doğrulamak

Üreteçler (örn. JSON Schema → Protobuf, OpenAPI → Protobuf) bazen sınır durum hatalı şemalar üretir — tekrarlayan alan numaraları, ayrılmış aralığa düşen değerler. Çıktıya güvenmeden önce doğrulayıcıdan geçirin.

Sık sorulan sorular

.proto şemam bir sunucuya gönderiliyor mu?

Hayır. Parser ve lint kontrolleri tamamen tarayıcınızda JavaScript olarak çalışır. DevTools’u açıp yapıştırırken Network sekmesini izleyin — sıfır istek. İç tip adlarını, package yollarını ya da üçüncü taraf bir doğrulayıcıya göndermek istemeyeceğiniz şeyleri içeren şemalar için kullanışlıdır.

Lint adımı tam olarak hangi kontrolleri yapar?

Alan numaraları 1..536870911 aralığında olmalı (Google tarafından ayrılmış 19000..19999 aralığı hariç), bir message içindeki her alan numarası benzersiz olmalı ve bir message içindeki her alan adı benzersiz olmalı. Bu kuralların herhangi birinde takılan her şey, tam message.field yolu ile birlikte raporlanır. Parse adımı ayrıca eksik noktalı virgül, eşlenmemiş süslü parantezler, beklenmeyen tokenlar vb. üzerinde de başarısız olur.

Proto3 spec’ine göre mi yoksa proto2’ye göre mi doğruluyor?

Her iki sözdizimini de kabul eder (proto3 default-zero, proto2 required/optional niteleyicileri vb.). Lint kontrolleri spec ile tanımlanmıştır ve her ikisine de uygulanır. "proto3’te required olmaz" gibi en katı kontroller burada zorlanmaz — onları zaten protoc’un kendisi yakalar.

Alan numaram 19000 neden işaretleniyor?

19000..19999 aralığı, Google tarafından Protocol Buffers uygulama kullanımı için dahili olarak ayrılmıştır. Bu aralıkta bir alan numarası atadığınızda gerçek protoc şemayı reddeder. Doğrulayıcı bunu erken yakalar; böylece kafa karıştıran bir build hatasından değil, bu araçtan öğrenirsiniz.

Import’ları takip ediyor mu?

Hayır. import ifadeleri tanınır ama atlanır — başka dosyalardaki message tipleri "unknown" olarak çözülür ve doğrulanmaz. Import edilen tiplere bağlı bir message’ı doğrulamanız gerekirse, import edilen message’ları aynı girdiye yapıştırın.

Ne kadar büyük bir şemayı kaldırabiliyor?

On binlerce satır rahatlıkla. Doğrulama yerel; upload yok, rate limit yok, ağ gidiş-geliş yok — isterseniz repo’nun tamamını yapıştırın, sınır tarayıcınızın belleği.

İlgili araçlar

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

Protobuf Doğrulayıcı