构建与依赖 / 系统课时

创建包含依赖的可执行 JAR

创建包含依赖的可执行 JAR

普通 mvn package 生成的 JAR 通常只含本项目类,直接执行时仍可能缺少第三方依赖。本课用 Maven Shade Plugin 3.6.2 把项目类、运行时依赖和入口清单合并成一个 JAR,并给出资源冲突与类名冲突的处理办法。

学习目标

  • 配置 Shade Plugin,在 package 阶段生成可直接 java -jar 运行的单一 JAR。
  • 使用 ManifestResourceTransformer 和 ServicesResourceTransformer 正确处理入口与服务发现资源。
  • 能区分资源冲突、签名文件冲突和类包冲突,并用对应手段验证修复结果。

准备一个能证明依赖已打包的入口类

以下示例使用 org.apache.commons:commons-lang3:3.17.0,入口类放在 src/main/java/com/example/App.java。代码故意调用第三方类;如果最终 JAR 没有包含依赖,运行时会立刻出现 NoClassDefFoundError,因此很适合作为验收样例。

java
package com.example;

import org.apache.commons.lang3.StringUtils;

public class App {
    public static void main(String[] args) {
        // 调用第三方依赖,验证它确实进入最终可执行 JAR。
        String message = StringUtils.upperCase("Maven Shade Ready");
        System.out.println(message);
    }
}

预期结果(完成下一节打包并执行后)

text
MAVEN SHADE READY

用 Shade Plugin 合并依赖并写入 Main-Class

示例固定使用 Maven Shade Plugin 3.6.2;该版本要求 Maven 3.6.3 及以上、JDK 8 及以上来运行插件。下面的 pom.xml 可直接配合上一节入口类使用,最终主制品仍命名为 demo-app-1.0.0.jar。

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>demo-app</artifactId>
  <version>1.0.0</version>

  <properties>
    <maven.compiler.source>8</maven.compiler.source>
    <maven.compiler.target>8</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-lang3</artifactId>
      <version>3.17.0</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.6.2</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <!-- Shading 后原依赖签名失效,避免把旧签名带入新 JAR。 -->
              <filters>
                <filter>
                  <artifact>*:*</artifact>
                  <excludes>
                    <exclude>META-INF/*.SF</exclude>
                    <exclude>META-INF/*.DSA</exclude>
                    <exclude>META-INF/*.RSA</exclude>
                  </excludes>
                </filter>
              </filters>
              <transformers>
                <!-- 合并多个依赖中的 META-INF/services 服务提供者文件。 -->
                <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                <!-- 写入 java -jar 所需的 Main-Class。 -->
                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                  <mainClass>com.example.App</mainClass>
                </transformer>
              </transformers>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

这条合并链路同时处理项目字节码、依赖字节码和特殊资源,普通的同名资源并不会自动得到语义正确的“合并”。需要合并的资源必须选择对应 transformer,签名文件则应在内容已被改写后排除。

Shade 生成单一可执行 JAR 的合并链路

执行完整打包命令:

bash
mvn clean package

预期输出的关键结尾

text
[INFO] BUILD SUCCESS

处理资源合并与类包冲突

ServicesResourceTransformer 只负责 META-INF/services 一类服务发现资源;它会把多个依赖中的实现类记录追加到同一个服务描述文件。若项目依赖 SPI、JDBC 驱动或其他 ServiceLoader 机制,遗漏它可能导致打包成功但运行时找不到实现。

先用依赖树确认冲突来自哪里。下面命令针对示例依赖,实际项目可替换为自己的 groupId:artifactId:

bash
mvn dependency:tree -Dincludes=org.apache.commons:commons-lang3

预期输出的关键行

text
[INFO] com.example:demo-app:jar:1.0.0
[INFO] \- org.apache.commons:commons-lang3:jar:3.17.0:compile
[INFO] BUILD SUCCESS

如果两个不同依赖携带相同包名,或你要把内嵌库与宿主环境隔离,可以使用 relocation。下面是片段示例,放入 Shade 的 <configuration> 内;它会把该包及字节码中的引用一起改写,反射字符串和外部配置仍需单独验证。

xml
<relocations>
  <relocation>
    <pattern>org.apache.commons.lang3</pattern>
    <shadedPattern>internal.shadow.org.apache.commons.lang3</shadedPattern>
  </relocation>
</relocations>

生效后重新运行测试和最终 JAR;如果第三方框架通过字符串反射原包名,不能只凭构建成功判断 relocation 安全。

验证最终 JAR 是否真的可独立运行

先直接执行最终制品。Shade 默认在未附加 classifier 时把 shaded JAR 作为项目主制品,因此本例运行 target/demo-app-1.0.0.jar,而不是依赖额外的 -cp 参数。

bash
java -jar target/demo-app-1.0.0.jar

预期输出

text
MAVEN SHADE READY

出现 no main manifest attribute 时检查 ManifestResourceTransformer 的 mainClass;出现 NoClassDefFoundError 时检查依赖 scope、过滤规则和依赖树;只有 SPI 功能失效时,优先检查 META-INF/services 是否经过 ServicesResourceTransformer 合并。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建包含依赖的可执行 JAR

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通