本教程详细介绍如何使用gradle的shadow jar插件，将应用程序及其所有依赖项打包成一个独立的、可执行的jar文件。通过配置主模块的build.gradle文件，并运行特定的gradle任务，您可以轻松生成一个“胖jar”，实现便捷的部署和通过`java -jar`命令直接运行。
1. 理解可执行JAR与依赖管理
在Java开发中，将应用程序及其所有外部库（依赖项）打包成一个独立的、可执行的JAR文件是常见的部署需求。传统的java -cp命令需要手动指定所有依赖的路径，这在依赖众多时变得非常繁琐。为了简化部署和运行，我们通常会寻求一种方式来生成一个“胖JAR”（Fat Jar），即一个包含所有应用程序代码和其依赖的单一JAR文件，可以直接通过java -jar命令运行。
对于Gradle项目，尤其是多模块项目，虽然settings.gradle文件定义了项目的整体结构和模块包含关系，但具体的打包配置通常在每个模块的build.gradle文件中进行。本教程将重点介绍如何利用com.github.johnrengelman.shadow插件（通常称为Shadow Jar插件）来实现这一目标。
2. Shadow Jar插件简介
Shadow Jar插件是一个强大的Gradle插件，它能够将项目及其所有运行时依赖项合并到一个单独的JAR文件中。它的核心功能包括：
- 依赖合并（Shading）: 将所有依赖的类文件提取并重新打包到主JAR中。
- 类重定位（Relocation）: 允许重命名依赖包中的类，以避免在运行时与其他应用程序或库发生类路径冲突。
- 资源合并: 合并来自不同JAR的资源文件，如META-INF/services。
- 清单文件（Manifest）配置: 自动配置JAR的META-INF/MANIFEST.MF文件，特别是Main-Class属性，使其成为可执行JAR。
通过使用Shadow Jar插件，您可以轻松创建出可以直接运行的“胖JAR”，大大简化了应用程序的发布和部署流程。
3. 配置Shadow Jar插件
要使用Shadow Jar插件，您需要在希望生成可执行JAR的主模块的build.gradle文件中进行配置。
3.1 应用插件
首先，在主模块的build.gradle文件的plugins块中添加Shadow Jar插件。建议同时应用application插件，它能更好地辅助管理应用程序的主类。
plugins {
id 'java' // 如果是Java项目，通常会包含此插件
id 'application' // 用于定义应用程序的主类
id 'com.github.johnrengelman.shadow' version '7.1.2' // Shadow Jar插件
}请注意，version '7.1.2'应替换为当前或您项目兼容的最新版本。您可以在Shadow Jar插件的GitHub页面找到最新版本信息。
3.2 定义应用程序主类
为了使JAR文件可执行，您需要明确指定应用程序的入口点，即包含public static void main(String[] args)方法的类。这可以通过两种方式实现：
-
使用application插件配置: 这是推荐的方式，它使得主类定义更加清晰。
application { // 定义应用程序的主类，例如 'com.example.app.MainClass' mainClass = 'jaso92559.app.App' } -
直接在jar任务的manifest中配置: 这种方式也有效，但通常与application插件结合使用更佳。Shadow Jar插件在生成shadowJar时会尊重这些配置。
jar { manifest { attributes "Main-Class": "jaso92559.app.App" } }当同时使用application插件和jar任务的manifest配置时，application插件的mainClass通常会被Shadow Jar插件优先考虑并写入最终的shadowJar的MANIFEST.MF中。为了避免潜在的混淆，建议主要通过application块来定义主类。
完整的配置示例可能如下所示：
// build.gradle (主模块)
plugins {
id 'java'
id 'application'
id 'com.github.johnrengelman.shadow' version '7.1.2' // 请替换为最新版本
}
// 定义应用程序的主类
application {
mainClass = 'jaso92559.app.App' // 替换为您的应用程序主类
}
// 示例：如果需要对普通jar任务进行额外配置，但通常shadowJar会处理大部分
jar {
manifest {
attributes "Main-Class": "jaso92559.app.App" // 确保Main-Class属性被设置
}
}
// 其他项目配置，如依赖项等
repositories {
mavenCentral()
}
dependencies {
// 您的项目依赖
implementation 'com.google.guava:guava:31.1-jre'
testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.0'
testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.0'
}
tasks.named('test') {
useJUnitPlatform()
}4. 生成可执行JAR文件
配置完成后，您可以通过运行Gradle的shadowJar任务来生成包含所有依赖的可执行JAR文件。
在项目根目录（settings.gradle文件所在的目录）下，打开命令行或终端，执行以下命令：
./gradlew shadowJar
或者在Windows系统上：
gradlew shadowJar
Gradle将会编译您的项目，并使用Shadow Jar插件将所有依赖项打包到最终的JAR文件中。
5. 运行生成的JAR文件
任务成功执行后，生成的JAR文件通常位于主模块的build/libs/目录下。文件的命名约定通常是[module-name]-all.jar或[module-name]-[version]-all.jar。例如，如果您的模块名为app，则可能生成app-all.jar。
您可以通过以下命令直接运行这个“胖JAR”：
java -jar app-all.jar
替换app-all.jar为实际生成的文件名。如果一切配置正确，您的应用程序将会启动。
6. 总结与注意事项
- 插件位置: Shadow Jar插件应应用于需要打包成可执行JAR的具体模块的build.gradle文件，而不是根build.gradle或settings.gradle。
- 主类定义: 确保application.mainClass或jar.manifest.attributes["Main-Class"]正确指向您的应用程序入口类。
- 版本管理: 定期检查并更新Shadow Jar插件到最新版本，以获取性能改进和新功能。
- 冲突解决: 在极少数情况下，如果依赖中存在类名冲突或资源冲突，Shadow Jar插件提供了relocate和mergeServiceFiles等高级配置选项来解决这些问题。
- 文件大小: 生成的“胖JAR”会包含所有依赖，因此文件大小会比普通JAR大很多，这是正常的。
通过遵循本教程，您可以高效地利用Gradle的Shadow Jar插件来创建易于分发和执行的独立应用程序JAR文件，极大地简化了Java项目的部署流程。
