Hibernate 核心依賴包深度解析：23 個 JAR 包作用、必選與可選分類指南

Hibernate 發布包含 20+ JAR 文件，初學者易混淆。本文基於 Hibernate 3.x/4.x/5.x 經典依賴結構，深度解析每個包的作用、依賴關係、必選與可選分類、版本衝突排查與現代 Maven/Gradle 依賴管理最佳實踐。

核心必選包 (項目運行不可或缺)

字節碼操作與代理 (核心必選)

連接池 (四選一，生產必選其一)

原則：EJB 容器環境必須使用容器管理 DataSource (JNDI)，不可自行配置連接池，否則事務管理失效。

快取提供者 (二級快取/查詢快取可選其一)

資料庫方言與 JDBC 驅動 (按需引入)

• MySQL: `mysql:mysql-connector-j:8.0.33` (8.0+) / `mysql:mysql-connector-java:5.1.49` (5.x)
• PostgreSQL: `org.postgresql:postgresql:42.7.0`
• Oracle: `com.oracle.database.jdbc:ojdbc11:23.4.0.0` (JDK 11+)
• SQL Server: `com.microsoft.sqlserver:mssql-jdbc:12.4.1.jre11`
• H2 (測試): `com.h2database:h2:2.2.224`

工具與測試依賴 (compile/test scope 區分)

依賴衝突排查與最佳實踐

常見衝突場景

• 多版本 SLF4J 綁定：`slf4j-log4j12` + `logback-classic` + `log4j-slf4j-impl` → 保留一個綁定
• JPA API 版本不匹配：`hibernate-jpa-2.1-api` vs `jakarta.persistence-api` → 統一 Jakarta EE 9+ (jakarta.*)
• Byte Buddy / ASM 版本衝突：Spring、Hibernate、Mockito 可能引入不同版本 → 依賴管理統一版本
• Dom4j 1.x vs 2.x：包名變更 (`dom4j` → `org.dom4j`)，不可共存

Maven 依賴管理模板

    
        
        
            org.hibernate
            hibernate-bom
            5.6.15.Final
            pom
            import
        
        
        
            com.zaxxer
            HikariCP
            5.0.1
        
        
        
            org.ehcache
            ehcache
            3.10.8
        
    



    
    
        org.hibernate
        hibernate-core
    
    
    
    
        com.zaxxer
        HikariCP
    
    
    
    
        org.ehcache
        ehcache
    
    
    
    
        com.oracle.database.jdbc
        ojdbc11
        runtime
    

Gradle 依賴管理

dependencies {
    // Hibernate BOM
    implementation platform("org.hibernate:hibernate-bom:5.6.15.Final")
    
    // 核心
    implementation "org.hibernate:hibernate-core"
    
    // 連接池
    implementation "com.zaxxer:HikariCP"
    
    // 快取 (可選)
    implementation "org.ehcache:ehcache"
    
    // 資料庫驅動
    runtimeOnly "com.oracle.database.jdbc:ojdbc11"
    
    // 測試
    testImplementation "org.junit.jupiter:junit-jupiter"
    testImplementation "org.mockito:mockito-core"
    testImplementation "org.testcontainers:testcontainers"
}

版本演進關鍵節點

總結

1. 核心必選：`hibernate-core` + 連接池 (HikariCP 首選) + 資料庫驅動
2. 功能可選：快取 (Ehcache/Infinispan)、審計 (Envers)、驗證 (Validator)、JPA (自動傳遞)
3. 版本統一：使用 BOM/Platform 管理傳遞依賴版本，避免鑽石依賴衝突
4. Scope 正確：驅動 `runtime`、測試 `test`、編譯期註解處理器 `annotationProcessor`
5. 現代化：Hibernate 6+、Jakarta EE 9+、Java 11+、Byte Buddy、HikariCP、JCache 標準快取

理解依賴圖譜，才能構建精簡、穩定、可維護的持久層工程。