maven-shade-plugin入门指南
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都是打包插件，简单的区别如下：
|plugin|function| | — | — | |maven-jar-plugin|maven 默认打包插件，用来创建 project jar| |maven-shade-plugin|用来打可执行包，包含依赖，以及对依赖进行取舍过滤| |maven-assembly-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>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.lcifn.Application</mainClass>
</transformer>
</transformers>
</configuration>
AppendingTransformer
用来处理多个jar包中存在重名的配置文件的合并，尤其是spring。
<configuration>
<transformers>
<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>
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