Hibernate 6升级后Gradle构建无法解析hibernate-commons-annotations

问题描述 #

将Hibernate依赖从5.6.11.Final升级到6.1.7.Final并迁移到Jakarta包后，项目无法通过Gradle构建，提示无法定位org.hibernate.common:hibernate-commons-annotations:6.0.6.Final。

• 从Hibernate依赖中排除该注解模块可以完成构建，但编译/调试时会缺失该模块中的类；
• 手动添加该模块则返回相同的构建错误。

Gradle构建错误信息 #

:api:dev: Could not resolve org.hibernate.common:hibernate-commons-annotations:6.0.6.Final.
Required by:
    project :api > org.hibernate:hibernate-hikaricp:6.1.7.Final > org.hibernate.orm:hibernate-hikaricp:6.1.7.Final > org.hibernate.orm:hibernate-core:6.1.7.Final

Possible solution:
 - Declare repository providing the artifact, see the documentation at https://docs.gradle.org/current/userguide/declaring_repositories.html

项目build.gradle配置 #

plugins {
    id 'java'
    id 'com.github.johnrengelman.shadow' version '7.0.0' apply true
    id 'org.flywaydb.flyway' version '8.0.0-beta2'
    id 'maven-publish'
}

project.sourceCompatibility = "1.8"
project.targetCompatibility = "1.8"

repositories {
    mavenCentral()
    maven {
        name = 'spongepowered-repo'
        url = 'https://repo.spongepowered.org/maven'
    }
    maven {
        name = 'jitpack-repo'
        url = 'https://jitpack.io'
    }
}

static def loadEnv() {
    def env = [:]

    try {
        def file = new File('.env')
        def scanner = new Scanner(file)
        while (scanner.hasNextLine()) {
            def line = scanner.nextLine()
            if (line.contains('=')) {
                def pair = line.split('=')
                env.put(pair[0], pair.length == 2 ? pair[1] : '')
            }
        }
    } catch (FileNotFoundException ignored) { }

    env.putAll(System.getenv())
    return env
}

def env = loadEnv()

shadowJar {
    def remoteGson = 'com.google.code.gson'
    def remoteCommon = 'com.google.common'
    def remoteOpenfeign = 'openfeign'
    def remoteMariaJdbc = 'org.mariadb.jdbc'
    def remoteHibernate = 'org.hibernate'
    def remoteYaml = 'org.yaml.snakeyaml'
    def remoteApacheText = 'org.apache.commons.text'

    def localGson = 'dev.sbs.api.util.google.gson'
    def localCommon = 'dev.sbs.api.util.google.common'
    def localOpenfeign = 'dev.sbs.api.util.openfeign'
    def localMariaJdbc = 'dev.sbs.api.data.sql.mariadb'
    def localHibernate = 'dev.sbs.api.data.sql.hibernate'
    def localYaml = 'dev.sbs.api.data.yaml.snake'
    def localApacheText = 'dev.sbs.api.util.text'

    relocate remoteGson, localGson
    relocate remoteCommon, localCommon
    relocate remoteOpenfeign, localOpenfeign
    relocate remoteMariaJdbc, localMariaJdbc
    relocate remoteHibernate, localHibernate
    relocate remoteYaml, localYaml
    relocate remoteApacheText, localApacheText
}

sourceSets {
    dev {
        java {
            srcDirs = ['src/main/java']
        }
        resources {
            srcDirs = ['src/main/resources']
        }
    }
    devTest {
        java {
            srcDirs = ['src/test/java']
            compileClasspath += sourceSets.dev.output
            runtimeClasspath += sourceSets.dev.output
        }
        resources {
            srcDirs = ['src/test/resources']
        }
    }
}

dependencies {
    // Deserialization
    implementation group: 'com.google.code.gson', name: 'gson', version: '2.10.1'
    implementation group: 'com.google.guava', name: 'guava', version: '31.1-jre'
    implementation group: 'org.yaml', name: 'snakeyaml', version: '2.0'

    // Database
    implementation group: 'org.mariadb.jdbc', name: 'mariadb-java-client', version: '3.1.2'
    implementation group: 'org.ehcache', name: 'ehcache', version: '3.10.6'
    implementation group: 'org.hibernate', name: 'hibernate-hikaricp', version: '6.1.7.Final'
    implementation group: 'org.hibernate', name: 'hibernate-jcache', version: '6.1.7.Final'

    // Api Clients
    implementation group: 'io.github.openfeign', name: 'feign-okhttp', version: '12.2'
    implementation group: 'io.github.openfeign', name: 'feign-gson', version: '12.2'
    implementation group: 'redis.clients', name: 'jedis', version: '4.3.1'

    // Other
    implementation group: 'org.apache.commons', name: 'commons-text', version: '1.10.0'
    implementation group: 'ch.qos.logback', name: 'logback-classic', version: '1.4.6'

    // Annotations
    compileOnly group: 'org.projectlombok', name: 'lombok', version: '1.18.26'
    annotationProcessor group: 'org.projectlombok', name: 'lombok', version: '1.18.26'

    // Tests
    testImplementation group: 'org.hamcrest', name: 'hamcrest', version: '2.2'
    testImplementation group: 'org.junit.jupiter', name: 'junit-jupiter-api', version: '5.9.2'
    testRuntimeOnly group: 'org.junit.jupiter', name: 'junit-jupiter-engine', version: '5.9.2'
}

configurations {
    devImplementation.extendsFrom implementation
    devCompileOnly.extendsFrom compileOnly
    devAnnotationProcessor.extendsFrom annotationProcessor

    devTestImplementation.extendsFrom implementation
    devTestCompileOnly.extendsFrom compileOnly
    devTestAnnotationProcessor.extendsFrom annotationProcessor
    devTestImplementation.extendsFrom testImplementation
    devTestRuntimeOnly.extendsFrom testRuntimeOnly
}

// Exclude specific packages while they are being refactored
task devJar(type: Jar, group: 'build') {
    archiveAppendix.value('dev')
    archiveBaseName.value(artifactIdProp)
    archiveVersion.value(versionProp)

    from sourceSets.dev.java
    from sourceSets.dev.output
}

tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

publishing {
    repositories {
        maven {
            name = 'GitHubPackages'
            url = uri('https://maven.pkg.github.com/skyblock-simplified/sbs-api')
            credentials {
                username = env.get('GITHUB_USER')
                password = env.get('GITHUB_TOKEN')
            }
        }
    }
    publications {
        devPub(MavenPublication) {
            groupId = groupIdProp
            artifactId = artifactIdProp + '-dev'
            version = versionProp
            artifacts = [devJar]
            pom.withXml {
                def dependencies = asNode().appendNode('dependencies')
                configurations.implementation.allDependencies.each {
                    def dependency = dependencies.appendNode('dependency')
                    dependency.appendNode('groupId', it.group)
                    dependency.appendNode('artifactId', it.name)
                    dependency.appendNode('version', it.version)
                }
                configurations.compileOnly.allDependencies.each {
                    def dependency = dependencies.appendNode('dependency')
                    dependency.appendNode('groupId', it.group)
                    dependency.appendNode('artifactId', it.name)
                    dependency.appendNode('version', it.version)
                }
                configurations.annotationProcessor.allDependencies.each {
                    def dependency = dependencies.appendNode('dependency')
                    dependency.appendNode('groupId', it.group)
                    dependency.appendNode('artifactId', it.name)
                    dependency.appendNode('version', it.version)
                }
            }
        }
        releasePub(MavenPublication) {
            groupId = groupIdProp
            artifactId = artifactIdProp
            version = versionProp
            artifacts = [shadowJar]
            pom.withXml {
                def dependencies = asNode().appendNode('dependencies')
                configurations.implementation.allDependencies.each {
                    def dependency = dependencies.appendNode('dependency')
                    dependency.appendNode('groupId', it.group)
                    dependency.appendNode('artifactId', it.name)
                    dependency.appendNode('version', it.version)
                }
                configurations.compileOnly.allDependencies.each {
                    def dependency = dependencies.appendNode('dependency')
                    dependency.appendNode('groupId', it.group)
                    dependency.appendNode('artifactId', it.name)
                    dependency.appendNode('version', it.version)
                }
                configurations.annotationProcessor.allDependencies.each {
                    def dependency = dependencies.appendNode('dependency')
                    dependency.appendNode('groupId', it.group)
                    dependency.appendNode('artifactId', it.name)
                    dependency.appendNode('version', it.version)
                }
            }
        }
    }
}

flyway {
    url = 'jdbc:mariadb://' + env.get('DATABASE_HOST') + ':' + env.get('DATABASE_PORT') + '/' + env.get('DATABASE_SCHEMA')
    user = env.get('DATABASE_USER')
    password = env.get('DATABASE_PASSWORD')
}

test {
    useJUnitPlatform()
}

tasks.register('devTest', Test) {
    useJUnitPlatform()
    group = 'verification'
    testClassesDirs = sourceSets.devTest.output.classesDirs
    classpath = sourceSets.devTest.runtimeClasspath
}

解决方案 #

1. 升级Java版本到11及以上 #

Hibernate 6.1.x的最低兼容Java版本为11，当前项目配置的1.8版本不符合要求，会导致依赖解析或运行时异常。修改build.gradle中的版本配置：

project.sourceCompatibility = "11"
project.targetCompatibility = "11"

2. 清理Gradle缓存并重新构建 #

缓存损坏可能导致依赖解析失败，执行以下命令清理缓存并刷新依赖：

./gradlew clean build --refresh-dependencies

3. 显式添加hibernate-commons-annotations依赖 #

尽管该依赖是hibernate-core的传递依赖，但显式声明可以确保Gradle正确定位到该模块：

dependencies {
    // ... 其他依赖保持不变 ...
    implementation group: 'org.hibernate.common', name: 'hibernate-commons-annotations', version: '6.0.6.Final'
}

4. 检查Shadow插件的重定位配置 #

项目中对org.hibernate包进行了重定位，这可能干扰Gradle的依赖解析逻辑。尝试暂时注释掉该重定位规则，重新构建验证：

// relocate remoteHibernate, localHibernate

如果问题解决，说明重定位规则需要调整，建议仅重定位项目自身代码中使用的Hibernate类，而非整个包。

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