Maven 依赖冲突解决

果酱带你啃java

发布于 2026-04-14 14:56:24

670

前言

在Java开发中，Maven依赖冲突是每个开发者都会遇到的高频痛点，轻则导致项目启动失败、抛出NoSuchMethodError等运行时异常，重则引发隐蔽的业务逻辑异常、线上服务故障。很多开发者解决冲突全靠“瞎蒙式排除”，不仅无法根治问题，还会引入更多不可控的依赖风险。

本文将从Maven依赖管理的底层原理出发，带你彻底搞懂依赖冲突的本质，掌握从本地到线上的全链路排查工具，提供从根源解决冲突的7大方案，配合可直接运行的实战案例，让你不仅能快速解决冲突，更能从源头避免冲突的发生。

一、Maven依赖管理核心原理：搞懂底层才不会瞎操作

依赖冲突的本质是Maven依赖调解规则与JVM类加载机制的共同作用，不懂底层原理，解决冲突就是无源之水。

1.1 依赖传递性：冲突的根源

Maven的核心特性之一就是依赖传递：如果项目A依赖组件B，组件B又依赖组件C，那么Maven会自动将B和C都引入项目A，无需开发者手动声明C。

正是这种传递机制，导致同一个Jar包的不同版本会通过不同的依赖路径被引入项目，最终引发版本冲突。

1.2 Maven依赖调解两大核心规则（官方标准）

当同一个Jar包出现多个版本时，Maven会按照固定的官方规则选择唯一的版本生效，这就是依赖调解，所有规则均来自Maven官方文档，无任何主观臆断。

规则1：最短路径优先（Nearest Wins）

依赖树中，距离项目路径最短的Jar版本优先生效。

示例：项目A→B→C→D(1.0)（路径长度3），项目A→E→D(2.0)（路径长度2），最终D(2.0)生效，因为路径更短。
核心逻辑：Maven认为直接声明的依赖比传递依赖的优先级更高，开发者手动控制的版本更符合预期。

规则2：声明优先（First Declaration Wins）

当多个版本的路径长度完全相同时，在pom.xml中先声明的依赖对应的版本优先生效。

注意：该规则仅在Maven 2.0.9及以上版本生效，老旧版本存在兼容性问题。
示例：项目A→B→D(1.0)（路径长度2），项目A→C→D(2.0)（路径长度2），如果pom中先声明B，D(1.0)生效；先声明C，D(2.0)生效。

1.3 依赖范围scope对传递性的影响

scope控制依赖的生命周期和传递性，错误的scope配置会引发类找不到、版本冲突等问题，核心scope的规则如下：

scope类型	编译有效	测试有效	运行时有效	能否传递	典型使用场景
compile（默认）	是	是	是	是	核心业务依赖，如spring-web
provided	是	是	否	否	运行时由容器提供，如servlet-api
runtime	否	是	是	是	仅运行时需要，如mysql驱动
test	否	是	否	否	单元测试依赖，如junit
import	-	-	-	-	仅用于dependencyManagement中导入第三方BOM

1.4 可选依赖：阻断不必要的传递

当依赖声明<optional>true</optional>时，该依赖不会被传递到下游项目，仅当前项目生效。

适用场景：开发二方库/SDK时，非核心功能的依赖标记为可选，避免下游项目引入不必要的依赖，减少冲突风险。
正确配置示例：

<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.5</version>
    <optional>true</optional>
</dependency>

1.5 冲突的本质：JVM类加载机制的唯一性

Maven依赖调解最终决定了哪些Jar包会被写入项目的ClassPath，而JVM类加载的核心规则是：同一个类加载器下，全限定名（包名+类名）完全相同的类，只会被加载一次，先加载的类会覆盖后续的同名类。

依赖冲突的本质就是：同一个全限定名的类，存在于多个不同的Jar包中，JVM加载的类版本与代码预期的版本不匹配，最终引发各类异常。

二、依赖冲突的典型类型与异常表现

2.1 两大冲突类型

类型1：同一Jar包的不同版本冲突（最常见）

同一个groupId+artifactId的Jar包，通过不同的依赖路径引入了多个不同的version，Maven按调解规则选择一个版本生效，其他版本被忽略。

典型场景：spring-core 5.3.30和6.1.5同时存在，mybatis-plus传递的旧版本与spring-boot传递的新版本冲突。

类型2：不同Jar包的同名类冲突（最隐蔽）

不同的groupId+artifactId的Jar包，内部包含了全限定名完全相同的类，Maven无法通过依赖调解识别这种冲突，最终JVM会随机加载ClassPath中靠前的Jar包中的类，引发不可预知的问题。

典型场景：spring-jcl和commons-logging都包含org.apache.commons.logging.LogFactory类，fastjson不同分支的同名类冲突。

2.2 冲突对应的典型异常

通过异常类型可以快速定位冲突场景，避免盲目排查：

NoSuchMethodError：最常见的冲突异常，代码调用了目标版本类中的方法，但加载的旧版本类中没有该方法（方法名/参数/返回值不匹配）。
NoClassDefFoundError/ClassNotFoundException：类的依赖版本不匹配，导致类初始化失败，或传递依赖被排除后无可用版本。
ClassCastException：同名类被不同类加载器加载，或接口/实现类的版本不匹配，导致类型转换失败。
LinkageError：两个版本的类签名不兼容，JVM链接类时失败。
隐蔽的业务逻辑异常：方法存在但实现逻辑发生变化，无报错但业务结果不符合预期，最难排查。

三、全链路冲突排查工具：从本地到线上全覆盖

工欲善其事必先利其器，掌握正确的排查工具，能让你10分钟定位别人1天解决不了的冲突。

3.1 Maven自带命令行工具（通用无依赖）

Maven自带的命令是最基础、最权威的排查工具，无需安装任何插件，所有环境都可使用。

3.1.1 mvn dependency:tree 核心排查命令

该命令会输出项目完整的依赖树，是排查版本冲突的首选工具，核心参数必须掌握。

基础用法

# 输出完整依赖树
mvn dependency:tree
# 排查指定Jar包的冲突，必加-Dverbose显示被忽略的版本
mvn dependency:tree -Dverbose -Dincludes=org.springframework:spring-core

核心参数详解

参数	作用	必用场景
-Dverbose	显示被调解规则忽略的冲突版本，默认仅显示生效版本	所有冲突排查场景，必加
-Dincludes=groupId:artifactId	过滤指定Jar包，支持通配符，如org.springframework:	定位单个Jar包的冲突
-Dexcludes=groupId:artifactId	排除指定Jar包，与includes相反	过滤无关依赖，聚焦核心冲突
-DoutputType=dot	输出dot格式，可配合graphviz生成可视化依赖图	复杂项目全局依赖分析

输出结果解读

[INFO] com.jam.demo:demo-web:jar:1.0.0-SNAPSHOT
[INFO] +- org.springframework.boot:spring-boot-starter-web:jar:3.2.3:compile
[INFO] |  \- org.springframework:spring-web:jar:6.1.4:compile
[INFO] |     \- org.springframework:spring-core:jar:6.1.4:compile
[INFO] \- com.baomidou:mybatis-plus-spring-boot3-starter:jar:3.5.3:compile
[INFO]    \- org.springframework:spring-jdbc:jar:5.3.30:compile
[INFO]       \- org.springframework:spring-core:jar:5.3.30:compile (version managed from 5.3.30; omitted for conflict with 6.1.4)

omitted for conflict with 6.1.4：该版本因冲突被调解规则忽略，最终生效的是6.1.4版本。
version managed from 5.3.30：该版本被父pom的dependencyManagement强制管理。

3.1.2 mvn dependency:analyze 依赖健康度检查

该命令用于分析项目的依赖使用情况，提前规避依赖风险：

mvn dependency:analyze

输出核心结果：

Used undeclared dependencies：代码中使用了但未直接声明的依赖，仅通过传递依赖引入，存在版本丢失风险，建议手动声明。
Unused declared dependencies：项目中声明了但未使用的依赖，建议排除，减少冲突概率。

3.1.3 mvn help:effective-pom 查看最终生效pom

该命令输出合并了父pom、profile、dependencyManagement后的最终生效pom，用于排查版本管理失效的问题：

mvn help:effective-pom

典型场景：子pom声明的版本未生效，通过该命令可快速定位是否被父pom的dependencyManagement覆盖。

3.2 IDEA可视化排查插件（日常开发首选）

3.2.1 Maven Helper 插件（冲突排查神器）

这是IDEA中最常用的Maven冲突排查插件，可视化操作，一键排除冲突依赖。

安装：IDEA → Plugins → 搜索Maven Helper → 安装重启。
使用：打开pom.xml，底部切换到Dependency Analyzer标签页。
核心视图：
- Conflicts（冲突视图）：直接高亮显示所有存在冲突的Jar包，红色标注冲突版本，右键可一键生成exclusion排除代码。
- All Dependencies as Tree：树形结构展示所有依赖，与命令行输出一致，支持搜索过滤。
- All Dependencies as List：列表形式展示所有依赖，方便全局查看。

3.2.2 IDEA原生依赖图

右键pom.xml → Maven → Show Dependencies（快捷键Ctrl+Alt+Shift+U），可生成全局可视化依赖图，红色连线标注冲突依赖，支持缩放、搜索、一键排除，适合复杂项目的全局依赖分析。

3.3 隐蔽冲突排查工具（同名类冲突专用）

针对不同Jar包的同名类冲突，常规的dependency:tree无法识别，必须使用专用工具。

3.3.1 duplicate-finder-maven-plugin 重复类检测插件

该插件可以扫描项目中所有全限定名重复的类，无论是否来自同一个Jar包，是排查隐蔽冲突的核心工具。

插件配置（最新稳定版）

<build>
    <plugins>
        <plugin>
            <groupId>org.basepom.maven</groupId>
            <artifactId>duplicate-finder-maven-plugin</artifactId>
            <version>1.5.0</version>
            <executions>
                <execution>
                    <id>duplicate-finder-check</id>
                    <phase>verify</phase>
                    <goals>
                        <goal>check</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <failBuildInCaseOfConflict>true</failBuildInCaseOfConflict>
                <ignoredResources>
                    <ignoredResource>META-INF/.*</ignoredResource>
                    <ignoredResource>module-info.class</ignoredResource>
                </ignoredResources>
            </configuration>
        </plugin>
    </plugins>
</build>

执行命令

# 执行重复类检查，存在冲突则构建失败
mvn verify
# 单独执行检查
mvn duplicate-finder:check

执行后会输出所有重复的类，以及对应的Jar包，精准定位同名类冲突。

3.4 线上冲突排查神器：Arthas

很多冲突本地无法复现，仅线上环境出现，Arthas是阿里开源的Java诊断工具，可以直接查看线上环境中类的加载来源，100%定位冲突根源。

核心排查命令

启动Arthas并attach到目标Java进程

# 下载Arthas
curl -O https://arthas.aliyun.com/arthas-boot.jar
# 启动并选择目标进程
java -jar arthas-boot.jar

查看类的加载来源

# 查看指定类的详细信息，包括加载的Jar包路径、版本、类加载器
sc -d org.springframework.util.StringUtils

反编译加载的类，验证方法是否存在

# 反编译指定类，查看类的实际内容，确认是否存在报错的方法
jad org.springframework.util.StringUtils

通过这两个命令，可以直接确认线上环境加载的类是否是预期的版本，彻底解决“本地正常，线上报错”的玄学冲突问题。

四、依赖冲突7大解决方案（按优先级排序）

解决冲突的核心原则是：优先从根源规避，其次精准修复，兜底极端场景，杜绝无差别exclusion的野蛮操作。

方案1：dependencyManagement统一版本管理（最优治本方案）

原理

在父pom的dependencyManagement中声明所有依赖的版本，子模块引入依赖时无需指定version，所有传递依赖都会强制使用这里声明的版本，从根源上杜绝版本冲突。

适用场景

多模块项目、团队协作项目，是大型企业级项目的标准规范。

完整配置示例

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.jam.demo</groupId>
    <artifactId>maven-demo-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <name>maven-demo-parent</name>

    <modules>
        <module>demo-web</module>
    </modules>

    <properties>
        <java.version>17</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <spring-boot.version>3.2.3</spring-boot.version>
        <mybatis-plus.version>3.5.6</mybatis-plus.version>
        <lombok.version>1.18.30</lombok.version>
        <fastjson2.version>2.0.48</fastjson2.version>
        <guava.version>33.0.0-jre</guava.version>
        <springdoc.version>2.4.0</springdoc.version>
        <mysql.version>8.3.0</mysql.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!-- Spring Boot 官方BOM，统一管理Spring全家桶版本 -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- MyBatis-Plus 官方BOM -->
            <dependency>
                <groupId>com.baomidou</groupId>
                <artifactId>mybatis-plus-bom</artifactId>
                <version>${mybatis-plus.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- 自研/第三方依赖统一声明 -->
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
                <scope>provided</scope>
            </dependency>
            <dependency>
                <groupId>com.alibaba.fastjson2</groupId>
                <artifactId>fastjson2</artifactId>
                <version>${fastjson2.version}</version>
            </dependency>
            <dependency>
                <groupId>com.google.guava</groupId>
                <artifactId>guava</artifactId>
                <version>${guava.version}</version>
            </dependency>
            <dependency>
                <groupId>org.springdoc</groupId>
                <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
                <version>${springdoc.version}</version>
            </dependency>
            <dependency>
                <groupId>com.mysql</groupId>
                <artifactId>mysql-connector-j</artifactId>
                <version>${mysql.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.12.1</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                    <encoding>${project.build.sourceEncoding}</encoding>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

子模块引用示例（无需指定version）

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.jam.demo</groupId>
        <artifactId>maven-demo-parent</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>demo-web</artifactId>
    <name>demo-web</name>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>
</project>

核心优势

版本统一管理，一处修改全项目生效，避免版本不一致。
官方BOM中的版本均经过兼容性测试，杜绝不兼容的版本组合。
子模块无需关注版本号，减少人为配置错误。

方案2：直接声明目标版本（次优优雅方案）

原理

利用Maven最短路径优先规则，直接在项目pom中声明你需要的目标版本，该依赖的路径长度为1，比所有传递依赖的路径都短，会强制覆盖传递进来的其他版本。

适用场景

单模块项目、无需修改父pom、仅需指定单个Jar包版本的场景，比exclusion更优雅，无需修改其他依赖的配置。

示例

项目中spring-boot-starter-web传递了spring-core 6.1.4，但需要使用修复了漏洞的6.1.5版本，直接在pom中声明：

<dependencies>
    <!-- 直接声明目标版本，路径长度1，优先生效 -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-core</artifactId>
        <version>6.1.5</version>
    </dependency>
    <!-- 其他依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>3.2.3</version>
    </dependency>
</dependencies>

注意事项

声明的版本必须与项目中的其他依赖兼容，禁止跨大版本声明（如Spring Boot 2.x不能声明spring-core 6.x），否则会引发更严重的兼容性问题。

方案3：排除冲突的传递依赖（精准修复方案）

原理

在引入依赖时，通过<exclusions>标签排除该依赖传递进来的冲突Jar包，仅保留项目中已有的正确版本。

适用场景

某个依赖传递了冲突的版本，其他依赖传递的版本是正确的，仅需精准排除冲突版本。

正确示例

mybatis-plus传递了旧版本的spring-jdbc，与spring-boot的新版本冲突，精准排除：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.6</version>
    <!-- 排除冲突的传递依赖 -->
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-jdbc</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-tx</artifactId>
        </exclusion>
    </exclusions>
</dependency>

关键注意事项

<exclusion>中不需要写version，仅需指定groupId和artifactId，会排除该依赖传递的所有版本。
禁止使用通配符*批量排除groupId/artifactId，会导致不可预知的类丢失问题。
排除前必须确认项目中已有该依赖的正确版本，否则会引发ClassNotFoundException。

方案4：调整依赖声明顺序（兜底方案）

原理

利用Maven声明优先规则，当多个冲突版本的路径长度相同时，先声明的依赖对应的版本会生效。

适用场景

两个依赖传递了相同路径长度的冲突版本，仅需调整声明顺序即可指定生效版本，无需修改其他配置。

示例

项目中A依赖传递D(1.0)，B依赖传递D(2.0)，路径长度均为2，需要D(2.0)生效，将B的声明放在A前面：

<dependencies>
    <!-- 先声明B，其传递的D(2.0)优先生效 -->
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>B</artifactId>
        <version>1.0.0</version>
    </dependency>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>A</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

注意事项

该方案为兜底方案，不推荐作为主要解决方案，因为pom的依赖顺序可能被其他开发者修改，导致冲突复现，稳定性远不如直接声明版本或排除。

方案5：可选依赖标记（二方库/SDK开发必备）

原理

将非核心依赖标记为<optional>true</optional>，阻断依赖传递，避免下游项目引入不必要的依赖，从源头减少下游的冲突风险。

适用场景

开发二方库、SDK、公共组件时，非核心功能的依赖必须标记为可选。

示例

SDK中Excel处理功能依赖poi，非所有下游项目都需要，标记为可选：

<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.5</version>
    <optional>true</optional>
</dependency>

下游项目需要使用Excel功能时，手动引入poi即可，不会自动传递，避免版本冲突。

方案6：调整依赖scope（减少不必要的传递）

原理

通过调整scope，阻断非必要依赖的传递，避免与运行环境中的依赖冲突。

典型示例

servlet-api仅在编译时需要，运行时由Tomcat容器提供，设置scope为provided，不会被传递，避免与容器中的版本冲突：

<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>

lombok仅在编译时生效，设置scope为provided，不会被打包和传递，符合规范。

方案7：类加载器隔离（终极兜底方案）

原理

JVM中，不同类加载器加载的同名类是相互隔离的，即使全限定名相同，也不会互相影响。通过自定义类加载器，将冲突的不同版本Jar包用不同的类加载器加载，解决无法兼容的版本冲突。

适用场景

极端场景：项目必须同时使用同一个Jar的两个不兼容版本（如同时需要fastjson 1.x和fastjson2、spring 3.x和spring 6.x），无法通过上述方案解决。

常用实现方案

阿里SOFA-ARK：开箱即用的类隔离框架，基于Ark Plugin实现插件化隔离，无需自定义类加载器。
Spring Boot 分层类加载器：利用LaunchedURLClassLoader实现不同Jar包的隔离加载。
自定义ClassLoader：重写findClass方法，实现指定Jar包的隔离加载。

注意事项

类隔离会大幅增加项目的复杂度，提升排查和运维成本，不到万不得已禁止使用，优先选择上述6种方案。

五、全场景实战案例

案例1：最常见的同Jar多版本冲突，引发NoSuchMethodError

场景描述

Spring Boot 3.2.3项目，引入spring-boot-starter-web和mybatis-plus，启动时报错：

java.lang.NoSuchMethodError: 'boolean org.springframework.util.StringUtils.hasText(java.lang.String, java.lang.String)'

问题根源

spring-boot-starter-web 3.2.3传递了spring-core 6.1.4，该版本包含带两个参数的hasText方法。
旧版本mybatis-plus 3.5.3传递了spring-core 5.3.30，该版本无此方法。
两个版本路径长度相同，pom中先声明了mybatis-plus，最终生效的是5.3.30版本，导致方法找不到。

排查过程

执行冲突排查命令，定位冲突版本：

mvn dependency:tree -Dverbose -Dincludes=org.springframework:spring-core

输出结果显示spring-core 5.3.30被声明优先，6.1.4被忽略。
用Maven Helper插件的Conflicts视图，确认冲突来源。

解决方案（方案2：直接声明目标版本）

在pom中直接声明spring-core 6.1.4版本，利用最短路径优先规则强制生效：

<dependencies>
    <!-- 直接声明目标版本，优先生效 -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-core</artifactId>
        <version>6.1.4</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>3.2.3</version>
    </dependency>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        <version>3.5.3</version>
    </dependency>
    <!-- 其他依赖 -->
</dependencies>

验证代码（JDK17）

package com.jam.demo.controller;

import com.jam.demo.common.Result;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * 测试控制器
 *
 * @author ken
 * @date 2024-02-28
 */
@Slf4j
@RestController
@RequestMapping("/test")
@Tag(name = "测试接口", description = "依赖冲突验证接口")
publicclass TestController {

    /**
     * 字符串非空校验接口
     *
     * @param input 输入字符串
     * @return 校验结果
     */
    @GetMapping("/check")
    @Operation(summary = "字符串非空校验", description = "验证StringUtils.hasText方法，确认依赖冲突是否解决")
    public Result<Boolean> checkInput(
            @Parameter(description = "输入字符串", required = true) @RequestParam String input) {
        log.info("收到校验请求，输入内容：{}", input);
        // 调用冲突方法，验证是否正常执行
        boolean isValid = StringUtils.hasText(input);
        return Result.success(isValid);
    }
}

package com.jam.demo.common;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.io.Serializable;

/**
 * 通用返回结果类
 *
 * @author ken
 * @date 2024-02-28
 */
@Data
@Schema(description = "通用返回结果")
publicclass Result<T> implements Serializable {

    privatestaticfinallong serialVersionUID = 1L;

    @Schema(description = "响应码", example = "200")
    privateint code;

    @Schema(description = "响应消息", example = "操作成功")
    private String msg;

    @Schema(description = "响应数据")
    private T data;

    /**
     * 成功返回结果
     *
     * @param data 返回数据
     * @param <T>  数据类型
     * @return 通用返回结果
     */
    publicstatic <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(200);
        result.setMsg("操作成功");
        result.setData(data);
        return result;
    }

    /**
     * 失败返回结果
     *
     * @param msg 错误消息
     * @param <T>  数据类型
     * @return 通用返回结果
     */
    publicstatic <T> Result<T> fail(String msg) {
        Result<T> result = new Result<>();
        result.setCode(500);
        result.setMsg(msg);
        return result;
    }
}

修复后项目可正常启动，接口正常调用，无报错。

案例2：隐蔽的同名类冲突，引发ClassCastException

场景描述

项目启动时报错：

java.lang.ClassCastException: class org.apache.commons.logging.impl.SLF4JLogFactory cannot be cast to class org.apache.commons.logging.LogFactory

问题根源

项目中同时引入了commons-logging和spring-jcl两个Jar包，两者都包含全限定名完全相同的org.apache.commons.logging.LogFactory类，JVM加载了commons-logging中的类，与spring-jcl的实现不兼容，导致类型转换失败。

排查过程

执行mvn dependency:tree未发现同Jar版本冲突。
配置duplicate-finder-maven-plugin，执行检查，发现同名类冲突。
用Arthas的sc -d org.apache.commons.logging.LogFactory命令，确认类加载自commons-logging.jar。

解决方案（方案3：排除冲突依赖）

spring-jcl已经实现了commons-logging的所有功能，无需额外引入commons-logging，在引入的依赖中排除commons-logging：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>xxx-sdk</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>commons-logging</groupId>
            <artifactId>commons-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

修复后项目正常启动，无类型转换异常。

六、Maven依赖管理最佳实践（从源头避免冲突）

必须使用dependencyManagement+BOM统一管理版本，禁止子模块随意指定version，优先使用官方维护的BOM，如Spring Boot、MyBatis-Plus的官方BOM。
最小依赖原则，仅引入项目必需的依赖，禁止引入未使用的依赖，定期用mvn dependency:analyze清理无用依赖。
二方库/SDK开发必须使用optional标记非核心依赖，禁止传递不必要的依赖给下游项目。
禁止无差别批量排除依赖，所有exclusion必须精准对应冲突的Jar包，禁止使用通配符排除。
统一框架大版本，禁止混用不同大版本的框架，如Spring Boot 2.x与3.x、Spring 5.x与6.x，避免不兼容的breaking change。
升级依赖优先整体升级，而非补丁式排除，如Spring全家桶统一升级到同一个大版本，确保兼容性。
提交代码前必须执行校验，运行mvn clean package确保项目正常编译，mvn dependency:tree检查无冲突，禁止将冲突代码提交到仓库。
线上环境预留排查能力，保留pom.xml和依赖树信息，部署Arthas等诊断工具，方便线上冲突快速定位。

七、常见误区答疑

误区1：先声明优先是Maven的第一调解规则正解：Maven官方第一规则是最短路径优先，仅当路径长度相同时，才会触发声明优先规则，很多开发者搞反了顺序，导致排查方向错误。
误区2：exclusion写的越多，项目越稳定正解：无差别的exclusion会导致依赖树混乱，后续升级依赖时极易出现类丢失问题，优先使用统一版本管理和直接声明版本，减少exclusion的使用。
误区3：dependency:tree没显示冲突，就不会有依赖冲突正解：dependency:tree只能识别同一groupId+artifactId的版本冲突，无法识别不同Jar包的同名类冲突，必须使用duplicate-finder插件才能检测。
误区4：用了Spring Boot就不会有依赖冲突正解：Spring Boot仅管理了官方starter的依赖版本，第三方二方库/SDK传递的依赖不在其管理范围内，依然会出现版本冲突。
误区5：scope=provided的依赖不会出现在依赖树中正解：provided的依赖会出现在依赖树中，仅不会被打包到最终产物中，也不会向下游传递。