解決 Hibernate Spring 整合錯誤：Error creating bean with name 'sessionFactory' 實體類找不到

錯誤現象

在整合 Spring + Hibernate 專案啟動時，控制台拋出嚴重異常：

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'sessionFactory' defined in class path resource [spring.xml]: Invocation of init method failed; nested exception is org.hibernate.MappingException: entity class not found: News
Caused by: java.lang.ClassNotFoundException: News

根因分析

錯誤堆疊明確指向 org.hibernate.MappingException: entity class not found: News，進一步由 java.lang.ClassNotFoundException: News 確認。核心原因在於：

1. Hibernate 映射檔案中指定的實體類路徑錯誤：在 .hbm.xml 或註解配置中，class 屬性指向的全限定類名與實際類不符
2. 實體類未被編譯輸出到 classpath：可能因 IDE 配置問題、Maven 編譯插件誤配、或資源過濾導致 News.class 未打包進 WEB-INF/classes
3. 包名大小寫不一致：Windows 不區分大小寫，但 Linux 伺服器區分，導致部署時找不到類

排查步驟與解決方案

1. 檢查映射配置

<!-- hbm.xml 範例 -->
<hibernate-mapping>
    <class name="com.example.entity.News" table="news">  <!-- 確認全限定名 -->
        <id name="id" column="id">
            <generator class="native"/>
        </id>
        <property name="title" column="title"/>
    </class>
</hibernate-mapping>

關鍵檢查點：name 屬性必須與實體類的 package + className 完全一致，包含大小寫。

2. 驗證類輸出路徑

• Eclipse/IDEA：Project Structure → Modules → Paths 確認輸出目錄
• Maven 專案：執行 mvn clean compile，檢查 target/classes/com/example/entity/News.class 是否存在
• 部署後：解壓 WAR 包，確認 WEB-INF/classes/com/example/entity/News.class 存在

3. Spring 配置掃描路徑

<!-- spring.xml -->
<bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean">
    <property name="packagesToScan" value="com.example.entity"/>  <!-- 確保掃描路徑正確 -->
    <property name="hibernateProperties">
        <props>
            <prop key="hibernate.dialect">org.hibernate.dialect.MySQLDialect</prop>
            <!-- 其他屬性 -->
        </props>
    </property>
</bean>

若使用 packagesToScan，確保基礎包路徑正確；若用 mappingResources 顯式列出 .hbm.xml，檢查路徑是否為 classpath:hibernate/News.hbm.xml 格式。

4. 類載入器問題排查

若以上均正確，可能是類載入器隔離導致。嘗試在啟動時添加 JVM 參數：-verbose:class 觀察 News 類載入情況，或檢查是否有多個 ClassLoader（如 Tomcat 共享庫與應用庫衝突）。

最佳實踐建議

• 優先使用註解配置（@Entity、@Table），減少 XML 維護錯誤
• 統一包名規範：全小寫、功能模組化（com.company.module.entity）
• CI/CD 流程中加入 mvn clean test package 強制全量編譯驗證
• 開發、測試、生產環境保持一致的 JDK 版本與類載入策略

總結

「entity class not found」本質是執行期類路徑與配置期聲明不一致。系統性檢查「映射配置 → 編譯輸出 → 部署打包 → Spring 掃描」四個環節，即可精準定位並解決問題。