maven-plugin-shade 详解

一、介绍 ^[1]

This plugin provides the capability to package the artifact in an uber-jar, including its dependencies and to shade - i.e. rename - the packages of some of the dependencies.

maven-plugin-shade 插件提供了两个能力：

1. 把整个项目（包含它的依赖）都打包到一个 "uber-jar" 中
2. shade - 即重命名某些依赖的包

由此引出了两个问题：

1. 什么是 uber-jar ？

   uber-jar 也叫做 fat-jar 或者 jar-with-dependencies，意思就是包含依赖的 jar。

2. 什么是 shade ？

   shade 意为遮挡，在此处可以理解为对依赖的 jar 包的重定向（主要通过重命名的方式）。

‍♂️ 下文中可能使用 shade 来代替 maven-plugin-shade。

二、基本使用 ^[2]

maven-plugin-shade 必须和 Maven 构建生命周期中的 package 阶段绑定，也就是说，当执行 mvn package 时会自动触发 shade。

要使用 maven-plugin-shade，只需要在 pom.xml 的 <plugins> 标签下添加它的配置即可，示例如下：

<project>
    ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.2.4</version>
                <configuration>
                    <!-- 此处按需编写更具体的配置 -->
                </configuration>
                <executions>
                    <execution>
                        <!-- 和 package 阶段绑定 -->
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
    ...
</project>

默认情况下会把项目所有的依赖都包含进最终的 jar 包中。当然，我们也可以在 <configuration> 标签内配置更具体的规则。

三、常用功能

3.1 按需选择要添加到最终 jar 包中依赖 ^[3]

使用 <includes> 排除不需要的依赖，示例如下：

<configuration>
    <artifactSet>
        <excludes>
            <exclude>classworlds:classworlds</exclude>
            <exclude>junit:junit</exclude>
            <exclude>jmock:*</exclude>
            <exclude>*:xml-apis</exclude>
            <exclude>org.apache.maven:lib:tests</exclude>
            <exclude>log4j:log4j:jar:</exclude>
        </excludes>
    </artifactSet>
</configuration>

使用 <filters> 结合 <includes> & <excludes> 标签可实现更灵活的依赖选择，示例如下：

<configuration>
    <filters>
        <filter>
            <artifact>junit:junit</artifact>
            <includes>
                <include>junit/framework/**</include>
                <include>org/junit/**</include>
            </includes>
            <excludes>
                <exclude>org/junit/experimental/**</exclude>
                <exclude>org/junit/runners/**</exclude>
            </excludes>
        </filter>
        <filter>
            <artifact>*:*</artifact>
            <excludes>
                <exclude>META-INF/*.SF</exclude>
                <exclude>META-INF/*.DSA</exclude>
                <exclude>META-INF/*.RSA</exclude>
            </excludes>
        </filter>
    </filters>
</configuration>

除了可以通过自定义的 filters 来过滤依赖，此插件还支持自动移除项目中没有使用到的依赖，以此来最小化 jar 包的体积，只需要添加一项配置即可。示例如下：

<configuration>
    <minimizeJar>true</minimizeJar>
</configuration>

3.2 重定位 class 文件 ^[4]

如果最终的 jar 包被其他的项目所依赖的话，直接地引用此 jar 包中的类可能会导致类加载冲突，这是因为 classpath 中可能存在重复的 class 文件。为了解决这个问题，我们可以使用 shade 提供的重定位功能，把部分类移动到一个全新的包中。示例如下：

<configuration>
    <relocations>
        <relocation>
            <pattern>org.codehaus.plexus.util</pattern>
            <shadedPattern>org.shaded.plexus.util</shadedPattern>
            <excludes>
                <exclude>org.codehaus.plexus.util.xml.Xpp3Dom</exclude>
                <exclude>org.codehaus.plexus.util.xml.pull.*</exclude>
            </excludes>
        </relocation>
    </relocations>
</configuration>

涉及标签：

• <pattern>：原始包名
• <shadedPattern>：重命名后的包名
• <excludes>：原始包内不需要重定位的类，类名支持通配符

例如，在上述示例中，我们把 org.codehaus.plexus.util 包内的所有子包及 class 文件（除了 ~.xml.Xpp3Dom 和 ~.xml.pull 包下的所有 class 文件）重定位到了 org.shaded.plexus.util 包内。

当然，如果包内的大部分类我们都不需要，一个个排除就显得很繁琐了。此时我们也可以使用 <includes> 标签来指定我们仅需要的类，示例如下：

<project>
    ...
    <relocation>
        <pattern>org.codehaus.plexus.util</pattern>
        <shadedPattern>org.shaded.plexus.util</shadedPattern>
        <includes>
            <include>org.codehaud.plexus.util.io.*</include>
        </includes>
    </relocation>
    ...
</project>

3.3 生成可执行 jar 包 ^[5]

使用 maven-plugin-shade 后，最终生成的 jar 包可以包含所有项目所需要的依赖。我们会想，能不能直接运行这个 uber-jar 呢？答案是当然可以，并且十分简单，只需要指定 <mainClass> 启动类就可以了。示例如下：

<project>
    ...
    <configuration>
        <transformers>
            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                <mainClass>org.sonatype.haven.HavenCli</mainClass>
            </transformer>
        </transformers>
    </configuration>
    ...
</project>

熟悉 jar 包的朋友们都知道，jar 包中默认会包含一个 MANIFEST.MF 文件，里面描述了一些 jar 包的信息。使用 java 自带的 jar 命令打包的时候可以指定 MANIFEST.MF，其中也可以指定 Main-Class 来使得 jar 包可运行。那么使用 shade 来指定和直接在 MANIFEST.MF 文件中指定有什么区别呢？

答案是没有区别，细心的读者会发现 <mainClass> 标签的父标签是 <transformer> 有一个 implementation 属性，其值为 "~.ManifestResourceTransformer"，意思是 Manifest 资源文件转换器。上述示例只自指定了启动类，因此 shade 会为我们自动生成一个包含 Main-Class 的 MANIFEST.MF 文件，然后在打 jar 包时指定这个文件。

那如果我们想要完全定制 MANIFEST.MF 文件内容怎么办呢？我们可以使用 <manifestEntries> 标签，示例如下：

<project>
    ...
    <configuration>
        <transformers>
            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                <manifestEntries>
                    <Main-Class>org.sonatype.haven.ExodusCli</Main-Class>
                    <Build-Number>123</Build-Number>
                </manifestEntries>
            </transformer>
        </transformers>
    </configuration>
    ...
</project>

4.4 生成资源文件 ^[6]

项目中涉及到的依赖可能会有它们所必需的资源文件，使用 shade 可以把它们聚合在同一个 jar 包中。

默认地，shade 为我们提供了 12 个 ResourceTransformer 类：

类名	作用
ApacheLicenseResourceTransformer	防止 LICENSE 文件重复
ApacheNoticeResourceTransformer	准备合并的 NOTICE
AppendingTransformer	为某个资源文件附加内容
ComponentsXmlResourceTransformer	聚合 Plexus components.xml
DontIncludeResourceTransformer	防止包含指定的资源
GroovyResourceTransformer	合并 Apache Groovy 的扩展模块
IncludeResourceTransformer	添加项目中的文件为资源文件
ManifestResourceTransformer	自定义 MANIFEST 文件
PluginXmlResourceTransformer	聚合 Maven 的 plugin.xml 配置
ResourceBundleAppendingTransformer	合并 ResourceBundles
ServicesResourceTransformer	重定位且合并 META-INF/services 资源文件中的 class 文件.
XmlAppendingTransformer	为 XML 资源文件附加内容

每种 ResourceTransformer 的具体使用可以点击对应链接查看官方示例，这里不再赘述。

如果上述 12 个类都不能够满足我们的需求，我们可以实现 shade 提供的接口，按需自定义一个 ResourceTransformer，实现方法详见官网 Using your own Shader implementation。

参考来源

---

1. http://maven.apache.org/plugins/maven-shade-plugin/index.html ︎

2. http://maven.apache.org/plugins/maven-shade-plugin/usage.html ︎

3. http://maven.apache.org/plugins/maven-shade-plugin/examples/includes-excludes.htm ︎

4. http://maven.apache.org/plugins/maven-shade-plugin/examples/class-relocation.html ︎

5. http://maven.apache.org/plugins/maven-shade-plugin/examples/executable-jar.html ︎

6. http://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html ︎