JSON轉Protobuf轉換器

把 JSON 樣本整理成 .proto 訊息草稿

這項工具讀取 JSON 物件，或以物件為元素的陣列，依樣本值輸出 Protocol Buffers 的訊息定義文字（.proto）。它產生的是描述欄位、型別與編號的結構草稿，不是將 JSON 內容編碼成 Protobuf 二進位資料；要產生程式碼或序列化訊息，仍須在專案中使用相應的 Protobuf 工具鏈。

可設定根訊息名稱、選填的 package、proto2／proto3 語法，以及是否將欄位名稱轉成 snake_case。布林值對應 bool；整數值依 JavaScript 可讀取的數值及 32 位範圍推為 int32 或 int64；含小數的數值對應 double；文字對應 string。巢狀物件會成為另一個 message，陣列則成為 repeated 欄位。這些對應只依輸入樣本，不代表工具知道欄位的業務含義。

讀懂訊息、欄位與編號

在 .proto 中，message 是一種資料結構宣告；每個欄位有名稱、型別及欄位編號。repeated 表示欄位可包含多個同類值。輸出會依欄位在樣本中的出現順序，從 1 開始編號；巢狀 message 也會各自編號。Protobuf 官方 proto3 指南說明欄位編號須在同一訊息內唯一，訊息投入使用後不應任意更改或重用；因此自動編號適合起草，不足以代替既有協定的編號管理。

從樣本到可檢查的結構

1. 貼上代表性 JSON

   輸入合法的 JSON 物件，或首項為物件的陣列。盡量選擇欄位較完整的樣本；若是陣列，後續紀錄不會併入推斷。

2. 設定檔案選項

   填寫根訊息名稱，可留白 package，選 proto2 或 proto3，並決定欄位名是否轉為 snake_case。轉換會隨設定更新。

3. 檢查並複製輸出

   查看 .proto 文字，確認訊息名稱、巢狀結構、型別、欄位名及編號，再使用複製功能帶入專案。若 JSON 語法錯誤，先依解析錯誤修正輸入；若根值不是物件或物件陣列，工具無法建立結構。

4. 在專案工具鏈驗證

   依專案的 Protobuf 版本與規範修改草稿，使用編譯器檢查語法，並用多筆真實形狀的測試資料核對序列化與相容性。

輸出與輸入邊界問答

正式採用前的人工檢核

樣本不能揭示欄位是否必填、可否缺省、完整數值範圍、列舉選項或未來版本的結構。含小數的 JSON 數值會經一般 JavaScript 數字解析；若整數識別碼可能超出可精確表示範圍，請勿將其當數字樣本，改以字串保留原值並依協定決定型別。工具未替你校驗完整 schema、產生二進位資料或判定版本相容。

欄位編號按目前鍵的出現順序自動從 1 遞增，不能直接沿用於既有正式訊息；已發布欄位的編號與名稱需按團隊協定謹慎管理。欄位名稱轉換、重複訊息名稱、空值占位及 proto2／proto3 語法也都應在目標編譯器中確認。正式資料模型請用完整樣本集、既有 schema 與相容性檢查共同審核。