JAVA 使用 Maven shade 打包后启动失败？资源合并与 META-INF 冲突处理

大家好，今天我们来聊聊在使用 Maven Shade 插件打包 Java 项目时，经常会遇到的启动失败问题，以及如何有效地进行资源合并和解决 META-INF 冲突。这个问题的根源在于 Shade 插件在将多个 JAR 包合并成一个 Uber JAR（或 Fat JAR）时，可能会遇到资源文件冲突，尤其是 META-INF 目录下的文件。这种冲突会导致程序在运行时找不到必要的资源或者加载了错误的版本，从而引发各种异常。

一、问题背景：Uber JAR 与资源冲突

Uber JAR，顾名思义，就是一个包含了项目自身代码以及所有依赖库代码的 JAR 文件。它的优点在于简化了部署，只需要一个文件就可以运行应用程序，避免了复杂的依赖管理。Maven Shade 插件就是用来生成 Uber JAR 的常用工具。

然而，Uber JAR 的生成过程并非完美。当多个 JAR 包中包含同名的资源文件时，例如 application.properties，或者更常见的，META-INF 目录下的文件（例如 MANIFEST.MF、services 文件等），Shade 插件默认的处理方式是覆盖，这很可能导致某些依赖库的功能失效，或者整个应用无法启动。

二、META-INF 目录的重要性

META-INF 目录在 JAR 文件中扮演着重要的角色。它包含了一些元数据信息，用于描述 JAR 文件的内容和结构，以及提供给 JVM 和其他工具使用的信息。一些重要的文件包括：

MANIFEST.MF： JAR 文件的清单文件，包含了 JAR 文件的版本、创建者、依赖关系等信息。它还定义了 JAR 文件的入口类 (Main-Class) 以及类路径 (Class-Path)。
services 目录： 用于实现 Service Provider Interface (SPI) 机制。该目录下的文件包含了接口的实现类的全限定名，JVM 通过这些文件来加载对应的实现。
versions 目录 (Java 9+)： 用于多版本 JAR 的管理。
其他： 一些依赖库可能会在 META-INF 目录下存放自己的配置文件或者元数据信息。

由于这些文件对于应用程序的正常运行至关重要，因此，在合并 JAR 文件时，必须小心处理 META-INF 目录下的文件，避免冲突。

三、常见错误与异常分析

使用 Maven Shade 打包后启动失败，常见的错误信息包括：

ClassNotFoundException: 找不到类，通常是因为某个依赖库的类没有被正确包含进 Uber JAR，或者类路径配置错误。
NoClassDefFoundError: 找不到类定义，与 ClassNotFoundException 类似，但通常发生在类加载的后期，表示该类在编译时存在，但在运行时找不到。
NoSuchMethodError: 找不到方法，通常是因为版本冲突，Uber JAR 中包含了多个版本的同一个类，导致方法签名不匹配。
IllegalArgumentException: 参数不合法异常，可能由于配置错误或者资源文件内容冲突导致。
ServiceConfigurationError: SPI 配置错误，通常是因为 META-INF/services 目录下的文件配置错误。
ManifestException: MANIFEST.MF 文件格式错误，通常是因为文件合并过程中引入了非法字符或者格式错误。

这些错误信息只是表象，我们需要深入分析问题的根源，才能找到正确的解决方案。

四、Maven Shade 插件配置详解

Maven Shade 插件提供了丰富的配置选项，用于控制 JAR 文件的合并过程。下面是一些常用的配置选项：

<transformers>: 用于定义转换器，对特定的文件进行合并、修改或者删除。
<filters>: 用于定义过滤器，排除不需要包含在 Uber JAR 中的文件。
<relocators>: 用于重定位类，避免类名冲突。
<shadedArtifactAttached>: 是否生成一个包含 shaded 后的 artifact 的附加 artifact。
<shadedClassifierName>: 附加 artifact 的 classifier 名称。
<createDependencyReducedPom>: 是否生成一个精简的 POM 文件，只包含 Uber JAR 的直接依赖。

下面是一个 Maven Shade 插件的示例配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>com.example.MainApplication</mainClass>
                    </transformer>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
                <filters>
                    <filter>
                        <artifact>*:*</artifact>
                        <excludes>
                            <exclude>META-INF/*.SF</exclude>
                            <exclude>META-INF/*.DSA</exclude>
                            <exclude>META-INF/*.RSA</exclude>
                        </excludes>
                    </filter>
                </filters>
                <relocators>
                    <relocator>
                        <pattern>com.google.guava</pattern>
                        <shadedPattern>shaded.com.google.guava</shadedPattern>
                    </relocator>
                </relocators>
                <shadedArtifactAttached>true</shadedArtifactAttached>
                <shadedClassifierName>uber</shadedClassifierName>
                <createDependencyReducedPom>false</createDependencyReducedPom>
            </configuration>
        </execution>
    </executions>
</plugin>

这个配置做了以下几件事：

指定主类 (Main-Class) 为 com.example.MainApplication。
使用 ServicesResourceTransformer 合并 META-INF/services 目录下的文件，用于 SPI。
排除签名文件，避免签名校验失败。
重定位 Guava 库的类，避免类名冲突。
生成一个附加的 artifact，classifier 为 uber。
不生成精简的 POM 文件。

五、资源合并策略与 Transformer 的使用

Maven Shade 插件提供了多种 Transformer，用于处理不同类型的资源文件。选择合适的 Transformer 是解决资源冲突的关键。

Transformer	描述	适用场景
`ManifestResourceTransformer`	合并 MANIFEST.MF 文件，可以指定主类 (Main-Class)。	应用程序需要指定入口类。
`ServicesResourceTransformer`	合并 META-INF/services 目录下的文件，用于 SPI。	应用程序使用了 SPI 机制。
`AppendingTransformer`	将多个同名文件的内容追加到一起。	适用于文本文件，例如 properties 文件、日志配置文件等。
`RenameTransformer`	重命名文件。	适用于需要避免文件名冲突的情况。
`FilterTransformer`	过滤文件内容，可以根据正则表达式过滤掉不需要的行。	适用于需要过滤掉某些特定内容的文本文件。
`ReplaceStringTransformer`	替换文件内容中的字符串。	适用于需要替换某些特定字符串的文本文件。
`IncludeResourceTransformer`/`ExcludeResourceTransformer`	根据指定的模式包含或排除特定的资源文件。	适用于需要精确控制哪些资源文件被包含或排除的情况。
`ComponentConfigResourceTransformer`	用于合并META-INF/plexus/components.xml 文件，该文件是plexus框架的组件配置文件。	如果项目依赖于plexus框架并且在META-INF/plexus/components.xml文件中定义了组件，则需要使用此转换器来合并组件配置。

5.1 `ManifestResourceTransformer` 的配置

<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
    <mainClass>com.example.MainApplication</mainClass>
</transformer>

这个 Transformer 用于合并 MANIFEST.MF 文件，并指定主类 (Main-Class)。如果没有指定主类，Shade 插件会尝试从依赖库的 MANIFEST.MF 文件中查找，如果找到多个主类，则会报错。

5.2 `ServicesResourceTransformer` 的配置

<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>

这个 Transformer 用于合并 META-INF/services 目录下的文件。它会将所有同名文件的内容合并到一个文件中，并去除重复的行。

5.3 `AppendingTransformer` 的配置

<transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
    <resource>application.properties</resource>
</transformer>

这个 Transformer 用于将多个 application.properties 文件的内容追加到一起。需要注意的是，追加的顺序是不确定的，因此，如果 properties 文件中存在相同的 key，后面的值会覆盖前面的值。

5.4 自定义 Transformer

如果 Maven Shade 插件提供的 Transformer 无法满足需求，可以自定义 Transformer。自定义 Transformer 需要实现 org.apache.maven.plugins.shade.resource.ResourceTransformer 接口。

public class CustomTransformer implements ResourceTransformer {

    @Override
    public boolean canTransformResource(String resource) {
        // 判断是否需要转换该资源
        return resource.equals("META-INF/custom.txt");
    }

    @Override
    public void processResource(String resource, InputStream is, List<Relocator> relocators) throws IOException {
        // 处理资源文件
        // ...
    }

    @Override
    public void modifyOutputStream(JarOutputStream os) throws IOException {
        // 将处理后的资源写入输出流
        // ...
    }
}

然后在 Maven Shade 插件的配置中指定自定义 Transformer：

<transformer implementation="com.example.CustomTransformer"/>

六、Filter 的使用

Filter 用于排除不需要包含在 Uber JAR 中的文件。它可以根据 artifact ID、groupId、文件路径等条件进行过滤。

<filters>
    <filter>
        <artifact>*:*</artifact>
        <excludes>
            <exclude>META-INF/*.SF</exclude>
            <exclude>META-INF/*.DSA</exclude>
            <exclude>META-INF/*.RSA</exclude>
        </excludes>
    </filter>
    <filter>
        <artifact>com.example:library</artifact>
        <excludes>
            <exclude>com/example/internal/**</exclude>
        </excludes>
    </filter>
</filters>

这个配置做了以下几件事：

排除所有 artifact 的签名文件。
排除 com.example:library artifact 中的 com/example/internal 目录下的所有文件。

七、Relocator 的使用

Relocator 用于重定位类，避免类名冲突。它可以将某个 package 下的所有类重命名到另一个 package 下。

<relocators>
    <relocator>
        <pattern>com.google.guava</pattern>
        <shadedPattern>shaded.com.google.guava</shadedPattern>
    </relocator>
</relocators>

这个配置将 com.google.guava package 下的所有类重命名到 shaded.com.google.guava package 下。

八、实战案例：解决 SPI 冲突

假设我们有一个应用程序，使用了 SPI 机制，依赖了两个库，都提供了同一个接口的实现。

library-a 提供了 com.example.spi.MyService 接口的实现 com.example.spi.impl.MyServiceA。
library-b 提供了 com.example.spi.MyService 接口的实现 com.example.spi.impl.MyServiceB。

如果直接使用 Maven Shade 打包，META-INF/services/com.example.spi.MyService 文件中只会包含其中一个实现类的全限定名，导致另一个实现无法被加载。

为了解决这个问题，我们可以使用 ServicesResourceTransformer 来合并 META-INF/services 目录下的文件：

<transformers>
    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
        <mainClass>com.example.MainApplication</mainClass>
    </transformer>
    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
</transformers>

这样，META-INF/services/com.example.spi.MyService 文件中就会同时包含 com.example.spi.impl.MyServiceA 和 com.example.spi.impl.MyServiceB，两个实现都可以被加载。

九、问题排查与调试技巧

当遇到 Maven Shade 打包后启动失败的问题时，可以尝试以下方法进行排查：

查看错误日志： 仔细阅读错误日志，找到错误信息的关键内容，例如 ClassNotFoundException、NoSuchMethodError 等。
检查 Uber JAR 的内容： 使用 JAR 查看工具（例如 7-Zip）打开 Uber JAR 文件，检查是否存在资源冲突、类缺失、版本冲突等问题。
使用调试模式： 在启动应用程序时，使用调试模式，可以单步调试代码，查看类加载的过程，以及资源文件的加载情况。
逐步排除依赖： 将依赖库逐个排除，观察是否能够解决问题，从而找到导致问题的依赖库。
调整 Shade 插件配置： 根据错误信息和 Uber JAR 的内容，调整 Shade 插件的配置，例如修改 Transformer、Filter、Relocator 等。
升级 Shade 插件版本： 有时候，旧版本的 Shade 插件可能存在 Bug，升级到最新版本可能会解决问题。

十、最佳实践

明确依赖关系： 在项目开始之前，明确项目的依赖关系，避免引入不必要的依赖。
谨慎使用 Uber JAR： Uber JAR 并非总是最佳选择，对于大型项目，使用独立的 JAR 文件可能更灵活、更易于维护。
充分测试： 在发布之前，对 Uber JAR 进行充分的测试，确保应用程序的各个功能都正常运行。
记录配置： 详细记录 Maven Shade 插件的配置，方便后续维护和问题排查。
保持 Shade 插件版本最新： 定期检查并更新 Shade 插件的版本，以获得最新的功能和 Bug 修复。

总结

Maven Shade 插件是一个强大的工具，但使用不当可能会导致启动失败。理解资源合并的原理，掌握 Transformer 和 Filter 的使用，以及掌握问题排查的技巧，是解决问题的关键。希望今天的分享能够帮助大家更好地使用 Maven Shade 插件，构建稳定可靠的 Java 应用程序。

应对复杂的依赖关系

理解 Maven Shade 的工作机制，熟练运用其配置选项，并结合实际案例进行问题排查和调试，才能有效解决资源冲突，构建出可稳定运行的 Uber JAR。

持续学习与实践

掌握 Maven Shade 插件的配置和使用，需要不断学习和实践。通过阅读官方文档、查阅相关资料、以及参与开源项目，可以不断提升自己的技能，更好地应对各种挑战。