maven-shade-plugin入门指南

有时候，需要将复杂的项目，包括各种xml文件属性文件，类， jar等等打包到一个可以执行的jar包中，然后用java -jar xxx.jar 来运行项目，这样简单方便，特别是在编写一些测试工具时，尤为重要。

但是经常发现打包后的项目无法启动，其中一大类是您项目有问题，但是这个相对好解决，毕竟自己的项目可以在windows下的ide中做各种调试，测试都测试好了，在打包一般程序问题的概率就低得多了。

1. Why?

uber-jar 即为 super-jar，super为关键字，故取名为uber

通过 maven-shade-plugin 生成一个 uber-jar，它包含所有的依赖 jar 包。

2. Goals

Goal	Description
shade:help	Display help information on maven-shade-plugin.Callmvn shade:help -Ddetail=true -Dgoal=to display parameter details.
shade:shade	Mojo that performs shading delegating to the Shader component.

3. Usage

配置 maven-shade-plugin

maven-shade-plugin 将 goal shade:shade 绑定到 phase package 上。

 <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>2.4.3</version><configuration><!-- put your configurations here --></configuration><executions><execution><phase>package</phase><goals><goal>shade</goal></goals></execution></executions></plugin></plugins></build>

执行命令

mvn clean package

会在 target 文件生成一个 uber-jar，以 -shaded.jar 为后缀的 jar 包。

4. Examples

Selecting Contents for Uber JAR

将该工程依赖的部分 Jar 包 include/exclude 掉。

<build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>2.4.3</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><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></execution></executions></plugin></plugins>
</build>

将依赖的某个 Jar 包内部的类或者资源 include/exclude 掉。

<build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>2.4.3</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><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></execution></executions></plugin></plugins>
</build>

maven-shade-plugin 自动将所有不使用的类全部排除掉，将 uber-jar 最小化。

  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>2.4.3</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration><minimizeJar>true</minimizeJar></configuration></execution></executions></plugin></plugins></build>

Attaching the Shaded Artifact

默认会生成一个Jar包和一个以 “-shaded”为结尾的uber-jar包，可以通过配置来指定uber-jar的后缀名。

  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>2.4.3</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration><shadedArtifactAttached>true</shadedArtifactAttached><shadedClassifierName>jackofall</shadedClassifierName> <!-- Any name that makes sense --></configuration></execution></executions></plugin></plugins></build>

Executable JAR

通过设置 MainClass 创建一个可执行 Jar 包。

  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>2.4.3</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration><transformers><transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"><mainClass>org.sonatype.haven.HavenCli</mainClass></transformer></transformers></configuration></execution></executions></plugin></plugins></build>

Relocating Classes

Java 工程经常会遇到第三方 Jar 包冲突，使用 maven shade plugin 解决 jar 或类的多版本冲突。 maven-shade-plugin 在打包时，可以将项目中依赖的 jar 包中的一些类文件打包到项目构建生成的 jar 包中，在打包的时候把类重命名。下面的配置将 org.codehaus.plexus.util jar 包重命名为 org.shaded.plexus.util。

  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>2.4.3</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><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></execution></executions></plugin></plugins></build>-----

下面的部分介绍的更为细致些，特别是， jar包和类的剔除等

网上有一些maven-shade-plugin替代maven-assembly-plugin的文章，原因是代maven-assembly-plugin打出的jar包中要么是不能设置Main-Class，要么spring的META-INF/spring.*文件相互覆盖了。对于这两个问题，maven-assembly-plugin在当前的版本(3.1.0)中都可以解决了(方法见https://my.oschina.net/u/2377110/blog/1584205)。

实际上这两个插件所针对的用途其实是有差异的，而它们与maven默认的maven-jar-plugin都是打包插件，简单的区别如下：

当你只想将项目打成一个可执行包时，maven-shade-plugin非常适合。一般情况下，pom文件中shade插件配置如下。

<build>  <plugins>  <plugin>  <groupId>org.apache.maven.plugins</groupId>  <artifactId>maven-shade-plugin</artifactId>  <version>1.4</version>  <executions>  <execution>  <phase>package</phase>  <goals>  <goal>shade</goal>  </goals>  <configuration>  <filters>  <filter>  <artifact>*:*</artifact>  <excludes>  <exclude>META-INF/*.SF</exclude>  <exclude>META-INF/*.DSA</exclude>  <exclude>META-INF/*.RSA</exclude>  </excludes>  </filter>  </filters>  <transformers>  <transformer  implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">  <mainClass>com.lcifn.Application</mainClass>  </transformer>  <transformer  implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">  <resource>META-INF/spring.handlers</resource>  </transformer>  <transformer  implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">  <resource>META-INF/spring.schemas</resource>  </transformer>  </transformers>  </configuration>  </execution>  </executions>  </plugin>  </plugins>
</build>

shade插件绑定的是package生命周期目标，并设置com.lcifn.Application为Main-Class，以及将META-INF/spring.*文件合并(追加而非覆盖)，并过滤掉所有依赖的META/INF中SF,DSA,RSA后缀文件。这里涉及到filter配置和transformer配置。

5. filters和artifactSet

Filter操作在打包时将jar包中的内容排除。它是以groupId:artifactId为标识，在filter内部可以使用/更细致地控制，既可以移除代码文件，也可以移除配置文件。

<!-- 按package过滤junit包 -->
<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></filters>
</configuration>

如果想将整个jar包都过滤掉，可以使用，也是指定groupId:artifactId的标识。

<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>

另外配置将项目中没有使用的依赖自动移除

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

可以和共同使用

<configuration><minimizeJar>true</minimizeJar><filters><filter><artifact>log4j:log4j</artifact><includes><include>**</include></includes></filter><filter><artifact>commons-logging:commons-logging</artifact><includes><include>**</include></includes></filter></filters>
</configuration>

6. 资源转换

在打包时，存在将多个构件中的class文件或资源文件聚合的需求。shade插件提供了丰富的Transformer工具类。这里介绍一些常用的Transformer。

ManifestResourceTransformer

往MANIFEST文件中写入Main-Class是可执行包的必要条件。ManifestResourceTransformer可以轻松实现。

<configuration><transformers><transformerimplementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"><mainClass>com.lcifn.Application</mainClass></transformer></transformers>
</configuration>

AppendingTransformer

用来处理多个jar包中存在重名的配置文件的合并，尤其是spring。

<configuration><transformers><transformerimplementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"><resource>META-INF/spring.handlers</resource></transformer><transformerimplementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"><resource>META-INF/spring.schemas</resource></transformer></transformers>
</configuration>

ServicesResourceTransformer

JDK的服务发现机制是基于META-INF/services/目录的，如果同一接口存在多个实现需要合并，则可以使用此Transformer。

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

更多的Transformer见http://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html

7. 原始构件与shade构件

默认情况下，shade插件会覆盖基于项目的jar包，而生成包含所有依赖的jar包。但有时需要原始的jar包和shade后的jar包同时被部署，可以配置如下。

<configuration><shadedArtifactAttached>true</shadedArtifactAttached><!-- 名称会作为后缀在shade构件jar包后 --><shadedClassifierName>jackofall</shadedClassifierName>
</configuration>

8. createDependencyReducedPom属性

maven-shade-plugin插件有个配置属性:createDependencyReducedPom,默认值为true.

当这个属性为true的时候，如果我们使用maven-shade-plugin来打包项目，那么便会在项目根目录下生成一个dependency-reduced-pom.xml文件，这个被删减的pom文件会移除已经打包进jar包中的依赖。

怎么理解呢，也就是说，假如我的一个工程A依赖了spring-boot-starter-tomcat,那么这个依赖(即spring-boot-starter-tomcat)中的.class文件会被打包进生成的A.jar包中，

<artifactId>spring-boot-starter-tomcat</artifactId>
<groupId>org.springframework.boot</groupId>

而在生成的dependency-reduced-pom.xml文件中，这个依赖将被exclusion掉。

那么这个dependency-reduced-pom.xml有什么用呢？
我们如果在另一个工程B中引用了A工程对应的A.jar，而且B也依赖了spring-boot-starter-tomcat，那么我们在B工程中就不需要再依赖spring-boot-starter-tomcat了，这样可以避免重复引用。

参考

https://www.jianshu.com/p/0ae23548e9f2
http://www.iigrowing.cn/maven-shade-plugin_ru_men_zhi_nan.html