Java 中怎么在 Maven 中使用 shade 插件打包并重命名依赖类（Relocation）-java教程-PHP中文网

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

使用maven-shade-plugin的功能可重命名冲突依赖包路径，如将org.bouncycastle.改为com.yourcompany.shaded.bc.，新建shading模块单独处理、限定子包范围、验证类路径变更后，主项目直接引入shaded包即可隔离类冲突。

java 中怎么在 maven 中使用 shade 插件打包并重命名依赖类（relocation）

在 Maven 中使用 shade 插件打包并重命名依赖类（即 Relocation），主要是为了解决依赖冲突，或把第三方库“私有化”嵌入到你的 jar 中，避免与宿主环境的同名类冲突。核心是通过 relocations 配置，将原始包路径映射为新路径。

1. 添加 maven-shade-plugin 插件

在 pom.xml 的 <build><plugins></plugins></build> 中加入 shade 插件（推荐使用较新稳定版，如 3.4.1+）：

<plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-shade-plugin</artifactid><version>3.4.1</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration><!-- 关键：配置 relocation --><relocations><relocation><pattern>com.google.common.</pattern><shadedpattern>myapp.shaded.guava.</shadedpattern></relocation><relocation><pattern>org.slf4j.</pattern><shadedpattern>myapp.shaded.slf4j.</shadedpattern></relocation></relocations><pre class="brush:java;toolbar:false;">    <!-- 可选：指定主类，生成可执行 jar -->
    <transformers>
      <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
        <mainClass>com.example.MyApp</mainClass>
      </transformer>
    </transformers>

    <!-- 可选：避免 META-INF 签名冲突 -->
    <filters>
      <filter>
        <artifact>*:*)</artifact>
        <excludes>
          <exclude>META-INF/*.SF</exclude>
          <exclude>META-INF/*.DSA</exclude>
          <exclude>META-INF/*.RSA</exclude>
        </excludes>
      </filter>
    </filters>
  </configuration>
</execution>

2. Relocation 的作用和规则

Relocation 不是简单地“改名文件”，而是：在打包时重写字节码中的类引用、常量池、签名等所有涉及原始包路径的位置，确保运行时加载的是你重命名后的新类。

pattern 是要匹配的原始包前缀（必须以 . 结尾，如 com.google.common.）
shadedPattern 是替换成的新前缀（也建议以 . 结尾）
匹配是前缀匹配，所以 pattern="org.apache.commons.lang3." 会重定位 org.apache.commons.lang3.StringUtils 和其子包下所有类
多个 relocation 按声明顺序处理，不支持通配符或正则表达式（仅前缀匹配）

3. 注意事项和常见问题

Relocation 功能强大但容易出错，以下几点务必留意：

被 relocation 的依赖必须是 compile 或 runtime 范围 —— provided 或 test 依赖不会被打进 shade jar，自然也不会被重命名
某些框架（如 Spring、Logback）会在运行时通过反射或资源加载查找类（如 META-INF/spring.factories、logback.xml 中的类名），这些字符串不会被自动重写，需手动修改或使用 ResourceTransformer 处理
若依赖中含 JNI 库或 native 资源，shade 不处理二进制文件路径，relocation 对它们无效
建议配合 <minimizejar>true</minimizejar> 减小体积（慎用，可能误删反射调用的类）

4. 验证 relocation 是否生效

打包完成后（mvn clean package），检查生成的 target/*.jar：

用 jar -tvf your-app-1.0.jar | grep guava 查看是否出现 myapp/shaded/guava/ 目录
反编译一个被 relocation 的类（如 myapp.shaded.guava.base.Preconditions），确认其内部引用的其他 guava 类是否也已变成 myapp.shaded.guava.xxx
运行程序，观察日志或异常堆栈是否显示重命名后的包路径

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南