4. SDK依赖治理与冲突解决

在企业级SDK治理中，依赖冲突是最常见、也最容易被低估的问题。一个SDK直接声明的依赖可能只有三五个，但经过Maven或Gradle的传递解析后，实际进入classpath的jar可能达到几十甚至上百个。当两个SDK分别传递引入同一个库的不同版本时，构建工具不会报错，运行时却可能出现NoSuchMethodError、ClassNotFoundException或行为不一致。本节围绕“看清依赖树—收敛版本—仲裁冲突—验证结果”这条主线展开。

一、传递依赖分析：先看清依赖图，再谈治理

传递依赖是指A依赖B，B依赖C，则A在编译和运行时也会间接获得C。Maven默认采用“最短路径优先”和“先声明优先”的调解策略；Gradle默认选择“最高版本”。两者策略不同，导致同一组SDK在不同构建体系下可能解析出不同结果。

分析传递依赖的第一步是导出依赖树。以Maven为例：

mvn dependency:tree -Dverbose -Dincludes=com.fasterxml.jackson.core

输出中会看到类似com.fasterxml.jackson.core:jackson-databind:jar:2.9.8:compile与2.13.4:compile同时出现，并标注omitted for conflict。Gradle则使用：

./gradlew :sdk-core:dependencies --configuration runtimeClasspath

关键不是“看到树”，而是识别三类信号：同一GA（groupId+artifactId）多版本共存、同一功能族多实现（如log4j与logback）、以及被标记为omitted或conflict的节点。建议将依赖树导出为文本并纳入SDK仓库的docs/dependency-tree.txt，每次发版前diff一次，冲突变化即可被及时发现。

二、依赖收敛：把“能跑”变成“可控”

依赖收敛的目标是让同一功能族在整条依赖链上只保留一个版本。常见做法有三类：

• BOM统一管理：在父POM中通过dependencyManagement锁定版本，子模块只声明GA不写版本。例如将jackson-bom导入后，所有Jackson组件版本由BOM决定。
• 强制版本：Gradle使用resolutionStrategy.force 'com.fasterxml.jackson.core:jackson-databind:2.13.4'，Maven使用<dependencyManagement>覆盖传递版本。
• 排除传递依赖：对确实不需要的传递依赖使用<exclusions>或exclude group:，但排除要谨慎，避免误删运行时必需类。

收敛后必须验证。推荐在CI中加入依赖收敛检查：

mvn dependency:tree -Dverbose | grep -E "omitted for conflict|version managed"
# 或使用 maven-enforcer-plugin 的 dependencyConvergence 规则

若dependencyConvergence规则失败，说明仍有同一GA多版本共存，需要回到BOM或force策略继续收敛。

三、冲突仲裁算法：理解构建工具的“选择逻辑”

Maven的仲裁可以概括为：先按依赖路径长度排序，路径最短者胜；路径长度相同时，按POM中声明顺序，先声明者胜。Gradle则默认选择版本号最高者，但可通过resolutionStrategy改为failOnVersionConflict()直接失败，强制人工介入。

实际工程中更推荐“显式仲裁”而非“依赖默认策略”。例如在Gradle中：

configurations.all {
    resolutionStrategy {
        force 'com.fasterxml.jackson.core:jackson-databind:2.13.4'
        failOnVersionConflict()
    }
}

这样一旦出现未预期的版本冲突，构建立即失败，而不是悄悄选一个版本继续跑。对于SDK治理而言，构建期失败远优于运行期异常。

四、实战案例：一次Jackson版本冲突的排查与修复

某支付SDK在接入风控SDK后，线上出现NoSuchMethodError: com.fasterxml.jackson.databind.ObjectMapper.registerModule。排查过程如下：

1. 执行mvn dependency:tree -Dverbose -Dincludes=com.fasterxml.jackson.core，发现jackson-databind同时存在2.9.8与2.13.4，2.9.8被标记为omitted for conflict。
2. 检查运行时classpath，实际加载的是2.9.8，原因是支付SDK的依赖路径更短，Maven按最短路径优先选择了旧版本。
3. 在父POM的dependencyManagement中显式锁定jackson-databind为2.13.4，并加入maven-enforcer-plugin的dependencyConvergence规则。
4. 重新构建后，依赖树中2.9.8消失，registerModule方法可用，线上异常不再复现。

五、把治理固化为流程

依赖治理不是一次性动作。建议在SDK发版流水线中固定三个检查点：依赖树导出与diff、dependencyConvergence门禁、以及关键依赖的版本白名单。白名单示例：

当白名单外的版本进入依赖树时，构建失败并提示具体路径，由SDK负责人决定是升级、排除还是申请白名单变更。这样，依赖冲突从“偶发故障”变成“可管理、可追溯、可复现”的工程问题。