先定三個選項:按專案現狀選
產生 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 已經把樣板消掉大半,兩者差距其實不大。