本文详解 Hibernate 使用 XML 映射（.hbm.xml）时出现 Unable to locate persister: entity.Users 异常的根本原因与修复方法，重点说明配置类注册缺失、命名一致性及 Hibernate 6 兼容性要点。
本文详解 hibernate 使用 xml 映射（`.hbm.xml`）时出现 `unable to locate persister: entity.users` 异常的根本原因与修复方法，重点说明配置类注册缺失、命名一致性及 hibernate 6 兼容性要点。
在基于 XML 的 Hibernate 配置中，Unable to locate persister: entity.Users 是一个典型且易被忽视的初始化错误。它并非数据库连接或 SQL 语法问题，而是 Hibernate 在启动阶段未能成功注册实体映射元数据，导致运行时无法识别 entity.User 类对应的持久化上下文（即 Persister）。从堆栈可知，异常发生在 session.persist(user) 调用时，说明 Session 已创建，但其内部元模型中不存在 entity.User 的映射描述。
根本原因在于：仅在 hibernate.cfg.xml 中声明 <mapping resource="Users.hbm.xml"/> 并不足够。Hibernate 6（如本例所用 6.0.0.Final）已废弃旧版 Configuration.addResource() 的隐式加载机制，转而要求显式注册映射资源——尤其当使用 StandardServiceRegistryBuilder 构建 SessionFactory 时，必须通过 Configuration 实例手动添加 .hbm.xml 文件。
✅ 正确修复步骤
1. 显式注册 XML 映射文件
修改 HibernateUtilities.java 的静态初始化块，在构建 SessionFactory 前调用 configuration.addResource()：
import org.hibernate.HibernateException;
import org.hibernate.SessionFactory;
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
import org.hibernate.cfg.Configuration;
import java.io.IOException;
public class HibernateUtilities {
private static SessionFactory sessionFactory;
static {
try {
Configuration configuration = new Configuration().configure();
// ✅ 关键修复：显式添加 Users.hbm.xml 映射资源
configuration.addResource("Users.hbm.xml"); // 注意路径需与类路径一致
StandardServiceRegistryBuilder builder =
new StandardServiceRegistryBuilder()
.applySettings(configuration.getProperties());
sessionFactory = configuration.buildSessionFactory(builder.build());
} catch (HibernateException e) {
System.err.println("Problem creating session factory: " + e.getMessage());
throw e; // 不建议静默吞掉异常，便于调试
}
}
public static SessionFactory getSessionFactory() {
return sessionFactory;
}
}⚠️ 路径注意事项：addResource("Users.hbm.xml") 中的路径是 相对于类路径（classpath）的资源路径。确保 Users.hbm.xml 位于 src/main/resources（Maven/Gradle 项目）或 out/production/<module>（IntelliJ 默认输出目录）下，且包结构无需匹配（XML 文件本身已声明 name="entity.User"）。
2. 核对实体类与 XML 声明的一致性
检查 Users.hbm.xml 中的 class 属性是否与 Java 类完全匹配：
<class name="entity.User" table="USERS" schema="PROTRACKER"> <!-- ↑ 必须与 Users.java 的 package 和 class 名完全一致 -->
- ✅ 正确：package entity; public class User { ... }
- ❌ 错误：若类名为 Users（复数），但 XML 写 entity.User，或 Java 类在默认包而 XML 写 entity.User。
3. （可选）启用 Schema 自动更新验证映射
临时在 hibernate.cfg.xml 中取消注释并配置 hbm2ddl.auto，帮助验证映射是否被正确加载：
<property name="hibernate.hbm2ddl.auto">update</property> <property name="hibernate.show_sql">true</property> <property name="hibernate.format_sql">true</property>
若配置生效，启动时将看到类似 HHH000397: Using ASTQueryTranslatorFactory 和 DDL 日志，证明映射已载入。
? 为什么 addAnnotatedClass(User.class) 不适用？
问题答案中建议的 configuration.addAnnotatedClass(User.class) 是针对 注解映射（@Entity） 的注册方式，与当前纯 XML 配置场景不兼容。强行添加会导致：
- Hibernate 尝试按注解规则解析 User 类（但该类无任何 JPA 注解）；
- 可能引发 MappingException: No identifier specified 等新错误；
- 违背“XML 配置优先”设计意图，造成配置混乱。
因此，必须坚持使用 addResource() 加载 .hbm.xml。
✅ 最终验证
修复后运行 app.java，预期输出应包含成功提交日志，且 Oracle 表 PROTRACKER.USERS 中新增一条 NAME='Joe' 记录。若仍报错，请检查：
- Users.hbm.xml 是否存在于类路径（IntelliJ 中右键 → Reload project）；
- hibernate.cfg.xml 中 <mapping resource="..."> 的路径拼写是否与 addResource() 参数一致；
- Hibernate 版本是否为 6.x（本方案专为 6.0+ 设计；5.x 可能需 configuration.configure().addResource(...) 链式调用）。
通过显式注册 XML 映射资源，即可彻底解决 Unable to locate persister 问题，确保 Hibernate 在 XML 驱动模式下稳定持久化实体。
