Hibernate 二級緩存配置異常：XML 元素順序錯誤導致 MappingException 解決方案

異常現場還原

在配置 hibernate.cfg.xml 啟用二級緩存時，啟動專案拋出 org.hibernate.MappingException: invalid configuration，根因為 org.xml.sax.SAXParseException：The content of element type "session-factory" must match "(property*,mapping*,(class-cache|collection-cache)*,event*,listener*)"。

核心原因分析

Hibernate 的 DTD 強制規定 <session-factory> 內部子元素必須嚴格遵循順序：

1. <property> — 資料庫連線、方言等屬性配置（最前）
2. <mapping> — 實體映射檔或類別引用
3. <class-cache> / <collection-cache> — 二級緩存策略宣告
4. <event> — 事件監聽器註冊
5. <listener> — 實體生命週期監聽器（最後）

常見錯誤是將 <mapping> 置於 <property> 之前，或將緩存配置放在映射之後，導致 XML 驗證失敗。

正確配置範例

<session-factory>
  <!-- 1. 所有 property 必須在最前 -->
  <property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property>
  <property name="hibernate.cache.use_second_level_cache">true</property>
  <property name="hibernate.cache.region.factory_class">org.hibernate.cache.ehcache.EhCacheRegionFactory</property>

  <!-- 2. mapping 緊隨其後 -->
  <mapping resource="com/example/User.hbm.xml"/>
  <mapping class="com.example.Product"/>

  <!-- 3. 緩存策略配置 -->
  <class-cache name="com.example.User" usage="read-write"/>
  <collection-cache collection="com.example.User.orders" usage="read-only"/>

  <!-- 4. 事件與監聽器 -->
  <event type="pre-load"><listener class="com.example.MyPreLoadListener"/></event>
  <listener class="com.example.MyEntityListener"/>
</session-factory>

避坑指南

• 編寫配置時嚴格對照 DTD 順序，切勿隨意調整元素位置。
• 使用 IDE 的 XML 驗證功能（關聯 DTD/XSD）可提前發現順序錯誤。
• 升級 Hibernate 版本時注意 DTD 變更，查閱官方 Migration Guide。