maven-plugin-shade 详解
1]shademaven-plugin-shade 插件提供了两个能力把整个项目(包含它的依赖)都打包到一个 "uber-jar" 中shade - 即重命名某些依赖的包由此引出了两个问题什么是 uber-jar?uber-jar 也叫做 fat-jar 或者 jar-with-dependencies,意思就是包含依赖的 jar。什么是 shade?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 插件提供了两个能力:
- 把整个项目(包含它的依赖)都打包到一个 "uber-jar" 中
- shade - 即重命名某些依赖的包
由此引出了两个问题:
-
什么是 uber-jar ?
uber-jar 也叫做 fat-jar 或者 jar-with-dependencies,意思就是包含依赖的 jar。
-
什么是 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。
参考来源
开放原子开发者工作坊旨在鼓励更多人参与开源活动,与志同道合的开发者们相互交流开发经验、分享开发心得、获取前沿技术趋势。工作坊有多种形式的开发者活动,如meetup、训练营等,主打技术交流,干货满满,真诚地邀请各位开发者共同参与!
更多推荐
所有评论(0)