Hibernate 核心配置文件詳解：hibernate.cfg.xml 與映射文件實戰範本

Hibernate 核心配置文件詳解：hibernate.cfg.xml 與映射文件實戰範本

Hibernate 配置分為主配置文件 (資料庫連線、方言、緩存策略) 與映射文件 (實體類與資料表對應關係) 兩大部分。本文提供生產環境可用的標準範本並逐項解析關鍵屬性。

一、主配置文件 (hibernate.cfg.xml)

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
    "https://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <session-factory>
        <!-- 1. 資料庫連線基本配置 -->
        <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
        <property name="connection.url">jdbc:mysql://localhost:3306/hibernatedb?useSSL=false&serverTimezone=UTC</property>
        <property name="connection.username">root</property>
        <property name="connection.password">123456</property>

        <!-- 2. 連線池配置 (建議生產環境換用 HikariCP/Druid) -->
        <property name="connection.pool_size">10</property>

        <!-- 3. SQL 方言 (自動適配目標資料庫語法) -->
        <property name="dialect">org.hibernate.dialect.MySQL5InnoDBDialect</property>

        <!-- 4. 顯示 SQL (開發階段開啟，生產關閉) -->
        <property name="show_sql">true</property>
        <property name="format_sql">true</property>

        <!-- 5. DDL 自動策略 -->
        <property name="hbm2ddl.auto">update</property>
        <!-- validate: 僅驗證 | update: 自動更新 | create: 重建 | create-drop: 重建後刪除 -->

        <!-- 6. 二級緩存與查詢緩存 (按需啟用) -->
        <property name="cache.use_second_level_cache">true</property>
        <property name="cache.use_query_cache">true</property>
        <property name="hibernate.cache.region.factory_class">org.hibernate.cache.ehcache.EhCacheRegionFactory</property>

        <!-- 7. 當前 Session 上下文綁定 (ThreadLocal 模式) -->
        <property name="current_session_context_class">thread</property>

        <!-- 8. 載入映射文件 -->
        <mapping resource="hib/po/User.hbm.xml" />
    </session-factory>
</hibernate-configuration>

關鍵屬性速查表

二、映射文件 (User.hbm.xml)

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
    "https://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">
<hibernate-mapping package="hib.po">
    <class name="User" table="t_user" schema="hibernatedb">
        <!-- 主鍵映射 -->
        <id name="userId" column="user_id">
            <generator class="native"/> <!-- MySQL 自增、Oracle Sequence 自動適配 -->
        </id>

        <!-- 普通屬性映射 -->
        <property name="username" column="username"/>
        <property name="password" column="password"/>
        <property name="sex" column="sex"/>
        <property name="birthday" column="birthday" type="date"/>
        <property name="salary" column="salary"/>

        <!-- 關聯映射範例 (多對一) -->
        <many-to-one name="department" column="dept_id" class="Department" fetch="select"/>

        <!-- 集合映射範例 (一對多) -->
        <set name="roles" table="user_role" inverse="true" cascade="save-update">
            <key column="user_id"/>
            <many-to-many class="Role" column="role_id"/>
        </set>
    </class>

    <!-- 命名查詢 (HQL) -->
    <query name="findOrder">
        <![CDATA[ from User order by salary asc, sex asc ]]>
    </query>
</hibernate-mapping>

映射核心要素說明

• <id>：主鍵策略 native (身份列/序列自適應)、uuid (UUID 字串)、assigned (手動指派)。
• <property>：type 屬性可指定 Hibernate Type (如 date, timestamp, text)，預設自動推斷。
• <many-to-one>：多對一關聯，fetch="select" (預設延遲載入) / fetch="join" (急迫左連接)。
• <set>/<list>/<bag>：集合映射，inverse="true" 由關係維護端負責外鍵更新，cascade 定義級聯操作。
• CDATA 區塊：命名查詢中包含特殊字元 (<, >, &) 時必須包裹在 <![CDATA[ ... ]]>。

三、現代替代方案：JPA 註解零配置

新專案建議使用 @Entity, @Table, @Id, @Column, @OneToMany 等 JPA 註解完全替代 XML 映射，配合 LocalContainerEntityManagerFactoryBean 啟動，僅保留 persistence.xml 或 Spring Data JPA 配置，維護性更佳。

常見坑點提醒

1. hbm2ddl.auto=create 生產環境嚴禁使用，會導致資料清空。
2. MySQL 8.0+ 需在 URL 加 ?useSSL=false&serverTimezone=UTC 避免時區與 SSL 警告。
3. 映射文件放置路徑需在 Classpath 根目錄對應包結構下 (如 resources/hib/po/User.hbm.xml)。
4. show_sql=true 僅印到標準輸出，生產環境請配合 log4j2 記錄 org.hibernate.SQL 與 org.hibernate.type.descriptor.sql.BasicBinder 以查看參數綁定值。