Maven shading工作原理及maven-shade-plugin配置指南

1. Maven中的shading是什么？ #

shading是Maven体系中常用的依赖打包技术，核心能力是将项目自身编译产物和所有依赖的Jar包内容合并到同一个输出Jar中，同时支持按需对指定依赖的包路径做重命名，从根源上解决不同依赖之间的版本冲突问题。
举个常见场景：你的项目直接依赖了commons-lang3的3.12.0版本，而引入的某个第三方组件依赖了commons-lang3的2.6版本，两个版本API不兼容。通过shading你可以把自己用到的3.12.0版本的包路径重命名后打包到输出Jar中，和第三方依赖的2.6版本完全隔离，不会出现类加载冲突。

2. 什么是maven-shade-plugin，它的作用是什么？ #

maven-shade-plugin是Maven官方维护的专门用来实现shading能力的插件，它的核心作用包括：

• 把项目编译产物 + 全部依赖合并为单个可执行Jar（也叫fat Jar/uber Jar）
• 支持自定义包重定向规则，对指定依赖做包路径重写，实现依赖隔离，解决类冲突
• 支持灵活的打包规则配置，可排除不需要的依赖项、资源文件，也可合并多个Jar中同名的配置文件（比如Spring的spring.handlers、spring.schemas这类SPI配置文件）
• 支持自定义可执行Jar的主类，打包后的产物可直接通过java -jar命令运行

3. 如何配置maven-shade-plugin来实现shading功能？ #

基础配置示例如下，将配置添加到项目pom.xml的<build><plugins>节点下即可：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.1</version>
    <executions>
        <execution>
            <!-- 绑定到package生命周期阶段 -->
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <!-- 配置可执行Jar的主类 -->
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>com.yourproject.MainClass</mainClass>
                    </transformer>
                    <!-- 合并Spring配置文件示例 -->
                    <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>
                <!-- 包重命名配置示例：把org.apache.commons.lang3重命名为shaded.org.apache.commons.lang3 -->
                <relocations>
                    <relocation>
                        <pattern>org.apache.commons.lang3</pattern>
                        <shadedPattern>shaded.org.apache.commons.lang3</shadedPattern>
                        <!-- 配置不需要重命名的子包/类 -->
                        <excludes>
                            <exclude>org.apache.commons.lang3.math.NumberUtils</exclude>
                        </excludes>
                    </relocation>
                </relocations>
                <!-- 配置不需要打包进fat Jar的依赖 -->
                <excludes>
                    <exclude>org.projectlombok:lombok</exclude>
                </excludes>
            </configuration>
        </execution>
    </executions>
</plugin>

配置完成后执行mvn package命令，插件会自动完成shading流程，最终在项目target目录下生成完成了依赖合并、包重命名的fat Jar。

内容的提问来源于stack exchange，提问作者ARK