Hibernate 儲存報「找不到實體類」：映射檔案名稱寫法陷阱

錯誤現象

執行 session.save(entity) 時拋出 MappingException: Unknown entity: User 或類似訊息。實體類、映射檔 (`.hbm.xml`) 皆存在，但 Hibernate 無法解析。

核心原因：映射檔 `` 必須寫**完整限定類名 (FQCN)**

假設實體類完整名稱為 com.attest.User，映射檔 `User.hbm.xml` 內容必須為：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
"https://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
<hibernate-mapping package="com.attest"> <!-- 可選：設定包前綴 -->
    <class name="User" table="t_user"> <!-- 若上方設定 package，這裡可寫簡短名 -->
        <id name="id" column="id">
            <generator class="native"/>
        </id>
        <property name="username" column="username"/>
        <!-- 其他屬性 -->
    </class>
</hibernate-mapping>

或不使用 package 屬性，直接寫完整類名：

<class name="com.attest.User" table="t_user"> ... </class>

配置檔註冊映射檔也需完整路徑

hibernate.cfg.xml 中：

<mapping resource="com/attest/User.hbm.xml"/> <!-- 從 classpath 根目錄起算的相對路徑，使用 / 分隔 -->
<!-- 錯誤寫法：resource="User.hbm.xml" (若檔案在包目錄下) -->

原答案截圖說明

常見變體錯誤

• Annotation 配置遺漏： 使用 `@Entity` 註解時，需在 `hibernate.cfg.xml` 註冊 <mapping class="com.attest.User"/> 或掃描包 <property name="packagesToScan">com.attest</property> (SessionFactory 配置)。
• 大小寫敏感： Linux 伺服器部署時，資源路徑大小寫必須與實際檔案完全一致。
• 重複映射： 同一實體被 `.hbm.xml` 與 `@Entity` 同時配置，導致重複註冊衝突。

快速自查清單

1. 實體類是否 `public`、有無參建構子？
2. 映射檔 `` 是否為 **完整類名** 或配合 ``？
3. `cfg.xml` 中 `` 路徑是否為 **classpath 相對路徑** (如 `com/attest/User.hbm.xml`)？
4. 映射檔是否確實被打包進 `classes` / `jar` (檢查 `target/classes/com/attest/User.hbm.xml`)？
5. SessionFactory 建構時控制台是否有輸出 Reading mappings from resource: com/attest/User.hbm.xml？

修正上述任一項後，**重新編譯部署 (Clean + Build)**，即可解決「找不到實體」問題。