DevTool 團隊

JSON 變 C++ 結構體:選庫、型別推斷與巢狀的真實邊界

介面給的 JSON 要落成 C++ 結構體,先選庫再點產生:多數專案用 nlohmann/json(生態最順),追求解析效能選 RapidJSON,已在 Boost 生態選 Boost.JSON。這篇講清選項怎麼定(C++ 標準、命名風格、命名空間),型別推斷的五個盲區——整數一律推 int(13 位時間戳溢位,手改 int64_t)、null 推成 optional<string>、空陣列預設 vector<string>、混合陣列按首元素推斷、**巢狀物件不展開成子結構體而是 nlohmann::json 動態型別**;最後講 NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE 序列化宏與欄位的綁定關係,以及純 struct 可以直接貼進站內 C++ 線上編譯器跑 main 驗證布局。

先選庫:三個選項按專案定

產生 C++ 結構體的第一個決策不是點按鈕,是選 JSON 庫——它決定產生的程式碼形態(以本站 JSON 轉 C++ 轉換器 為例):

你的專案 選什麼 為什麼
新專案、無特殊效能要求 nlohmann/json(推薦預設) API 最像寫 Python,例外語意清晰,單標頭檔引入,宏生態全
解析效能敏感(高頻大報文) RapidJSON SAX 風格零分配解析快,代價是 API 繁瑣、記憶體自己管
已在 Boost 生態 Boost.JSON 與 Boost.Asio 等協同順,少一個依賴

配套選項:C++ 標準(11/14/17/20,按工程實際——17 起才有 std::optional,選 11 會退化)、命名風格(camelCase/snake_case 跟團隊規範)、命名空間與結構體名按工程填。註解和 getter/setter 可選產生。

型別推斷規則與五個盲區

產生器按樣本推斷型別,規則與盲區都在這張表裡:

JSON 值 推斷的 C++ 型別 盲區
42 int 32 位元上限——13 位時間戳溢位,手改 int64_t
3.14 double 金額別用浮點,定點存分
"text" std::string —
true bool —
null std::optional<std::string> 語意是「不知道型別,按字串兜底」——真實型別可能是數字,按文件改
[] std::vector<std::string> 空陣列推不出元素型別,預設字串——按文件改成真實型別
[1, 2] std::vector<int> 只看首元素——[1, \"a\"] 會推成 vector<int>,混合陣列是介面設計問題
{...} nlohmann::json 動態型別承接,不產生子結構體——見下節

最重要的邊界:巢狀物件不展開成子 struct。 產生器把巢狀物件的欄位型別直接給 nlohmann::json——任何巢狀結構都能兜住、不會推錯,但巢狀欄位失去編譯期型別檢查,存取走 json[\"key\"] 執行時路徑。想要強型別巢狀,把子物件單獨貼進來再產生一次、手動組裝——層級穩定的介面值得,結構多變的回應用動態型別反而省心。

序列化宏:產生程式碼的維護點

選 nlohmann 時會產生 NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(StructName, field1, field2, ...)——這個宏為你的 struct 自動產生 to_json/from_json,struct 與 JSON 互轉就有了。

綁定關係要記牢:宏裡的欄位列表必須與 struct 成員完全一致。三種常見翻車:

  • 加了欄位忘了改宏——序列化靜默漏欄位;
  • 切換命名風格(camelCase→snake_case)——struct 成員變了,宏裡的列表要同步;
  • 欄位改名——宏裡舊名編譯不過,是好事,至少不靜默。

驗證:兩段式

產生的程式碼分兩段,驗證方式不同:

  • 純 struct 段(欄位定義,零依賴的標準 C++):直接貼進 C++ 線上編譯器 跑個 main——列印 sizeof(Struct) 和各欄位,布局、對齊、拼寫一眼驗證;
  • 序列化段(宏 + nlohmann 依賴):本地工程編譯,跑一次往返(struct→json→struct 比對欄位),比肉眼看宏可靠。

真話:產生的 struct 是起點

  • 樣本決定型別:推斷只看你貼的那份 JSON——null 欄位、空陣列、巢狀物件全是「資訊不足」的訊號,拿介面文件或多份真實樣本校一遍再進工程;
  • int 溢位是 C++ 版獨有的坑:Java 至少還有 Long 兜著,C++ 的 int 是 32 位元——ID 與時間戳欄位過一遍是必要收尾;
  • 混合型別陣列回去找介面方:[1, \"a\"] 推成 vector<int> 編譯沒問題、執行時才炸——這類介面本身該修,不是 C++ 側硬扛。

常見問題

為什麼巢狀物件的欄位型別是 nlohmann::json,而不是子結構體?

產生器對巢狀物件的處理是「動態承接」:欄位型別直接給 nlohmann::json,序列化時整個子樹原樣進出——好處是任何巢狀結構都能處理;代價是巢狀欄位失去編譯期型別檢查。想要強型別的巢狀子結構體,把子物件單獨貼進來再產生一次、手動組裝——對層級穩定的介面值得,對結構多變的回應動態型別反而省心。

13 位時間戳這樣的整數欄位怎麼辦?

產生器看到整數一律推成 int——C++ 的 int 通常是 32 位元,上限約 21.4 億,13 位毫秒時間戳、雪花 ID 全部溢位。規則:JSON 裡超過 10 位的整數一律手改成 int64_t。順手檢查相鄰欄位——created_at 和 updated_at 通常是同一種型別。金額欄位同理別用 double,定點存分比浮點穩。

產生的 struct 怎麼快速驗證對不對?

純 struct 部分是標準 C++、零依賴——直接貼進線上 C++ 編譯器跑一個 main,列印 sizeof 和各欄位的值,布局、對齊、欄位名拼寫一眼驗證。帶 NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE 宏的完整程式碼依賴 nlohmann 標頭檔,本地工程編譯跑一次序列化往返比對最實在。

NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE 宏是什麼,改欄位時要動哪裡?

它是 nlohmann/json 提供的宏,為你的 struct 自動產生 to_json/from_json 轉換函式——只需在宏裡列出欄位名。NON_INTRUSIVE 指不侵入 struct 定義。關鍵綁定關係:宏裡的欄位名列表必須與 struct 成員完全一致——加了欄位不改宏會靜默漏欄位;切換命名風格後宏裡的舊名字也要同步。