Java8升级Java17后Hibernate无法解析根实体‘Category’

核心问题定位 #

升级到Hibernate 6.2 + Java 17后，hibernate.cfg.xml中配置的<mapping class="..."/>未被正确加载，导致HQL无法识别实体类，必须手动调用addAnnotatedClass()才能正常工作。以下是针对性的排查和解决步骤：

1. 修复Gradle构建配置（最可能的根因） #

你的build.gradle中未启用Java插件，导致实体类根本没有被编译到项目的类路径中：

//apply plugin: 'java'  // 被注释掉了
plugins {
    id 'antlr'
}

Hibernate通过XML中的全类名查找实体类时，找不到编译后的class文件，自然无法解析实体。

解决方法：
在plugins块中添加Java插件：

plugins {
    id 'java'
    id 'antlr'
}

同时恢复项目基础配置：

group = 'xxx'
version = '15.5.8-fromBuildGradle'

执行gradle clean build重新编译项目，确保实体类被正确打包到classpath中。

2. 更新Hibernate配置文件的DTD声明 #

你当前使用的是Hibernate 3.x的DTD，与Hibernate 6.2不兼容，可能导致XML解析时忽略<mapping>标签：

<!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//EN" "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">

解决方法：替换为Hibernate 6.x的DTD：

<!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 6.0//EN" "https://hibernate.org/dtd/hibernate-configuration-6.0.dtd">

3. 修正MySQL方言配置 #

使用MySQL 8时，应使用专门的8.x方言，而非通用的MySQLDialect：

<property name="hibernate.dialect">org.hibernate.dialect.MySQL8Dialect</property>

老方言可能引发兼容性问题，间接影响实体加载逻辑。

4. 处理Java模块系统的反射限制（若使用模块） #

如果项目使用了module-info.java（Java 9+模块系统），Hibernate需要反射访问实体类，必须在模块声明中开放实体类所在的包：

module your.module.name {
    // 允许Hibernate反射访问实体类
    opens com.xxx.xx.models.settings to org.hibernate.orm.core;
    // 导出实体类包（若其他模块需要访问）
    exports com.xxx.xx.models.settings;
}

5. 调整Hibernate SessionFactory初始化方式（可选） #

Hibernate 6.x推荐使用MetadataSources替代传统的Configuration类来构建SessionFactory，确保实体映射被正确加载：

MetadataSources metadataSources = new MetadataSources(
        new StandardServiceRegistryBuilder()
                .configure("hibernate.cfg.xml")
                .applySetting("hibernate.connection.url", "jdbc:mysql://" + this._host + ":" + this._port + "/" + this._database)
                .applySetting("hibernate.connection.username", this._username)
                .applySetting("hibernate.connection.password", this._password)
                .build()
);
Metadata metadata = metadataSources.buildMetadata();
SessionFactory sessionFactory = metadata.buildSessionFactory();

这种方式更符合Hibernate 6.x的设计规范，能避免一些兼容性问题。

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