遭遇hibernate.MappingException: Unknown entity问题求助

核心排查点及解决方法 #

1. 确认Hibernate版本与Jakarta EE兼容性 #

Tomcat 10基于Jakarta EE 9，使用jakarta.persistence.*包，而旧版Hibernate（5.5及以下）依赖javax.persistence.*，会导致注解无法被识别。

• 解决方案：升级Hibernate到5.6.x或更高版本（5.6开始支持Jakarta），同时确保依赖的JPA API为Jakarta版本（jakarta.persistence:jakarta.persistence-api）。

2. 修正SessionFactory构建方式 #

Hibernate 5.2+推荐使用StandardServiceRegistry构建SessionFactory，旧的Configuration.buildSessionFactory()可能无法正确加载实体映射：

public static void save() {
    StandardServiceRegistry registry = new StandardServiceRegistryBuilder()
            .configure("hibernate.cfg.xml")
            .build();
    Transaction transaction = null;
    try {
        SessionFactory sessionFactory = new MetadataSources(registry)
                .buildMetadata()
                .buildSessionFactory();
        
        Company company = new Company();
        company.setId(1L);
        company.setCompanyName("madela");
        
        Session session = sessionFactory.getCurrentSession();
        transaction = session.beginTransaction();
        session.save(company);
        transaction.commit();
    } catch (Exception e) {
        if (transaction != null && transaction.isActive()) {
            transaction.rollback();
        }
        StandardServiceRegistryBuilder.destroy(registry);
        e.printStackTrace();
    }
}

3. 验证实体类映射配置 #

• 检查hibernate.cfg.xml中的<mapping class="com.example.entity.Company"/>是否与实体类全限定名完全一致（Java类名大小写敏感）。
• 确认实体类已被正确打包到项目WEB-INF/classes目录下，保证Tomcat部署时能加载到该类。

4. 排查类加载冲突 #

• 移除项目依赖中同时存在的javax.persistence相关Jar包，避免与jakarta.persistence类加载混淆。
• 检查Tomcat全局库中是否有冲突的Hibernate或JPA Jar包，避免类加载优先级问题。

5. 额外验证点 #

• 确认实体类的@Entity注解来自jakarta.persistence.Entity（而非旧的javax.persistence.Entity），检查import语句即可验证。
• 实体类已提供公共无参构造方法（你的代码中已满足此要求）。

报错信息回顾 #

org.hibernate.MappingException: Unknown entity: com.example.entity.Company
org.hibernate.metamodel.internal.MetamodelImpl.entityPersister(MetamodelImpl.java:710)
org.hibernate.internal.SessionImpl.getEntityPersister(SessionImpl.java:1648)
org.hibernate.event.internal.AbstractSaveEventListener.saveWithGeneratedId(AbstractSaveEventListener.java:114)
org.hibernate.event.internal.DefaultSaveOrUpdateEventListener.saveWithGeneratedOrRequestedId(DefaultSaveOrUpdateEventListener.java:194)
org.hibernate.event.internal.DefaultSaveEventListener.saveWithGeneratedOrRequestedId(DefaultSaveEventListener.java:38)
org.hibernate.event.internal.DefaultSaveOrUpdateEventListener.entityIsTransient(DefaultSaveOrUpdateEventListener.java:179)
org.hibernate.event.internal.DefaultSaveEventListener.performSaveOrUpdate(DefaultSaveEventListener.java:32)
org.hibernate.event.internal.DefaultSaveOrUpdateEventListener.onSaveOrUpdate(DefaultSaveOrUpdateEventListener.java:75)
org.hibernate.event.service.internal.EventListenerGroupImpl.fireEventOnEachListener(EventListenerGroupImpl.java:107)
org.hibernate.internal.SessionImpl.fireSave(SessionImpl.java:676)
org.hibernate.internal.SessionImpl.save(SessionImpl.java:669)
org.hibernate.internal.SessionImpl.save(SessionImpl.java:664)
com.example.service.impl.AbstractTest.saveTest(AbstractTest.java:43)
com.example.servlet.HelloWorld.doPost(HelloWorld.java:34)
jakarta.servlet.http.HttpServlet.service(HttpServlet.java:694)
jakarta.servlet.http.HttpServlet.service(HttpServlet.java:777)
org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53)

内容的提问来源于stack exchange，提问作者MishaBucha