DevTool 團隊

從 JSON 產生 Java 類別:註解、Lombok 與型別推斷的選項怎麼定

介面回傳的 JSON 要變成 Java DTO,手寫欄位加 getter/setter 是最低效的事。這篇講清產生器的選項怎麼按專案定:序列化庫是 Jackson 還是 Gson 決定註解(@JsonProperty vs @SerializedName,用錯庫讀不到),有 Lombok 依賴就開 @Data 省樣板,包裝型別還是基本型別看欄位能否為 null。再講型別推斷的四個盲區——整數一律推 Integer(13 位毫秒時間戳會溢位,手改 Long)、null 與空陣列推成 Object、混合陣列退化成 List<Object>、snake_case 欄位靠註解映射;最後是真話:產生的類別是樣本快照不是契約,API 加欄位要靠 ignoreUnknown 兜底,record 是現代選擇但工具產生的是傳統 POJO。

先定三個選項:按專案現狀選

產生 Java 類別不是「點一下就完」,三個選項決定產生的程式碼能不能直接用。按你專案的現狀定(以本站 JSON 轉 Java 類生成器 為例):

你的專案 選項 為什麼
用 Jackson(Spring Boot 預設) 註解選 Jackson @JsonProperty 欄位名映射與反序列化靠它;選錯庫註解=靜默全 null
用 Gson 註解選 Gson @SerializedName 同上,庫與註解必須配套
有 Lombok 依賴 開 @Data getter/setter/toString/equals 全省,類別體只剩欄位
沒 Lombok 或團隊禁用 關掉,產生顯式 getter/setter 程式碼長但零依賴
欄位可能為 null 包裝型別(Integer/Boolean) 基本型別裝不下 null,反序列化會拋錯
欄位保證有值且追求效能 基本型別(int/boolean) 省裝箱,但遇 null 就炸

類別名、套件名、存取修飾符按團隊規範填;巢狀物件會產生內部類別(或獨立類別),陣列產生 List<T>。

型別推斷規則與四個盲區

產生器只能看你給的那份樣本推斷型別,規則與盲區都要清楚:

JSON 值 推斷的 Java 型別 盲區
"text" String —
true Boolean / boolean —
42 Integer / int 13 位時間戳、雪花 ID 會溢位——手改 Long
3.14 Double / double 金額場景建議手改 BigDecimal
null Object 樣本裡是 null 就推不出真實型別
[] List<Object> 空陣列推不出元素型別
[1, "a"] List<Object> 混合型別退化
{...} 巢狀類別 —

盲區一:整數溢位。 這是產生器最隱蔽的坑——JSON 裡 1730000000000 看起來是個普通整數,推成 Integer 後反序列化直接溢位。規則:超過 10 位的整數一律手改 Long,ID 類欄位尤其如此(很多 API 乾脆用字串傳 ID 規避前端 JS 的 2^53 精度問題,這時推成 String 反而是對的)。

盲區二:null 與空陣列。 推成 Object 的欄位是產生器在說「我不知道」——拿一份欄位都有值、陣列都非空的完整樣本重新產生,或按介面文件手改。上線前過一遍所有 Object 欄位是必要收尾。

盲區三:混合型別陣列。 [1, "a"] 只能是 List<Object>,通常意味著介面設計本身有問題——拿著這個結果去跟介面方確認,比在 Java 側硬處理強。

盲區四:欄位命名。 user_name 轉成 userName 靠註解映射原名;Java 保留字(class、default)會被加後綴避讓——注意改名後的欄位要與註解裡的原名對得上。

註解:庫與註解必須配套

@JsonProperty("user_name") 是 Jackson 的,@SerializedName("user_name") 是 Gson 的——用錯一個,反序列化不報錯,欄位全部 null,這是排查成本最高的一類問題。

三條實踐:

  • 專案用什麼庫就選什麼註解,Spring Boot 預設 Jackson;
  • 整個專案都是 snake_case JSON 時,別每個欄位加註解——在 ObjectMapper 上配全域命名策略(PropertyNamingStrategies.SNAKE_CASE)一處生效;
  • Lombok @Data 與註解可以共存:註解掛在欄位上,Lombok 產生的 getter/setter 不影響序列化庫按欄位註解工作。

真話:產生的類別是快照,不是契約

  • 樣本決定一切:產生器按你貼的那份 JSON 推斷——樣本裡沒出現的欄位它不知道,可選欄位它當必有,null 欄位它推 Object。拿介面文件或多份真實回應對一遍再上線;
  • API 會演進:上游加欄位後,嚴格模式的反序列化會拋 UnrecognizedPropertyException——給類別加 @JsonIgnoreProperties(ignoreUnknown = true) 或配全域 FAIL_ON_UNKNOWN_PROPERTIES=false,讓新欄位靜默忽略而不是把介面打掛;
  • record 是現代選擇:Java 16+ 的 record 不可變、極簡,純資料傳輸很合適;產生器產出的是傳統可變 POJO——團隊用 Java 17+ 且接受不可變風格的,拿產生結果手改成 record 工作量很小;有 Lombok 的,@Data 已經把樣板消掉大半,兩者實際差距不大。

產生器的價值是把「照著 JSON 敲欄位」這件機械活壓到零,欄位型別與演進策略仍然是你的工程判斷。

常見問題

JSON 欄位是 snake_case,Java 欄位要 camelCase,怎麼對上?

靠序列化註解做映射:產生器把 user_name 轉成 Java 欄位 userName,同時在欄位上加 @JsonProperty("user_name")(Jackson)或 @SerializedName("user_name")(Gson),反序列化時庫按註解裡的原名找 JSON 鍵。兩點要注意:註解必須與你專案實際用的庫配套——混用就是靜默全 null;以及整個專案都是 snake_case 時,與其每個欄位加註解,不如在 ObjectMapper 上全域設定命名策略,一處設定全域生效。

為什麼有的欄位被推斷成了 Object?

型別推斷只能看你給的樣本,三種情況推不出具體型別:欄位值是 null、陣列為空、陣列元素型別不一致。這些 Object 欄位是產生器在說「樣本資訊不夠」,不是最終答案——拿一份完整樣本重新產生,或者按介面文件手工改成正確型別。上線前把所有 Object 欄位過一遍,是用產生器的必要收尾。

整數欄位為什麼用 Integer 會出問題?

產生器看到整數一律推成 Integer(或 int),但 Java 的 int 上限是 2,147,483,647——13 位的毫秒時間戳、雪花演算法 ID、大額金額全部超過這個範圍,反序列化時直接溢位或拋錯。判斷方法:JSON 裡的整數超過 10 位就該懷疑,時間戳與 ID 類欄位一律手改 Long。更穩的做法是金額用 BigDecimal、ID 用 Long 或 String。

應該用產生的可變 POJO 還是 Java record?

record(Java 16+)是不可變的資料載體,程式碼極簡且語意清晰,適合純資料傳輸;傳統 POJO 適合需要逐步填充、與老框架相容的場景。產生器產出的是傳統 POJO——拿它當起點,專案是 Java 17+ 且團隊接受不可變風格的,手工改成 record 工作量很小;團隊有 Lombok 的,@Data 已經把樣板消掉大半,兩者差距其實不大。