Hibernate 配置文件全解析：hibernate.cfg.xml、hibernate.properties、映射文件與加載機制

Hibernate 配置文件體系概覽

Hibernate 核心配置涉及三類文件，優先級遞減：

1. hibernate.properties —— 屬性文件，**最高優先級**，放在 classpath 根目錄
2. hibernate.cfg.xml —— XML 配置，**次優先級**，官方推薦，結構清晰、支援映射文件引用
3. xxx.hbm.xml —— 實體映射文件，定義類與表的對應關係

此外，可通過代碼指定任意配置文件路徑：`new Configuration().configure(file)`

配置文件讀取順序與原理

啟動日誌揭示真相：

1. 尋找 hibernate.properties (未找到)
2. 初始化位元組碼增強器 (cglib)
3. 初始化時間戳服務
4. 讀取 hibernate.cfg.xml
5. 加載映射文件/類

驗證實驗： 將 `hibernate.cfg.xml` 改名為 `.bak`，放置同內容的 `hibernate.properties`，程序正常運行，日誌顯示直接讀取屬性文件。

hibernate.properties 範例

hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.connection.driver_class=com.mysql.jdbc.Driver
hibernate.connection.url=jdbc:mysql://localhost:3306/jdbc
hibernate.connection.username=root
hibernate.connection.password=123123
hibernate.current_session_context_class=thread
hibernate.show_sql=true
hibernate.format_sql=true

注意： 無法在 properties 中引用映射文件，需代碼手動 `addResource()`。

hibernate.cfg.xml 完整範例（推薦）

<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
    "https://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <session-factory>
        <!-- 數據庫連接 -->
        <property name="dialect">org.hibernate.dialect.MySQLDialect</property>
        <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
        <property name="connection.url">jdbc:mysql://localhost:3306/jdbc</property>
        <property name="connection.username">root</property>
        <property name="connection.password">123123</property>

        <!-- 連接池 (內建/外部) -->
        <property name="connection.pool_size">10</property>
        <!-- property name="hibernate.c3p0.min_size">5</property -->

        <!-- 運行行為 -->
        <property name="show_sql">true</property>
        <property name="format_sql">true</property>
        <property name="hbm2ddl.auto">update</property>  <!-- auto/create/update/validate -->
        <property name="current_session_context_class">thread</property>

        <!-- 映射文件引用 -->
        <mapping resource="edu/fjnu/hotelsys/domain/Hotel.hbm.xml"/>
        <mapping resource="edu/fjnu/hotelsys/domain/Room.hbm.xml"/>
        <!-- 亦可掃描包: mapping package="..." -->
    </session-factory>
</hibernate-configuration>

實體映射文件 (xxx.hbm.xml) 詳解

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
    "https://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
<hibernate-mapping package="edu.fjnu.hotelsys.domain">
    <class name="Room" table="room">
        <id name="roomId" column="room_id" type="java.lang.Integer">
            <generator class="increment"/>  <!-- 主鍵生成策略 -->
        </id>
        <property name="roomNo" column="room_no" type="string" length="10" not-null="true"/>
        <property name="roomType" column="room_type" type="string" length="1" not-null="true"/>
        <property name="roomStatus" column="room_status" type="string" length="1" not-null="true"/>
        <property name="roomMemo" column="room_memo" type="string" length="200"/>
        <property name="roomEquipStr" column="room_equip" type="string" length="20"/>
        <many-to-one name="hotel" class="Hotel" column="hotel_no" fetch="join"/>  <!-- 多對一關聯 -->
    </class>
</hibernate-mapping>

關鍵元素：

• ``：主鍵映射，`generator` 支援 `increment`、`identity`、`sequence`、`hilo`、`native`、`assigned`、`uuid` 等
• ``：普通屬性，`column`、`type`、`length`、`not-null`、`unique` 等約束
• ``：多對一關聯，`fetch="join"` 表示迫切左外連接抓取
• ``/``：集合映射，配合 ``/``/`` 使用
• ``：組合對象（值類型）映射

Configuration 與 SessionFactory 構建流程

方式一：標準 XML 配置 (Hibernate 5.x 風格)

public class HibernateUtil {
    private static final SessionFactory sessionFactory = buildSessionFactory();

    private static SessionFactory buildSessionFactory() {
        try {
            StandardServiceRegistry registry = new StandardServiceRegistryBuilder()
                .configure()  // 默認讀取 hibernate.cfg.xml
                .build();
            return new MetadataSources(registry)
                .buildMetadata()
                .buildSessionFactory();
        } catch (Throwable ex) {
            throw new ExceptionInInitializerError(ex);
        }
    }

    public static SessionFactory getSessionFactory() { return sessionFactory; }
    public static void shutdown() { getSessionFactory().close(); }
}

方式二：註解配置 (AnnotationConfiguration，Hibernate 3.x/4.x)

AnnotationConfiguration cfg = new AnnotationConfiguration()
    .configure("hibernate.cfg.xml")
    .addAnnotatedClass(Hotel.class)
    .addAnnotatedClass(Room.class);
SessionFactory sf = cfg.buildSessionFactory();

核心 API 解析

常見配置陷阱與最佳實踐

1. 不要在代碼中頻繁構建 SessionFactory：極其消耗資源，應用啟動時構建一次，靜態持有。
2. 區分 `hbm2ddl.auto` 值：`create` 每次重建表 (測試用)、`update` 自動更新結構 (開發慎用)、`validate` 僅驗證 (生產推薦)、`none` 不操作。
3. 連接池必須外掛：內建池僅供測試，生產強制使用 HikariCP/Druid/C3P0，配置 `hibernate.connection.provider_class`。
4. 映射文件統一管理：使用 `` 或 Spring `LocalSessionFactoryBean` 的 `mapperLocations` 批量掃描，避免手動維護列表。
5. 當前會話上下文：`current_session_context_class=thread` 綁定線程，配合 `getCurrentSession()` 實現 Spring 聲明式事務無縫整合。

Hibernate 配置看似繁雜，實則遵循「約定優於配置」原則。掌握配置加載順序、核心屬性含義、映射元素語義、SessionFactory 生命週期管理，即可駕馭從簡單 CRUD 到複雜關聯查詢的各類持久化場景。