Hibernate映射文件打包JAR後JUnit測試失效：映射資源加載路徑配置避坑指南

問題背景與現象

將 Hibernate 實體類與映射文件（.hbm.xml）抽取打包為獨立 JAR（model-core.jar），引入多模組項目。主應用啟動正常，但 JUnit 單元測試報錯：

org.hibernate.hql.ast.QuerySyntaxException: Fsettlement is not mapped
[select f from Fsettlement f where ...]

明確提示「實體未映射」，說明 SessionFactory 未正確加載 JAR 內的映射文件。

配置演進與試錯記錄

初始配置（失效）

<property name="mappingJarLocations">
    <list><value>WEB-INF/lib/model-core*.jar</value></list>
</property>

Spring 啟動上下文時無法解析 WEB-INF/lib/ 相對路徑（非 Web 環境）。

嘗試 mappingLocations 通配符（多數失效）

根因深度分析

1. ClassLoader 差異：主應用運行於 Web 容器（Tomcat），擁有 WebAppClassLoader 可掃描 WEB-INF/lib/；JUnit 運行於標準 Java 應用上下文，ClassPath 僅包含 target/classes、target/test-classes 及 Maven 依賴 JAR 根目錄。
2. 資源掃描機制：mappingJarLocations 要求 Spring 解析 JAR 文件路徑並掃描內部資源，依賴特定 ClassLoader 能力；mappingLocations 配合 classpath*: 前綴，委託 ClassLoader 直接加載資源流，兼容性更強。
3. 通配符語義：classpath*: 表示掃描所有 ClassPath 路徑下匹配的資源；classpath: 僅取第一個匹配項。JAR 內資源路徑為 com/allen/hbm/xxx.hbm.xml（無前導斜槓）。

最終解決方案

<property name="mappingLocations">
    <value>classpath*:com/allen/hbm/*.hbm.xml</value>
</property>

最佳實踐建議

• 統一使用 classpath*: + 相對包路徑通配符，避免絕對路徑、WEB-INF 等環境強耦合寫法
• 映射文件置於 JAR 內與包結構對應目錄（如 com/allen/hbm/），而非 JAR 根目錄
• 單元測試配置獨立的 applicationContext-test.xml，確保資源路徑一致性
• 若映射文件極多，考慮使用 packagesToScan（需實體類帶註解）或程序化配置 LocalSessionFactoryBean

驗證清單

1. JAR 解壓確認 .hbm.xml 位於正確包路徑下
2. 測試類路徑包含該 JAR（Maven 依賴 scope 為 compile/test）
3. 啟動日誌出現 Mapping file: com/allen/hbm/xxx.hbm.xml 字樣
4. HQL 查詢實體名與映射文件 <class name="..."> 一致

核心心法：資源加載路徑需與 ClassLoader 能力匹配，通配符語義要精確。