Hibernate 异常 UnknownEntityException：Could not resolve root entity

1、概览

本文将带你了解 Hibernate 出现异常 “UnknownEntityException：Could not resolve root entity” 的原因，以及解决办法。

2、理解异常

通常，在 HQL 或 JPQL 查询中解析已知映射实体名称失败时，Hibernate 就会抛出 “UnknownEntityException: Could not resolve root entity” 异常。

简而言之，Hibernate 依赖 JPA 实体来完成对象关系映射的所有工作。因此，它希望查询中指定的实体名称与 @Entity 注解所注解的类名称相匹配。

因此，导致异常的最常见原因之一就是 使用了与有效实体类名称不匹配的名称。

3、示例

知道了导致 Hibernate 出现 UnknownEntityException 的原因后，来看看如何在实践中重现这种情况。

首先，创建一个 Person 类，如下：

@Entity
public class Person {
    @Id
    private int id;
    private String firstName;
    private String lastName;

    // 标准 Getter / Setter 方法省略
}

如上，使用 id、firstName 和 lastName 来定义一个 Person。

@Entity 注解表示 Person 类是一个 JPA 实体，@Id 表示代表主键的字段。

接下来，我们故意在 HQL 查询中使用错误的实体名称。例如，尝试用 PERSON 代替 Person 作为实体名称来 SELECT 所有 Person 实体：

class UnknownEntityExceptionUnitTest {
    private static Session session;

    @BeforeAll
    static void init() {
        session = HibernateUtil.getSessionFactory().openSession();
        session.beginTransaction();
    }

    @AfterAll
    static void clear() {
        session.close();
    }

    @Test
    void whenUsingUnknownEntity_thenThrowUnknownEntityException() {
        assertThatThrownBy(() -> session.createQuery("FROM PERSON", Person.class))
          .hasRootCauseInstanceOf(UnknownEntityException.class)
          .hasRootCauseMessage("Could not resolve root entity 'PERSON'");
    }
}

如你所见，测试用例失败，抛出了异常：UnknownEntityException: Could not resolve root entity because Hibernate doesn’t recognize PERSON as a valid JPA entity。

4、修复异常

如前所述，Hibernate 引发 UnknownEntityException 的主要原因是它无法找到具有指定名称的实体。因此，最简单的解决办法就是在 HQL 和 JPQL 查询中使用正确的实体名称。

添加一个新的测试用例，并将错误的名称 PERSON 替换为正确的 Person：

@Test
void whenUsingCorrectEntity_thenReturnResult() {
    Query<Person> query = session.createQuery("FROM Person", Person.class);

    assertThat(query.list()).isEmpty();
}

如上所示，测试用例成功执行，没有出现异常，因为这次使用的 Person 是一个有效的实体名称。

5、总结

本文介绍了 Hibernate 出现异常 UnknownEntityException: “Could not resolve root entity” 的原因，以及如何解决该异常。

Ref：https://www.baeldung.com/hibernate-unknownentityexception-could-not-resolve-root-entity