解決 org.hibernate.MappingException: Unknown entity 錯誤完整指南

錯誤現象

在基於 Spring + Hibernate + Struts2 的 SSH 整合專案中，嘗試儲存回覆（Revert）實體時，伺服器拋出 HTTP 500 錯誤，堆疊追蹤顯示：

org.hibernate.MappingException: Unknown entity: com.ssh.domain.Revert

異常鏈路從 ArticleAction.revertArticle 經由 Service、DAO 層最終在 HibernateTemplate.save() 觸發，根因是 SessionFactoryImpl.getEntityPersister() 找不到對應的實體映射資訊。

核心原因分析

1. 實體類未被 Hibernate 掃描到

最常見原因是 Revert 類雖然存在於 com.ssh.domain 包下，但未在 Hibernate 設定檔（hibernate.cfg.xml 或 Spring 的 LocalSessionFactoryBean）中註冊映射檔（.hbm.xml）或掃描註解。

2. 映射檔案遺失或路徑錯誤

• 若使用 .hbm.xml：檢查 mappingResources 或 mappingLocations 是否包含 com/ssh/domain/Revert.hbm.xml
• 若使用註解：確認 packagesToScan 涵蓋 com.ssh.domain

3. 實體類缺少 @Entity 註解

若採用 JPA 註解方式，Revert 類必須標註 @Entity，否則 Hibernate 不會將其視為持久化實體。

解決方案

方案一：在 Spring 中補全映射配置（推薦）

<bean id="sessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
    <property name="mappingLocations">
        <list>
            <value>classpath:com/ssh/domain/*.hbm.xml</value>
        </list>
    </property>
    <!-- 或使用註解掃描 -->
    <property name="packagesToScan">
        <list><value>com.ssh.domain</value></list>
    </property>
</bean>

方案二：手動在 hibernate.cfg.xml 註冊

<mapping resource="com/ssh/domain/Revert.hbm.xml"/>

方案三：補全實體類註解

@Entity
@Table(name = "revert")
public class Revert implements Serializable {
    @Id @GeneratedValue
    private Long id;
    // ... 其他欄位
}

驗證步驟

1. 重啟應用，觀察啟動日誌中是否出現 Mapping class: com.ssh.domain.Revert
2. 再次觸發回覆儲存操作，確認不再拋出 Unknown entity

避坑指南

• 新增實體類後，務必同步更新映射配置，建議採用 packagesToScan 通配掃描，減少手動維護成本
• 專案遷移或重構包路徑時，同步檢查映射路徑是否失效
• 若使用多模組專案，確認實體類所在模組已被主模組依賴並掃描