创建包含依赖的Gradle Uber JAR及Kotlin库冲突解决方法

1. 理解Uber JAR及其必要性

在软件开发中，尤其是在需要将一个项目（例如一个库或微服务）打包成一个独立的可执行文件或易于分发的组件时，我们常常需要创建一个包含所有运行时依赖项的JAR文件，这被称为“Uber JAR”或“胖JAR”。这种打包方式简化了部署，因为所有必需的第三方库都被打包在同一个JAR中，无需额外管理依赖。

然而，简单地通过Gradle的jar任务来合并依赖通常不足以应对复杂场景，例如处理资源文件冲突或更深层次的依赖树。更重要的是，在Kotlin项目中，如果Uber JAR包含了Kotlin运行时库，当这个JAR被另一个同样使用Kotlin的项目引用时，可能会因为类路径上存在重复或不同版本的Kotlin运行时库而导致冲突，从而出现IDE无法识别JAR内部类或运行时错误。

2. 使用Shadow Plugin创建Uber JAR

com.github.johnrengelman.shadow插件是Gradle生态系统中创建Uber JAR的推荐解决方案。它能够智能地处理依赖项的合并，包括重命名包以避免冲突（Shading）以及处理资源文件。

初始配置 (Project A - 待打包项目):

首先，在你的Kotlin项目（例如Project A）的build.gradle.kts文件中，添加Shadow插件：

plugins {
    kotlin("jvm") version "1.6.21" // 使用你的Kotlin版本
    java // 确保java插件也已应用，shadow插件依赖它
    id("com.github.johnrengelman.shadow") version "7.1.2" // 使用最新稳定版本
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    // 你的项目依赖，例如
    implementation("org.mybatis.dynamic-sql:mybatis-dynamic-sql:1.4.1")
    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

tasks.withType {
    kotlinOptions.jvmTarget = "1.8"
}

// 配置assemble任务，使其依赖于shadowJar任务
tasks.assemble {
    dependsOn("shadowJar")
}

应用此配置后，运行gradle shadowJar命令将会在build/libs目录下生成一个名为your-project-name-version-all.jar（或类似名称）的Uber JAR，其中包含了所有运行时依赖。

3. 解决Kotlin库冲突问题

当Project A生成的Uber JAR包含Kotlin运行时库，并且被另一个Kotlin项目（例如Project B）引用时，IDE（如IntelliJ IDEA）可能会出现无法识别JAR内部类的问题。这通常是因为Project B本身已经通过其Kotlin插件引入了Kotlin运行时库，导致类路径上存在重复的Kotlin核心类。

为了解决这个问题，我们需要在创建Uber JAR时，明确地将Kotlin运行时相关的依赖从最终的JAR文件中排除。这样，当Project B引用这个Uber JAR时，它将使用自己已有的Kotlin运行时库，避免冲突。

排除Kotlin库的Shadow Plugin配置 (Project A - 修正版):

在Project A的build.gradle.kts中，添加ShadowJar任务的配置，以排除所有以"kotlin"开头的依赖：

plugins {
    kotlin("jvm") version "1.6.21"
    java
    id("com.github.johnrengelman.shadow") version "7.1.2"
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

tasks.assemble {
    dependsOn("shadowJar")
}

// 关键步骤：配置ShadowJar任务以排除Kotlin库
tasks.withType {
    exclude {
        // 排除所有以"kotlin"开头的依赖，例如kotlin-stdlib, kotlin-reflect等
        it.name.startsWith("kotlin")
    }
    // 可以根据需要添加其他排除规则，例如：
    // exclude("META-INF/*.SF", "META-INF/*.DSA", "META-INF/*.RSA") // 排除签名文件
}

dependencies {
    implementation("org.mybatis.dynamic-sql:mybatis-dynamic-sql:1.4.1")
    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

tasks.withType {
    kotlinOptions.jvmTarget = "1.8"
}

tasks.withType {
    // 保持为空或根据需要配置
}

通过exclude { it.name.startsWith("kotlin") }这行配置，Shadow插件在打包时会忽略所有名称以"kotlin"开头的JAR文件，这些通常是Kotlin的标准库、反射库等运行时依赖。重新运行gradle shadowJar后，生成的Uber JAR将不再包含这些Kotlin运行时库。

4. 在其他项目中使用Uber JAR (Project B)

一旦Project A生成了不含内部Kotlin运行时库的Uber JAR（例如ProjectA-1.0-SNAPSHOT-all.jar），Project B就可以将其作为本地文件依赖进行引用。

Project B 的 build.gradle.kts 配置:

plugins {
    kotlin("jvm") version "1.6.21"
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    // 引用Project A生成的Uber JAR
    // 假设JAR文件位于Project B的src/main/resources目录下
    implementation(files("src/main/resources/ProjectA-1.0-SNAPSHOT-all.jar"))
    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

tasks.withType {
    kotlinOptions.jvmTarget = "1.8"
}

此时，Project B的IDE应该能够正确识别ProjectA-1.0-SNAPSHOT-all.jar中的所有类，并且由于Kotlin运行时库由Project B自身提供，不会发生冲突。

5. 注意事项与最佳实践

• 版本兼容性： 确保Project A（原始项目）和Project B（引用项目）使用的Kotlin版本兼容。如果Project B使用的Kotlin版本与Project A编译时使用的Kotlin版本差异过大，即使排除了Kotlin运行时库，也可能导致运行时问题。
• 资源冲突： Shadow插件在合并JAR时会智能处理资源文件，但极端情况下仍需注意。如果两个依赖包含相同路径的资源文件，Shadow插件默认会选择第一个遇到的。
• 发布到Maven仓库： 对于更专业的项目间依赖管理，最佳实践是将Project A发布到本地或远程Maven仓库，而不是直接引用本地JAR文件。这样Project B可以通过标准的Maven/Gradle依赖声明来引用Project A，Gradle会自动处理依赖的传递性。
• 为什么不直接使用Gradle的jar任务合并依赖？ Gradle的默认jar任务主要用于打包项目的类和资源，不直接处理其传递性依赖。虽然可以通过from(configurations.runtimeClasspath.get().map { zipTree(it) })手动合并，但这通常无法解决类路径冲突、资源文件冲突等复杂问题，而Shadow插件正是为此而生。

总结

创建包含所有依赖的Uber JAR是分发和部署Kotlin/Gradle项目的常见需求。com.github.johnrengelman.shadow插件提供了强大的功能来完成这项任务。然而，在Kotlin项目中，为了避免IDE无法识别类或运行时冲突，务必配置ShadowJar任务以排除Kotlin运行时相关的库。通过这种方式，可以确保生成的Uber JAR在其他Kotlin项目中能够无缝集成和正常运行。