Java 序列化中的循環引用問題與 JAXB CycleRecoverable 解決方案

問題背景：為什麼會出現循環引用？

在領域模型設計中，雙向關聯極為常見。例如：

• Company 持有 Employee 集合（@OneToMany）
• Employee 持有 Company 參考（@ManyToOne）

當使用 JAXB（或其他序列化引擎）序列化 Company 時，引擎會遞歸遍歷物件圖：

1. 序列化 Company → 發現 employees 欄位
2. 序列化 Employee → 發現 company 欄位
3. 再次遇到同一個 Company 實例 → 循環引用

引擎無法自行判斷何時停止，導致無限遞歸或 StackOverflowError。

實體類別範例

@Entity
public class Company {
    @Id @Column(name = "id")
    private String id;
    
    @OneToMany(mappedBy = "company")
    private List<Employee> employees;
    // getters/setters
}

@Entity
public class Employee {
    @Id @Column(name = "id")
    private String id;
    
    @ManyToOne
    @JoinColumn(name = "company_id")
    private Company company;
    // getters/setters
}

解決方案：實作 CycleRecoverable 介面

JAXB 提供 com.sun.xml.bind.CycleRecoverable 介面，讓開發者在偵測到循環時返回替代物件，打破循環。

修改後的實體類別

import com.sun.xml.bind.CycleRecoverable;
import javax.xml.bind.annotation.*;
import java.util.List;

@Entity
@XmlRootElement
public class Company implements CycleRecoverable {
    @Id @Column(name = "id")
    private String id;
    
    @OneToMany(mappedBy = "company")
    @XmlElementWrapper(name = "employees")
    @XmlElement(name = "employee")
    private List<Employee> employees;
    
    // 關鍵：循環偵測回調
    @Override
    public Object onCycleDetected(Context context) {
        Company stub = new Company();
        stub.setId(this.id); // 僅保留識別資訊
        return stub;
    }
    // getters/setters
}

@Entity
@XmlRootElement
public class Employee implements CycleRecoverable {
    @Id @Column(name = "id")
    private String id;
    
    @ManyToOne
    @JoinColumn(name = "company_id")
    @XmlTransient // 或在循環處理中返回 stub
    private Company company;
    
    @Override
    public Object onCycleDetected(Context context) {
        Employee stub = new Employee();
        stub.setId(this.id);
        return stub;
    }
    // getters/setters
}

運作原理

1. 序列化引擎開始處理 Company，記錄其身份標識。
2. 遍歷至 Employee，再遍歷回 Company。
3. 引擎偵測到同一實例再次出現 → 調用 onCycleDetected(Context)。
4. 方法返回一個新建立的精簡物件，不包含導致循環的關聯欄位。
5. 引擎序列化該精簡物件，遞歸結束。

輸出 XML 範例

<company>
    <id>C001</id>
    <employees>
        <employee>
            <id>E001</id>
            <company>  <!-- 這裡會是精簡 stub -->
                <id>C001</id>
            </company>
        </employee>
    </employees>
</company>

最佳實踐與注意事項

1. 全域實作：建議所有實體類別均實作 CycleRecoverable，因為運行時難以預測哪些關聯會形成循環。
2. Stub 設計：替代物件應僅包含識別屬性（如 id），避免攜帶大量資料或再次觸發循環。
3. 替代方案：
   • @XmlTransient：直接忽略該欄位（簡單但資料遺失）。
   • @XmlID / @XmlIDREF：用 ID 參考替代物件嵌套（標準 JAXB 方式，需配合 XmlAdapter）。
   • 使用 Jackson / Gson 等 JSON 序列化庫，內建 @JsonManagedReference / @JsonBackReference 或 @JsonIdentityInfo 處理循環。
4. 效能考量：onCycleDetected 會建立新物件，大量循環時可能增加 GC 壓力；可考慮快取 Stub 實例。

總結

循環引用是雙向關聯模型的必然產物。JAXB 的 CycleRecoverable 機制提供了標準化、可控的解決路徑：在循環發生時刻攔截，輸出精簡替代物件，保證序列化順利完成且不遺失關鍵識別資訊。掌握此技巧，能讓你在複雜領域模型中游刃有餘地處理 XML/JSON 序列化需求。