一、介紹 [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。
參考來源
http://maven.apache.org/plugins/maven-shade-plugin/index.html ↩︎
http://maven.apache.org/plugins/maven-shade-plugin/usage.html ↩︎
http://maven.apache.org/plugins/maven-shade-plugin/examples/includes-excludes.htm ↩︎
http://maven.apache.org/plugins/maven-shade-plugin/examples/class-relocation.html ↩︎
http://maven.apache.org/plugins/maven-shade-plugin/examples/executable-jar.html ↩︎
http://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html ↩︎