Hibernate 雙向多對多關聯映射最佳實踐：基於主鍵關聯表、級聯策略與性能優化全解析

Hibernate 雙向多對多關聯映射最佳實踐

多對多關聯是領域建模常見模式，Hibernate 通過中間關聯表實現。本文深度解析基於主鍵的雙向多對多映射：實體設計、映射配置、級聯策略、關係維護邏輯、N+1 問題優化、JPQL/HQL 查詢模式，並對比單向與雙向的工程選型建議。

一、領域模型設計

實體定義

@Entity
@Table(name = "t_role")
public class Role {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false, unique = true, length = 50)
    private String name;
    
    // 雙向多對多：Role 為關係維護端
    @ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
    @JoinTable(
        name = "t_role_function",           // 關聯表名
        joinColumns = @JoinColumn(name = "role_id"),      // 本端外鍵
        inverseJoinColumns = @JoinColumn(name = "function_id") // 対端外鍵
    )
    private Set functions = new HashSet<>();
    
    // 業務輔助方法（關鍵：保證雙向一致性）
    public void addFunction(Function function) {
        this.functions.add(function);
        function.getRoles().add(this);
    }
    
    public void removeFunction(Function function) {
        this.functions.remove(function);
        function.getRoles().remove(this);
    }
    // getter/setter 省略
}

@Entity
@Table(name = "t_function")
public class Function {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false, length = 100)
    private String name;
    
    @Column(length = 50)
    private String code;
    
    @Column(length = 200)
    private String url;
    
    // 非維護端：mappedBy 指向對端屬性名
    @ManyToMany(mappedBy = "functions")
    private Set roles = new HashSet<>();
    // getter/setter 省略
}

關鍵註解解析

二、XML 映射配置對比（舊項目維護）

<!-- Role.hbm.xml -->
<class name="Role" table="t_role">
    <id name="id"><generator class="native"/></id>
    <property name="name" column="name"/>
    <set name="functions" table="t_role_function" cascade="save-update">
        <key column="role_id"/>
        <many-to-many class="Function" column="function_id"/>
    </set>
</class>

<!-- Function.hbm.xml -->
<class name="Function" table="t_function">
    <id name="id"><generator class="native"/></id>
    <property name="name"/><property name="code"/><property name="url"/>
    <set name="roles" table="t_role_function" inverse="true">
        <key column="function_id"/>
        <many-to-many class="Role" column="role_id"/>
    </set>
</class>

關鍵差異： 非維護端必須設置 inverse="true"（XML）或 mappedBy（註解），否則雙方都會維護關聯表導致重複 INSERT/DELETE。

三、關係維護邏輯與陷阱

正確操作模式

@Transactional
public void assignFunctions(Long roleId, List functionIds) {
    Role role = roleRepository.findById(roleId).orElseThrow();
    Set functions = new HashSet<>(functionRepository.findAllById(functionIds));
    
    // 清空舊關係（觸發 DELETE 中間表記錄）
    role.getFunctions().clear();
    
    // 建立新關係（雙向綁定）
    for (Function f : functions) {
        role.addFunction(f);  // 內部自動維護反向
    }
    
    roleRepository.save(role);  // 級聯 MERGE 持久化
}

常見錯誤

1. 單向綁定： 只設置 `role.getFunctions().add(f)`，忘記 `f.getRoles().add(role)`，導致內存中對象圖不一致
2. 級聯 REMOVE 災難： `cascade = CascadeType.REMOVE` 會刪除關聯的 Function 實體！多對多絕對禁止 REMOVE/ALL 級聯
3. 直接操作中間表： 繞過實體關係直接操作關聯表，破壞一級緩存一致性

四、查詢優化：解決 N+1 問題

問題場景

List roles = roleRepository.findAll(); // 1 查詢
for (Role r : roles) {
    r.getFunctions().size(); // 每個 Role 觸發 1 查詢 → N+1
}

解決方案對比

推薦配置

@Entity
@BatchSize(size = 20)  // 類級別批量抓取
public class Role {
    @ManyToMany
    @BatchSize(size = 20)  // 集合級別
    @JoinTable(...)
    private Set functions;
}

五、進階查詢模式

反向查詢：擁有某功能的所有角色

// JPQL
@Query("SELECT r FROM Role r JOIN r.functions f WHERE f.id = :functionId")
List findRolesByFunctionId(@Param("functionId") Long functionId);

// Criteria API
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery cq = cb.createQuery(Role.class);
Root root = cq.from(Role.class);
root.join("functions").get("id").in(functionIds);

統計查詢：角色擁有功能數量

@Query("SELECT r.name, COUNT(f) FROM Role r LEFT JOIN r.functions f GROUP BY r.id, r.name")
List countFunctionsPerRole();

六、性能優化清單

1. 集合類型選擇： Set 避免重複、@OrderColumn 需要順序時用 List
2. 關聯表索引： 為 role_id、function_id 建立聯合唯一索引 UK_ROLE_FUNC (role_id, function_id)
3. 批量操作： 大量關聯變更時，考慮原生 SQL 批量 INSERT/DELETE 中間表，再 evict 緩存
4. 只讀場景： 查詢不需修改關係時，使用 DTO 投影避免加載集合
5. 緩存策略： 二級緩存緩存關聯集合需謹慎，@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)

七、遷移指南：從雙向改為單向

若業務僅單向導航（如只需「角色→功能」，無「功能→角色」），移除 mappedBy 端集合，簡化模型：

// Role 保持不變
// Function 移除 roles 集合及 @ManyToMany

// 查詢反向關係改用 JPQL
@Query("SELECT f FROM Function f JOIN f.roles r WHERE r.id = :roleId")
List findFunctionsByRoleId(@Param("roleId") Long roleId);

優勢：減少實體耦合、避免雙向維護 Bug、降低內存佔用。

八、測試驗證用例

@DataJpaTest
class RoleFunctionMappingTest {
    
    @Autowired TestEntityManager em;
    
    @Test
    void testBidirectionalConsistency() {
        Role admin = new Role(); admin.setName("ADMIN");
        Function userMgmt = new Function(); userMgmt.setName("用戶管理");
        
        admin.addFunction(userMgmt);
        em.persist(admin);
        em.flush();
        em.clear();
        
        Role loaded = em.find(Role.class, admin.getId());
        assertThat(loaded.getFunctions()).hasSize(1);
        
        Function loadedFunc = em.find(Function.class, userMgmt.getId());
        assertThat(loadedFunc.getRoles()).hasSize(1);
        assertThat(loadedFunc.getRoles().iterator().next().getId()).isEqualTo(admin.getId());
    }
    
    @Test
    void testCascadePersist() {
        Role role = new Role(); role.setName("GUEST");
        Function f1 = new Function(); f1.setName("查看");
        Function f2 = new Function(); f2.setName("導出");
        
        role.addFunction(f1);
        role.addFunction(f2);
        
        em.persist(role);  // 級聯持久化 f1, f2
        em.flush();
        
        assertThat(em.find(Function.class, f1.getId())).isNotNull();
    }
}

九、總結：工程選型決策樹

1. 是否需要雙向導航？否 → 單向 @ManyToMany
2. 關聯屬性是否需額外字段（如分配時間、分配人）？是 → 拆解為兩個 @OneToMany + 中間實體
3. 關聯數據量大（>1000）？是 → 單向 + JPQL 反向查詢 + @BatchSize
4. 頻繁整體替換關係？是 → clear() + 重建，配合批量 SQL 優化