Hibernate 一對多雙向關聯：StackOverflowError 根因與解決方案

開發者實作 Department(一) ↔ Employee(多) 雙向關聯，保存正常但讀取拋出 StackOverflowError，錯誤堆疊指向 Employee.toString() 循環調用。本文深度解析循環引用成因與多種解決方案。

錯誤堆疊核心訊息

java.lang.StackOverflowError
    at org.xxf.OneToManyA.Employee.toString(Employee.java:13)
    at java.util.AbstractCollection.toString(AbstractCollection.java:422)
    at org.hibernate.collection.internal.PersistentSet.toString(PersistentSet.java:327)
    // 無限循環...

根因分析：雙向關聯 + toString() = 死循環

實體類關係

// Department 端
@OneToMany(mappedBy = "department")
private Set employees = new HashSet<>();

// Employee 端
@ManyToOne
@JoinColumn(name = "department_id")
private Department department;

toString() 觸發循環

// Employee.java 第 13 行附近
@Override
public String toString() {
    return "Employee{id=" + id + ", name='" + name + 
           ", department=" + department + "}"; // ← 這裡!
}

// Department.toString() 同理包含 employees 集合
// 呼叫鏈：Employee.toString() → Department.toString() → 
// Set.toString() → Employee.toString() → ... 無限遞迴

五大解決方案 (按推薦度排序)

方案一：移除關聯欄位的 toString() — 最簡單、最徹底 ✅

// Employee
@Override
public String toString() {
    return "Employee{id=" + id + ", name='" + name + "'}"; // 移除 department
}

// Department
@Override
public String toString() {
    return "Department{id=" + id + ", name='" + name + "'}"; // 移除 employees
}

• 優點：零配置、零依賴、效能最好、完全避免循環
• 缺點：除錯時看不到關聯資訊

方案二：使用 Lombok @ToString.Exclude — 現代專案首選 ✅

@Data
@Entity
public class Employee {
    @Id @GeneratedValue
    private Integer id;
    private String name;
    
    @ManyToOne
    @JoinColumn(name = "department_id")
    @ToString.Exclude  // ← 關鍵註解
    private Department department;
}

@Data
@Entity
public class Department {
    @Id @GeneratedValue
    private Integer id;
    private String name;
    
    @OneToMany(mappedBy = "department")
    @ToString.Exclude  // ← 雙向都排除
    private Set employees = new HashSet<>();
}

• 優點：編譯期處理、程式碼乾淨、保留其他欄位 toString
• 缺點：需引入 Lombok

方案三：手寫 toString 排除關聯 — 不用 Lombok 時的標準做法

// Employee
@Override
public String toString() {
    return "Employee{id=" + id + ", name='" + name + 
           ", departmentId=" + (department != null ? department.getId() : null) + "}";
}

// Department
@Override
public String toString() {
    return "Department{id=" + id + ", name='" + name + 
           ", employeeCount=" + (employees != null ? employees.size() : 0) + "}";
}

• 優點：無依賴、可控制輸出格式、可顯示關聯 ID/計數
• 缺點：樣板代碼多、維護成本高

方案四：使用 @JsonIgnore / @JsonManagedReference/@JsonBackReference (JSON 序列化層面)

// 僅解決 JSON 序列化循環，不解決 toString() 循環
@JsonManagedReference
@OneToMany(mappedBy = "department")
private Set employees;

@JsonBackReference
@ManyToOne
private Department department;

• 注意：這是 Jackson 序列化註解，**不影響** toString() 循環

方案五：Hibernate 初始化策略調整 (治標不治本)

• 設定 @OneToMany(fetch = FetchType.LAZY) (預設即為 LAZY)
• 避免在 toString()/equals()/hashCode() 中觸發關聯載入
• 本質上仍需配合方案 1-3 解決 toString 循環

最佳實踐總結表

延伸：equals()/hashCode() 同樣危險

// ❌ 危險：若包含關聯物件，同樣會循環
@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof Employee)) return false;
    Employee that = (Employee) o;
    return Objects.equals(id, that.id) && 
           Objects.equals(department, that.department); // 循環!
}

// ✅ 安全：僅用主鍵或業務鍵
@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof Employee)) return false;
    Employee that = (Employee) o;
    return Objects.equals(id, that.id); // 僅比較 ID
}

@Override
public int hashCode() {
    return Objects.hash(id);
}

總結

StackOverflowError 在 Hibernate 雙向關聯中極常見，根因是 toString() (或 equals()/hashCode()) 觸發雙向導航循環。**核心原則：實體類的 toString/equals/hashCode 絕不包含關聯物件**。現代專案首選 Lombok @ToString.Exclude，傳統專案手寫排除關聯欄位，徹底從源頭斷開循環鏈。