7.2 依赖冲突解决策略

7.2 依赖冲突解决策略

7.2 依赖冲突解决策略

在 Maven 项目的开发过程中，依赖管理是至关重要的一环。Maven 强大的依赖管理功能极大地简化了项目构建和依赖维护。然而，随着项目规模的扩大和依赖的增多，依赖冲突问题也变得不可避免。当项目中引入多个依赖，并且这些依赖间接或直接地依赖于同一个库的不同版本时，就会发生依赖冲突。这种冲突可能导致运行时错误、版本不兼容、甚至项目构建失败。

7.2.1 理解依赖冲突

在深入解决方案之前，我们首先需要理解依赖冲突的本质和产生原因。

7.2.1.1 什么是依赖冲突？

依赖冲突是指在 Maven 项目的依赖树中，同一个依赖库出现了多个不同的版本。例如，你的项目直接依赖了库 A 的 1.0 版本，同时又通过另一个依赖库 B 间接依赖了库 A 的 2.0 版本。此时，Maven 需要决定最终使用哪个版本的库 A。

7.2.1.2 依赖冲突的产生原因

依赖冲突通常由以下两种情况引起：

• 传递性依赖冲突 (Transitive Dependency Conflict): 这是最常见的冲突类型。当你的项目直接依赖的库 (例如库 B) 本身也依赖于其他库 (例如库 A) 时，就会引入传递性依赖。如果多个直接依赖的库都传递性地依赖于同一个库的不同版本，就会产生冲突。

• 直接依赖冲突 (Direct Dependency Conflict): 虽然相对少见，但也有可能发生。例如，你在 pom.xml 文件中显式地声明了同一个库的两个不同版本。Maven 通常会警告这种配置，但仍然需要解决冲突。

7.2.1.3 依赖冲突的危害

依赖冲突可能导致以下问题：

• ClassNotFoundException 或 NoSuchMethodError 等运行时错误: 当程序在运行时尝试使用一个版本库的 API，但实际加载的是另一个版本库时，可能会出现这些错误。

• 版本不兼容性问题: 不同版本的库可能存在 API 变更或行为差异，导致程序功能异常或崩溃。

• 难以调试和排查问题: 依赖冲突引起的错误往往难以追踪，因为问题可能隐藏在深层依赖关系中。

• 项目构建不稳定: 在某些情况下，依赖冲突甚至可能导致 Maven 构建过程失败。

为了更好地理解依赖冲突，我们可以用一个 Mermaid graph TD 图来可视化一个简单的传递性依赖冲突场景：

在这个图中，项目 A 直接依赖了库 B 和库 D。库 B 依赖于库 C 的 1.0 版本，而库 D 依赖于库 C 的 2.0 版本。这就产生了库 C 的版本冲突。Maven 需要决定最终使用 C:1.0 还是 C:2.0。

7.2.2 Maven 默认的冲突解决策略：最近原则 (Nearest Wins)

Maven 默认的依赖冲突解决策略是 “最近原则” (Nearest Wins)。这意味着 Maven 会选择 依赖路径最短 的版本作为最终使用的版本。

7.2.2.1 最近原则的原理

当 Maven 解析依赖树时，它会计算每个依赖的版本到项目的距离 (依赖路径的长度)。对于同一个依赖库的多个版本，Maven 会选择距离项目最近的版本，即依赖路径最短的版本。

在上面的 Mermaid 图例中，假设库 B 和库 D 都是项目 A 的直接依赖，那么它们到项目 A 的距离都是 1。此时，Maven 会进一步比较 B 和 D 在 pom.xml 文件中的声明顺序 (先声明的优先)。如果 B 在 D 之前声明，那么 Maven 可能会选择 C:1.0 版本，因为它是通过路径 A -> B -> C:1.0 到达的，而 C:2.0 是通过路径 A -> D -> C:2.0 到达的。

7.2.2.2 最近原则的局限性

虽然最近原则在很多情况下能够解决依赖冲突，但它也存在一些局限性：

• 可能选择不兼容的版本: 最近的版本并不一定是最佳版本。例如，C:1.0 版本可能存在 bug 或者与项目代码不兼容，而 C:2.0 版本才是更合适的选择。

• 依赖声明顺序的影响: 依赖声明的顺序会影响冲突解决结果，这可能会导致项目构建的不确定性。

• 无法解决所有冲突: 在某些复杂的依赖场景下，最近原则可能无法找到一个合适的版本，或者选择的版本仍然会导致运行时问题。

7.2.2.3 代码实践：最近原则示例

我们创建一个简单的 Maven 项目来演示最近原则。

项目结构：

dependency-conflict-example/
├── pom.xml
└── src/main/java/com/example/Main.java
​

父 POM (dependency-conflict-example/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>dependency-conflict-example</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <modules>
        <module>module-a</module>
        <module>module-b</module>
        <module>module-main</module>
    </modules>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.google.guava</groupId>
                <artifactId>guava</artifactId>
                <version>20.0</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
​

模块 A (dependency-conflict-example/module-a/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>dependency-conflict-example</artifactId>
        <groupId>com.example</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>module-a</artifactId>
    <dependencies>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.8.5</version>
        </dependency>
    </dependencies>
</project>
​

模块 B (dependency-conflict-example/module-b/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>dependency-conflict-example</artifactId>
        <groupId>com.example</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>module-b</artifactId>
    <dependencies>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.9.0</version>
        </dependency>
    </dependencies>
</project>
​

主模块 (dependency-conflict-example/module-main/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>dependency-conflict-example</artifactId>
        <groupId>com.example</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>module-main</artifactId>
    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>module-a</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>module-b</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
</project>
​

主模块代码 (dependency-conflict-example/module-main/src/main/java/com/example/Main.java):

package com.example;
import com.google.gson.Gson;
public class Main {
    public static void main(String[] args) {
        Gson gson = new Gson();
        System.out.println("Gson version: " + gson.getClass().getPackage().getImplementationVersion());
    }
}
​

在这个示例中，module-a 依赖 gson:2.8.5，module-b 依赖 gson:2.9.0，module-main 同时依赖 module-a 和 module-b。运行 module-main 的 Main 类，观察输出的 Gson 版本。

运行 mvn dependency:tree 命令查看依赖树：

在 module-main 目录下运行 mvn dependency:tree 命令，可以看到依赖树信息。在输出中，你会发现 Gson 的版本被解析为 2.8.5 (或 2.9.0，取决于 module-a 和 module-b 在 module-main 的 pom.xml 中声明的顺序)。

解释：

Maven 应用最近原则，选择了依赖路径最短的 Gson 版本。由于 module-a 和 module-b 都是 module-main 的直接依赖，它们的依赖路径长度相同。在这种情况下，Maven 通常会按照 pom.xml 中依赖声明的顺序选择先声明的依赖的版本。

注意: 最近原则的结果可能受到依赖声明顺序的影响，这在复杂项目中可能会带来不确定性。因此，仅仅依赖最近原则来解决所有冲突是不够的，我们需要更明确的策略来控制依赖版本。

7.2.3 使用 <dependencyManagement> 管理依赖版本

<dependencyManagement> 是 Maven 提供的一种强大的依赖版本管理机制。它允许你在父 POM 中集中定义依赖的版本信息，子模块可以继承这些版本定义，从而实现依赖版本的一致性管理和冲突解决。

7.2.3.1 <dependencyManagement> 的作用

• 集中管理依赖版本: 在父 POM 的 <dependencyManagement> 标签中定义依赖的版本，子模块只需要声明依赖的 groupId 和 artifactId，版本信息会自动从父 POM 中继承。

• 统一项目依赖版本: 通过在父 POM 中统一管理版本，可以确保整个项目中同一个依赖库只使用一个版本，避免版本不一致导致的冲突。

• 方便版本升级和维护: 当需要升级依赖版本时，只需要修改父 POM 中的 <dependencyManagement> 配置，所有子模块都会自动应用新的版本，大大简化了版本维护工作。

7.2.3.2 <dependencyManagement> 的使用方法

在父 POM 的 <dependencyManagement> 标签中，你可以像在 <dependencies> 标签中一样声明依赖，但只需要指定 groupId、artifactId 和 version 即可。子模块在 <dependencies> 中声明依赖时，如果 groupId 和 artifactId 与父 POM 中 <dependencyManagement> 定义的依赖匹配，则会自动继承父 POM 中定义的版本。

7.2.3.3 代码实践：使用 <dependencyManagement> 解决冲突

修改上面的示例项目，使用 <dependencyManagement> 来管理 Gson 版本。

父 POM (dependency-conflict-example/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>dependency-conflict-example</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <modules>
        <module>module-a</module>
        <module>module-b</module>
        <module>module-main</module>
    </modules>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.google.guava</groupId>
                <artifactId>guava</artifactId>
                <version>20.0</version>
            </dependency>
            <dependency>
                <groupId>com.google.code.gson</groupId>
                <artifactId>gson</artifactId>
                <version>2.9.0</version>  <!-- 在父 POM 中统一管理 Gson 版本为 2.9.0 -->
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
​

模块 A (dependency-conflict-example/module-a/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>dependency-conflict-example</artifactId>
        <groupId>com.example</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>module-a</artifactId>
    <dependencies>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <!--  移除版本信息，继承父 POM 的版本管理 -->
        </dependency>
    </dependencies>
</project>
​

模块 B (dependency-conflict-example/module-b/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>dependency-conflict-example</artifactId>
        <groupId>com.example</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>module-b</artifactId>
    <dependencies>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <!-- 移除版本信息，继承父 POM 的版本管理 -->
        </dependency>
    </dependencies>
</project>
​

主模块 (dependency-conflict-example/module-main/pom.xml) 和代码 (Main.java) 保持不变。

运行 mvn dependency:tree 命令查看依赖树：

在 module-main 目录下运行 mvn dependency:tree 命令，可以看到依赖树信息。此时，你会发现 Gson 的版本被统一解析为 2.9.0，这是我们在父 POM 的 <dependencyManagement> 中指定的版本。

解释：

通过在父 POM 的 <dependencyManagement> 中定义 Gson 的版本为 2.9.0，我们强制项目的所有模块 (包括 module-a、module-b 和 module-main) 都使用 Gson 2.9.0 版本，从而有效地解决了 Gson 版本冲突问题。

Mermaid 图示 <dependencyManagement> 的作用：

在这个图中，父 POM 的 <dependencyManagement> 定义了库 C 的版本为 2.0。模块 B 和模块 D 都依赖库 C，但它们没有在自己的 pom.xml 中指定版本。因此，它们都继承了父 POM 中 <dependencyManagement> 定义的版本，最终都使用库 C 的 2.0 版本，避免了版本冲突。

7.2.3.4 <dependencyManagement> 的优先级

• 子模块 <dependencies> 中显式声明的版本优先级最高: 如果在子模块的 <dependencies> 标签中显式声明了依赖的版本，则会覆盖父 POM <dependencyManagement> 中定义的版本。

• 父 POM <dependencyManagement> 定义的版本优先级次之: 如果子模块没有显式声明版本，则会继承父 POM <dependencyManagement> 中定义的版本。

• 最近原则优先级最低: 如果父 POM 没有 <dependencyManagement> 定义，且子模块也没有显式声明版本，则 Maven 会使用默认的最近原则来解决冲突。

最佳实践: 建议在多模块 Maven 项目中，尽可能地使用 <dependencyManagement> 在父 POM 中集中管理依赖版本。这可以提高依赖版本管理的效率和可维护性，并有效地避免依赖冲突问题。

7.2.4 使用 <exclusions> 排除传递性依赖

在某些情况下，我们可能需要排除某个传递性依赖，以解决依赖冲突或者避免引入不需要的库。Maven 提供了 <exclusions> 标签，允许你在依赖声明中排除特定的传递性依赖。

7.2.4.1 <exclusions> 的作用

• 排除传递性依赖: 可以精确地排除某个依赖库的传递性依赖，防止不需要的库被引入到项目中。

• 解决传递性依赖冲突: 当传递性依赖引入了不兼容的版本时，可以使用 <exclusions> 排除冲突的版本，并显式引入需要的版本。

• 减少项目依赖大小: 排除不必要的传递性依赖可以减小项目最终的依赖包大小。

7.2.4.2 <exclusions> 的使用方法

在 <dependency> 标签中，可以添加 <exclusions> 子标签。在 <exclusions> 标签中，可以声明要排除的依赖的 groupId 和 artifactId。

7.2.4.3 代码实践：使用 <exclusions> 排除传递性依赖

假设我们的 module-a 模块依赖了库 X，而库 X 又传递性地依赖了库 Y 的 1.0 版本。我们发现库 Y 的 1.0 版本与项目的其他依赖不兼容，我们需要排除库 Y 的 1.0 版本，并显式引入库 Y 的 2.0 版本。

修改模块 A (dependency-conflict-example/module-a/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>dependency-conflict-example</artifactId>
        <groupId>com.example</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>module-a</artifactId>
    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>module-x</artifactId> <!-- 假设 module-x 传递性依赖了库 Y:1.0 -->
            <version>1.0-SNAPSHOT</version>
            <exclusions>
                <exclusion>
                    <groupId>com.example</groupId> <!-- 假设库 Y 的 groupId 是 com.example -->
                    <artifactId>module-y</artifactId> <!-- 假设库 Y 的 artifactId 是 module-y -->
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>module-y</artifactId> <!-- 显式引入需要的库 Y 的 2.0 版本 -->
            <version>2.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
</project>
​

模块 X (dependency-conflict-example/module-x/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>module-x</artifactId>
    <version>1.0-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>module-y</artifactId>
            <version>1.0-SNAPSHOT</version> <!-- module-x 传递性依赖 module-y:1.0 -->
        </dependency>
    </dependencies>
</project>
​