Hibernate HQL 報錯：User is not mapped 實體映射排查清單

現象

session.createCriteria(User.class) 正常，session.createQuery("from User") 報 User is not mapped。

根本原因

HQL 查詢使用**實體類名**（而非表名），且要求實體已被 SessionFactory 識別。常見原因：

1. 實體類未在配置中註冊（hibernate.cfg.xml 或 persistence.xml）。
2. 包掃描路徑錯誤，實體類所在包未被掃描。
3. 註解缺失：缺少 @Entity、@Table。
4. 大小寫不匹配：HQL 中 User 需與實體類名完全一致（區分大小寫）。

排查清單

驗證方法

// 獲取所有已註冊實體名
Map metadata = sessionFactory.getAllClassMetadata();
for (String entityName : metadata.keySet()) {
    System.out.println(entityName); // 應包含 "com.example.User"
}

參考資源

詳細排查：新浪博客 Hibernate User is not mapped 解決

總結

User is not mapped 核心是**實體類未被 SessionFactory 識別**。按「配置註冊 → 包掃描 → 註解完整 → HQL 大小寫」四步排查，通常能定位問題。Criteria API 直接用 Class 對象，故不受映射名稱影響。