Maven依赖冲突问题排查经验

木小丰 2021年11月13日 1,521次浏览

一、背景

在日常的开发中,排查问题是一个合格Java开发者的的基本能力。对于常见的NullPointerException,NoClassDefFoundError等问题一般通过google直接就能找到答案。

不过还有一些异常情况不是那么直观,google一般搜不到有效的信息,就需要深入研究排查。新人遇到这类问题,往往一脸懵逼,不知如何下手,请教高手,高手如果只是简单指导一个方向,新人踩过几个坑没解决后会更加沮丧。甚至怀疑自己遇到一个神秘的无法解决的bug。有经验的开发往往也不能一眼就看出问题的修复方案,但是排查问题多了会有大概的思路,需要沉下心来不断的踩坑、爬坑,最终才能定位解决问题。

本文以Maven构建工具为例,从原理、思路、工具、实践几方面分享Java中复杂jar包依赖问题排查经验。

二、Maven依赖问题的表现形式

1、老项目

  • 一般是新引入了一个jar包,导致项目启动不起来
  • 原来的服务好好的,新的改动不涉及这块,但是新改动代码后突然报错了

2、新项目

  • 日志问题:众所周知,jar生态的日志包及其混乱,同一套日志组件,不同版本之间也可能会带来问题
  • 组件整合问题:各组件底层依赖jar包版本不一致,导致问题。最麻烦的是不兼容的依赖。

三、问题排查策略

1、基础知识:Maven依赖传递策略

compile (编译范围):默认策略;编译,测试,运行,打包都能用

provided (已提供范围):编译,测试可用,不会打包到package包中。大部分情况下需要底层环境提供,比如tomcat服务中已经内置了servlet包,代码写代码时需要调用servlet的类

runtime (运行时范围):只有运行时才可用,但在编译的时候不需要。比如,你可能在编译的时候只需要JDBC API JAR,而只有在运行的时候才需要JDBC驱动实现。

test (测试范围):test范围依赖在编译和运行时都不需要,它们只有在测试编译和测试运行阶段可用。

system (系统范围):system范围依赖与provided 类似,但是你必须显式的提供一个对于本地系统中JAR 文件的路径。适合maven中央仓库中不存在jar包引用。

2、基础知识:Maven依赖树的解析规则

(1)深入优先原则

深度优先遍历依赖,并缓存节点剪枝。比如下图:

  • A→B→D→E/F
  • A→C→D

在第二步A→C→D时,由于节点D已经被缓存,所以会立即返回,不必再次遍历E/F,避免重复搜索。

image-20211113200514057
(2)短路径优先原则

比如下图 A 通过 B 和 D 引入了 1.0 版本的 E,同时 A 通过 C 引入了 2.0 版本的 E。针对这种多个版本构建依赖时,Maven 采用短路径优先原则,即 A 会依赖 2.0 版本的 E。如果想引入 1.0 版本的 E,需要直接在 A 的 pom 中声明 E 的版本。

image-20211113200742469
(3)依赖循环

maven中禁止有循环依赖。比如A 依赖了 B,同时 B 又依赖了 A。这种循环依赖可能不会直接显现,但是会在一个很长的调用关系显现出来

(4)Maven多模块问题

B模块依赖A模块,A模块的依赖修改了,需要install一下,B模块才能感知到最新的依赖。

3、工具

(1)日志

开发环境,建议默认日志级别设置为info,对需要关注的模块,建议设置为debug模式,比如当前工程目录,正在联调的依赖jar包。

如果异常无法定位,第一反应应该是添加日志。

(2)maven命令行

添加以下有空的命令行参数:

  • -e 出错日志

  • -X 打印debug日志

  • -q 只打印错误

(3)IDEA插件:Maven Helper

安装插件后左下角会出现个新标签页,点击后搜所有此模块依赖的jar包及冲突情况

image-20211113201357394 image-20211113201425368

4、新项目

新项目碰到错误,复杂的问题,先不要深入研究,先看下是否有以下情况:

  • 新项目推荐Log4j2,代码里统一用slf4j打日志
  • 新项目推荐spring boot,它们内部把依赖问题都修复了,可以避免很多问题

5、从下往上递归根因

java的错误栈是从报错的最底层逐步往上打,这样能很方便的定位,一般的问题通过此手段定位问题后即可很快修复。

复杂点的异常,比如jar包冲突异常,最底层的异常一般都是基础组件,比如类加载器、日志组件等,这种情况就要多看几层。

6、从上往下查看变动

大部分问题都是新引入依赖导致,从上往下查看变动,配合从下往上定位信息,定位出问题的组件。

四、案例分享

1、Tomcat项目启动报错

背景:新需求接入舆情SDK,测试环境测试通过,线上发布有大量机器tomcat启动失败。

(1)查找错误日志

异常日志:

image-20211113201801746

(2)尝试修复:第一次

通过module-info.class,和 tag in constant pool: 19分析,直观感受是tomcat不支持java9中的模块策略

机器上使用的是tomcat6, 还不支持java9的新模块策略,遂升级tomcat6到tomcat8,启动错误还有

(3)尝试修复:第二次

此异常是lombok-1.18.10引起的,这个版本为了支持java9添加了module-info.class,而lombok包是java源代码增强的一个工具,运行时,并不需要,遂把依赖的scope改成provided。

重新发布,又报了以下异常:

image-20211113201859921

(4)尝试修复:第三次

报错Not running on Jetty,而我们的服务是运行在tomcat上,配合从上到下排查的思路,在新引入的maven依赖项打开pom.xml,查看里面的依赖项还有parent里的依赖项,找到了以下元凶:parent里会依赖***-boot-starter-web,而这里默认使用jetty作为引擎,遂排除掉,并验证业务逻辑是否正常。

image-20211113202044303

重新发布,问题解决。

(5)经验总结

  • 排查jar包也有风险,很可能导致业务功能受影响,排除后要经过充分验证

2、新加依赖后服务启动失败

背景:新需求接入用户个性化api jar包,使用MDP的thrift注解注册了 thrift client bean,引入后项目启动失败。

(1)异常日志

image-20211113202156042

(2)定位问题

从堆栈初步看是以下包不兼容导致的:swift-codec或guava,还有mtthrift。刚开始重点排查了swift-codec或guava的兼容问题,将其降级和新引入jar包里的版本一致,启动错误还在

刚开始没往mtthrift方面想,因为mtthrift是美团的基础组件,一般情况下不会出现兼容的问题,查看官方wiki也没说有兼容问题

(3)从上到下排查

查看新引入的依赖,打开pom.xml,发现里面引入了MDP 1.5.5版本,而我们的项目的是最新的MDP 1.6.6.1, 初步判断是MDP包冲突,所以就把新包的MDP包排除掉

image-20211113202304318

重新启动,错误依旧

(4)排查版本不一致的依赖

到现在基本可以认为是mtthrift升级导致的不兼容问题。我们引入的jar包只需要其中了api定义,并不需要依赖的依赖,所以把所有的依赖都排除掉。重新引入和依赖包一致的mtthrift版本。重新启动,问题解决。

image-20211113202412654

(5)总结

这个问题解决过程中走了很多弯路,一般我们的认为基础组件升级会兼容老版本,还有一点加深了这个认识:项目里引入的其他的thrift-client包,并没有出现问题。

但不幸的是,这个正好遇到了此类问题。从最终的解决方案看,应该是新引入的jar包编译的问题。

五、对外发布jar包规范

  • 对外提供的SDK或API包,不要包含不必要的额外依赖
  • 严禁包含有依赖的parent的jar包发布
  • 必须要依赖的,可以依赖通用包比如common-langs、guava包等,最好设置provided。

六、总结

Maven包依赖问题是开发中的常见问题,如果不熟悉排查方案,会浪费大量时间。本文从工具、方法论、实践方面做了一些思考,希望对大家日常开发有帮助。

原文链接https://lesofn.com/archives/maven-yi-lai-chong-tu-wen-ti-pai-cha-jing-yan

作者简介:美团Java高级工程师,关注软件架构及职业成长,不定期分享各种技术、资源,对文章中涉及的技术感兴趣或有任何问题请关注微信交流。

公共号:Java研发