本文详细阐述了如何利用 Maven Assembly Plugin 覆盖 Java 库中的现有类。当尝试打包一个包含自定义修改的应用程序时，Maven Assembly Plugin 可能会因类名冲突而跳过自定义类。文章将介绍通过配置 `archiverConfig` 中的 `duplicateBehavior` 属性，并结合使用特定版本的插件，来强制包含并优先使用自定义类，从而实现对闭源或第三方库的有效扩展和定制。
在 Java 开发中，尤其是在需要对现有闭源产品或第三方库进行局部功能扩展、UI 定制（如实现“暗黑模式”）或 bug 修复时，开发者常常会遇到需要覆盖特定库类的情况。在集成开发环境（IDE）中，由于其灵活的 classpath 管理机制，通常能够很容易地让开发者自定义的同名类优先于依赖库中的原始类加载。然而，当尝试使用 Maven Assembly Plugin 打包成一个可独立运行的 JAR 包时，这一过程可能会遇到挑战。
Maven Assembly Plugin 的默认行为与冲突
Maven Assembly Plugin 的 jar-with-dependencies 描述符在构建聚合 JAR 包时，会将所有依赖及其自身的类文件解压并重新打包。如果项目中存在与依赖库中同名的类，插件的默认行为（通常是 duplicateBehavior 为 skip）会导致它在遇到重复文件时，只保留第一个，而跳过后续的重复文件。这通常意味着，你的自定义类会被依赖库中的原始类覆盖，导致打包后的应用程序无法使用你的修改。
错误信息通常表现为 already added, skipping，明确指出插件正在跳过重复的类文件。要解决这个问题，我们需要调整 Maven Assembly Plugin 处理重复文件的策略。
解决方案：配置 duplicateBehavior
Maven Assembly Plugin 提供了 archiverConfig 配置块，允许我们更精细地控制底层文件归档工具（Plexus Archiver）的行为。其中，duplicateBehavior 属性是解决类覆盖冲突的关键。
通过将 duplicateBehavior 设置为 add，我们指示插件不要跳过重复文件，而是尝试将所有重复文件都添加到归档中。在实际操作中，当多个同名类文件被添加到 JAR 包中时，通常是最后添加的那个或者在 classpath 中位置靠前的那个会被 Java 类加载器优先加载。在 Maven Assembly Plugin 的 jar-with-dependencies 场景下，结合 add 行为，可以有效确保你的自定义类被包含并最终生效。
关键版本要求
需要特别注意的是，此功能或其稳定性可能依赖于 Maven Assembly Plugin 的特定版本。根据经验，使用较旧的版本（例如 2.2-beta5）可能会遇到缺陷或不支持此行为。因此，强烈建议使用 Maven Assembly Plugin 3.4.2 或更高版本，以确保 duplicateBehavior 配置能够正常工作。
示例配置
以下是实现类覆盖的 Maven Assembly Plugin 配置示例：
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>3.4.2</version> <!-- 确保使用3.4.2或更高版本 -->
<configuration>
<archive>
<manifest>
<mainClass>MyLittleLaucher</mainClass> <!-- 指定你的主类 -->
</manifest>
</archive>
<descriptorRefs>
<descriptorRef>jar-with-dependencies</descriptorRef>
</descriptorRefs>
<archiverConfig>
<!-- 关键配置：允许添加重复文件，从而实现自定义类的覆盖 -->
<duplicateBehavior>add</duplicateBehavior>
</archiverConfig>
</configuration>
<executions>
<execution>
<id>make-assembly</id> <!-- 随意命名，用于区分执行 -->
<phase>package</phase> <!-- 在打包阶段执行 -->
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>配置详解
-
maven-assembly-plugin : 指定使用 Maven Assembly Plugin。 -
3.4.2 : 务必指定 3.4.2 或更高版本，以确保 duplicateBehavior 的可靠性。 -
: 插件的配置容器。 -
: 配置 JAR 包的归档属性。 -
: 配置 JAR 包的 manifest 文件。 -
ainClass>MyLittleLaucher : 指定你的应用程序的入口主类。
-
-
-
: 指定用于生成聚合 JAR 包的描述符。 -
jar-with-dependencies : 这是一个标准的描述符，用于创建一个包含所有项目依赖的单个 JAR 包。
-
-
: 这是本解决方案的核心，用于配置底层归档器。 -
add : 将此属性设置为 add。它告诉归档器，当遇到同名文件时，不要跳过，而是尝试将它们都包含进来。在 jar-with-dependencies 的上下文中，这通常意味着你的自定义类将被成功添加到 JAR 中，并在类加载时优先被识别。
-
-
-
: 配置插件的执行。 -
: 定义一个执行目标。 -
make-assembly : 执行的唯一标识符。 -
package : 指定在 Maven 的 package 生命周期阶段执行此插件。 -
goals>
single : 指定执行 single 目标，即生成一个独立的聚合 JAR 包。
-
-
注意事项与最佳实践
- 谨慎覆盖： 覆盖库类是一种强大的机制，但应谨慎使用。它可能导致与库未来版本的兼容性问题，并使代码难以维护和理解。在可能的情况下，优先考虑通过扩展、组合或依赖注入等更“侵入性”较低的方式进行修改。
- 测试彻底： 无论何时覆盖库类，都必须进行彻底的测试，以确保你的修改按预期工作，并且没有引入新的问题或破坏现有功能。
- 文档记录： 详细记录你所做的覆盖，包括覆盖了哪些类、覆盖的原因以及预期行为，这对于团队协作和未来的维护至关重要。
- 理解类加载： 深入理解 Java 的类加载机制有助于你更好地预测和调试类覆盖相关的问题。
总结
通过在 Maven Assembly Plugin 的配置中设置 archiverConfig 下的 duplicateBehavior 为 add，并确保使用 3.4.2 或更高版本的插件，开发者可以有效地解决在构建聚合 JAR 包时，自定义类被依赖库中的同名类覆盖的问题。这一策略使得对现有 Java 库进行定制和扩展变得可行，为实现特定的应用需求提供了灵活的解决方案。然而，在使用此方法时，务必遵循最佳实践，确保代码的稳定性、可维护性和兼容性。
