升级microprofile-openapi-api至2.0+导致hibernate-jpamodelgen失效求助

原因分析 #

MicroProfile OpenAPI 2.0及以上版本的microprofile-openapi-api依赖会引入Jakarta EE API的传递依赖，而Hibernate JPA ModelGen 6.x基于Jakarta Persistence API（JPA 3.x）构建，两者结合后出现以下问题导致注解处理器失效：

1. 类路径中出现JPA API多版本冲突（Java EE的JPA 2.x与Jakarta EE的JPA 3.x共存），Gradle注解处理器路径优先选择了不兼容的API版本，导致Hibernate处理器无法识别实体类的JPA注解。
2. MicroProfile OpenAPI 2.0+自身引入的注解处理器或修改的执行顺序，干扰了Gradle对Hibernate JPA ModelGen的扫描与加载，使得处理器未被触发执行。

解决办法 #

1. 明确指定JPA API版本，消除依赖冲突 #

在build.gradle中显式引入兼容的Jakarta Persistence API，确保类路径中只有单一有效版本：

implementation 'jakarta.persistence:jakarta.persistence-api:3.1.0'

同时可通过Gradle命令排查依赖树，确认是否存在旧版JPA API：

./gradlew dependencyInsight --dependency jakarta.persistence:jakarta.persistence-api

2. 强制隔离Hibernate注解处理器的依赖 #

修改annotationProcessor配置，排除Hibernate JPA ModelGen中可能冲突的JPA API依赖，避免被OpenAPI的传递依赖干扰：

annotationProcessor('org.hibernate.orm:hibernate-jpamodelgen:6.1.6.Final') {
    exclude group: 'javax.persistence', module: 'javax.persistence-api'
    exclude group: 'jakarta.persistence', module: 'jakarta.persistence-api'
}

也可显式配置注解处理器路径，确保Hibernate处理器被优先加载：

tasks.withType(JavaCompile) {
    options.annotationProcessorPath = files(configurations.annotationProcessor)
}

3. 升级Hibernate JPA ModelGen到兼容版本 #

尝试使用最新稳定版的hibernate-jpamodelgen，新版本对Jakarta EE生态的适配性更好：

annotationProcessor('org.hibernate.orm:hibernate-jpamodelgen:6.4.4.Final')

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