Java 17迁移场景下Hibernate 6编译错误的解决咨询

版本变更清单 #

• JDK 8 → JDK 17
• Maven 3.1 → Maven 3.8.6
• Tomcat 7 → Tomcat 10
• 从javax.servlet迁移至Jakarta Servlet

当前父POM依赖配置 #

<dependency>
    <groupId>jakarta.platform</groupId>
    <artifactId>jakarta.jakartaee-api</artifactId>
    <version>10.0.0</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>3.0.1</version>
    <scope>runtime</scope>
    <exclusions>
        <exclusion>
            <artifactId>xml-apis</artifactId>
            <groupId>xml-apis</groupId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>3.0.2</version>
    <scope>runtime</scope>
    <exclusions>
        <exclusion>
            <artifactId>xml-apis</artifactId>
            <groupId>xml-apis</groupId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>6.1.7.Final</version>
</dependency>
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-entitymanager</artifactId>
    <version>6.0.0.Alpha7</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-envers-jakarta</artifactId>
    <version>6.0.0.Alpha9</version>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>8.0.0.Final</version>
    <scope>runtime</scope>
</dependency>

构建编译错误 #

cannot find symbol 
[ERROR]   symbol:   class LogicalAuditExpression
[ERROR]   location: package org.hibernate.envers.query.criteria cannot find symbol 
[ERROR]   symbol:   class JavaTypeDescriptor
[ERROR]   location: package org.hibernate.type.descriptor.java cannot find symbol 
[ERROR]   symbol:   class BasicBinder 
[ERROR]   location: package org.hibernate.type.descriptor.sql cannot find symbol 
[ERROR]   symbol:   class SqlTypeDescriptor 
[ERROR]   location: class com.xxx.framework.base.jdbc.postgresql.PostgreSQLDialect cannot find symbol 
[ERROR]   symbol:   class YesNoType 
[ERROR]   location: package org.hibernate.type package org.hibernate.service.jdbc.dialect.internal does not exist

问题根源 #

1. Hibernate版本严重不匹配：稳定版hibernate-core:6.1.7.Final搭配预览版hibernate-envers-jakarta:6.0.0.Alpha9、hibernate-entitymanager:6.0.0.Alpha7，API差异导致类找不到。
2. 冗余依赖：Hibernate 6.x开始，hibernate-entitymanager已合并到hibernate-core中，无需单独引入。
3. Jakarta适配不彻底：未使用Hibernate针对Jakarta EE的专属artifactId，导致命名空间冲突。

解决方案 #

1. 统一Hibernate依赖版本（兼容Jakarta EE 10） #

移除旧的冲突依赖，替换为稳定的Jakarta专属版本：

<properties>
    <hibernate.version>6.2.13.Final</hibernate.version>
</properties>

<!-- Hibernate Core（包含EntityManager功能） -->
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core-jakarta</artifactId>
    <version>${hibernate.version}</version>
</dependency>
<!-- Hibernate Envers（Jakarta版本） -->
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-envers-jakarta</artifactId>
    <version>${hibernate.version}</version>
</dependency>
<!-- Hibernate Validator（Jakarta版本） -->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator-jakarta</artifactId>
    <version>8.0.1.Final</version>
    <scope>runtime</scope>
</dependency>

2. 修复编译错误对应的API变更 #

• LogicalAuditExpression：替换为AuditDisjunction/AuditConjunction，例如AuditQueryCreator.disjunction()替代逻辑或表达式。
• JavaTypeDescriptor/SqlTypeDescriptor/BasicBinder：改用Hibernate 6.x新API，如org.hibernate.type.descriptor.java.JavaType、org.hibernate.type.descriptor.jdbc.JdbcType。
• YesNoType：使用@Convert(converter = BooleanToYesNoConverter.class)自定义布尔值与Y/N的转换，或直接调用BooleanConverter接口。
• 自定义Dialect：继承org.hibernate.dialect.PostgreSQLDialect（Jakarta版本），适配新的JDBC类型注册API。

3. Java 17 + Hibernate 6.x + Jakarta EE 10 示例 #

核心POM片段

<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <jakartaee.version>10.0.0</jakartaee.version>
    <hibernate.version>6.2.13.Final</hibernate.version>
</properties>

<dependencies>
    <!-- Jakarta EE API（Tomcat 10提供实现） -->
    <dependency>
        <groupId>jakarta.platform</groupId>
        <artifactId>jakarta.jakartaee-api</artifactId>
        <version>${jakartaee.version}</version>
        <scope>provided</scope>
    </dependency>
    <!-- Hibernate核心依赖 -->
    <dependency>
        <groupId>org.hibernate.orm</groupId>
        <artifactId>hibernate-core-jakarta</artifactId>
        <version>${hibernate.version}</version>
    </dependency>
    <!-- Envers审计 -->
    <dependency>
        <groupId>org.hibernate.orm</groupId>
        <artifactId>hibernate-envers-jakarta</artifactId>
        <version>${hibernate.version}</version>
    </dependency>
    <!-- JAXB -->
    <dependency>
        <groupId>jakarta.xml.bind</groupId>
        <artifactId>jakarta.xml.bind-api</artifactId>
        <version>4.0.2</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jaxb</groupId>
        <artifactId>jaxb-runtime</artifactId>
        <version>4.0.4</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

实体类示例（Jakarta注解）

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import org.hibernate.envers.Audited;

@Entity
@Audited
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String username;
    private String email;
    
    // Getters & Setters
}

4. Jakarta版Hibernate JPA库说明 #

Hibernate 6.x开始，Jakarta EE兼容的JPA功能已完全整合到hibernate-core-jakarta中，不再存在单独的hibernate-jpa库。引入hibernate-core-jakarta即可获得完整的Jakarta Persistence API实现。

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