Hibernate自动检测注解实体类时出现持久化器定位错误

问题 #

使用Hibernate 6.2.5.Final时，希望通过自动扫描实体类替代在hibernate.cfg.xml中逐个添加<mapping>标签，配置hibernate.archive.autodetection和hibernate.packageToScan后出现错误：

Unable to locate persister: ina.project.backend.entities.UserEntity

旧版手动添加映射的配置可正常运行，以下是相关代码文件：

pom.xml #

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>main</groupId>
    <artifactId>InternetAnwendungen-Project</artifactId>
    <version>1.0</version>
    <packaging>war</packaging>
    <name>Internet Anwendung - Project</name>
    <url>https://maven.apache.org</url>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.target>11</maven.compiler.target>
        <maven.compiler.source>11</maven.compiler.source>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.jsoup</groupId>
            <artifactId>jsoup</artifactId>
            <version>1.16.1</version>
        </dependency>
        <dependency>
            <groupId>jakarta.platform</groupId>
            <artifactId>jakarta.jakartaee-web-api</artifactId>
            <version>9.1.0</version>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-core</artifactId>
            <version>6.2.5.Final</version>
        </dependency>
        <dependency>
            <groupId>org.hibernate.validator</groupId>
            <artifactId>hibernate-validator</artifactId>
            <version>7.0.4.Final</version>
        </dependency>
        <dependency>
            <groupId>org.mariadb.jdbc</groupId>
            <artifactId>mariadb-java-client</artifactId>
            <version>3.0.8</version>
        </dependency>
        <dependency>
            <groupId>org.jetbrains</groupId>
            <artifactId>annotations</artifactId>
            <version>RELEASE</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>io.github.cdimascio</groupId>
            <artifactId>dotenv-java</artifactId>
            <version>2.2.0</version>
        </dependency>
    </dependencies>

    <build>
        <finalName>ROOT</finalName>
        <directory>./dev-ops/build</directory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.2</version>
                <configuration>
                    <outputDirectory>./dev-ops/build</outputDirectory>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

UserEntity.java #

package ina.project.backend.entities;

import jakarta.persistence.*;
import jakarta.validation.constraints.Size;

import java.io.Serializable;

@Entity
@Table(name = "User")
@NamedQuery(name = "user.byId", query = "SELECT u FROM UserEntity u  where u.id = ?1")
@NamedQuery(name = "user.byUsername", query = "SELECT u FROM UserEntity u  where u.username = ?1")
public class UserEntity implements Serializable {
    @Id
    @Column(name = "id", nullable = false, unique = true, updatable = false)
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private int id;

    @Column(name = "username", nullable = false, unique = true)
    @Size(min = 4, max = 100)
    private String username;

    @Column(name = "password", nullable = false)
    private String password;

    public int getId() {
        return id;
    }

    public UserEntity setId(int id) {
        this.id = id;
        return this;
    }

    public String getUsername() {
        return username;
    }

    public UserEntity setUsername(String username) {
        this.username = username;
        return this;
    }

    public String getPassword() {
        return password;
    }

    public UserEntity setPassword(String password) {
        this.password = password;
        return this;
    }
}

旧版 hibernate.cfg.xml（可正常运行） #

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">

<hibernate-configuration>
    <session-factory>

        <!-- Connection Properties -->
        <property name="connection.driver_class">org.mariadb.jdbc.Driver</property>

        <property name="connection.pool_size">10</property>
        <property name="dialect">org.hibernate.dialect.MariaDBDialect</property>
        <property name="cache.provider_class">org.hibernate.cache.internal.NoCachingRegionFactory</property>
        <property name="show_sql">true</property>
        <property name="hbm2ddl.auto">validate</property>
        <property name="current_session_context_class">thread</property>
        <mapping class="ina.project.backend.entities.UserEntity"/>
    </session-factory>

</hibernate-configuration>

新版 hibernate.cfg.xml（出错版本） #

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">

<hibernate-configuration>
    <session-factory>

        <!-- Connection Properties -->
        <property name="connection.driver_class">org.mariadb.jdbc.Driver</property>

        <property name="connection.pool_size">10</property>
        <property name="dialect">org.hibernate.dialect.MariaDBDialect</property>
        <property name="cache.provider_class">org.hibernate.cache.internal.NoCachingRegionFactory</property>
        <property name="show_sql">true</property>
        <property name="hbm2ddl.auto">validate</property>
        <property name="current_session_context_class">thread</property>
        <property name="hibernate.archive.autodetection">class, hbm</property>
        <property name="hibernate.packageToScan">ina.project.backend.entities</property>
    </session-factory>

</hibernate-configuration>

解决方案 #

1. 修正Hibernate 6的扫描配置属性 #

Hibernate 6废弃了hibernate.packageToScan，需改用无hibernate.前缀的packagesToScan属性。保留hibernate.archive.autodetection确保检测类文件：

修改新版hibernate.cfg.xml中的扫描配置：

<property name="packagesToScan">ina.project.backend.entities</property>
<property name="hibernate.archive.autodetection">class</property>

2. 确认WAR包中包含实体类字节码 #

由于项目是WAR打包，需确保编译后的实体类位于WEB-INF/classes目录。修改maven-war-plugin配置，明确指向编译后的类路径：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <version>3.3.2</version>
    <configuration>
        <outputDirectory>./dev-ops/build</outputDirectory>
        <classesDirectory>${project.build.directory}/classes</classesDirectory>
    </configuration>
</plugin>

3. 检查配置加载逻辑 #

如果手动通过Configuration类加载配置，确保调用configure()后未覆盖扫描规则：

Configuration config = new Configuration().configure();
SessionFactory sessionFactory = config.buildSessionFactory();

无需手动调用addAnnotatedClass，packagesToScan会自动扫描指定包下的实体类。

4. 验证实体类注解 #

确认实体类使用的是Jakarta规范注解（jakarta.persistence.Entity），你的代码已正确使用，此部分无需调整。

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