在把 Java 的 List 物件序列化成 JSON 時,若遇到反覆轉換失敗或出現非預期欄位,問題往往出在實體類別的關聯設定上。本文說明最常見的成因與對應的解法。
如果你的專案使用 Hibernate 的自動註解(如 JPA 註解),且實體之間存在「一對多」或「多對一」的關聯,序列化時就很容易出問題。這類關聯通常是雙向的:例如訂單參考官方客戶,客戶又持有訂單清單,兩者互相參照形成循環。JSON 序列化工具在遇到循環參照時,往往會無限遞迴而丟出例外,導致轉換失敗。
最直接的做法,是在那些不需要輸出到 JSON 的欄位上加上 @JsonIgnore 註解。這樣在把 List 轉成 JSON 時,序列化工具就會自動忽略這些被標註的欄位,避免陷入循環參照:
@OneToMany(mappedBy = "customer")
@JsonIgnore
private List<Order> orders;
通常只需要在雙向關聯的其中一側加上 @JsonIgnore,即可打破循環,讓序列化正常完成。
除了 @JsonIgnore,依情境也可採用:
@JsonIgnoreProperties:在類別層級一次忽略多個欄位。
@JsonManagedReference 與 @JsonBackReference:成對使用,明確標示雙向關聯中的正向與反向端。
@JsonIdentityInfo:為物件加上識別資訊,讓序列化工具以 id 取代重複參照,適合需要保留關聯結構的場景。
List 轉 JSON 失敗,多數情況並非序列化工具本身的問題,而是實體關聯設定造成的循環參照。只要在不需要輸出的關聯欄位上標註 @JsonIgnore(或採用成對的參照註解),即可有效解決。理解 Hibernate 關聯與 JSON 序列化的交互作用,是排查這類錯誤的關鍵。