dependency-conflict-resolver

依赖冲突解析器

来源映射：源自 Kotlin_Spring_Developer_Pipeline.md（SK-05）的 2 级高价值技能。

使命

找出实际生效的制品版本、它生效的原因，以及范围最小且安全的修正方案。 将依赖冲突解析视为版本归属问题，而不是猜测竞赛。

首先阅读

• ./gradlew dependencies 或指定模块的 dependencies 输出。
• 对发生故障的库系列运行 ./gradlew dependencyInsight --dependency <artifact>。
• 根目录和模块的构建文件、版本目录、导入的 BOM，以及插件版本。
• 确切的运行时或编译时错误：
  • NoSuchMethodError
  • ClassNotFoundException
  • NoClassDefFoundError
  • AbstractMethodError
  • 重复绑定警告

按以下顺序诊断

1. 确定发生故障的类或方法所属方。
2. 确定哪个制品提供了该类。
3. 确定依赖图中的所有候选版本。
4. 确定生效的版本及其生效原因：
   • 直接依赖
   • BOM 或平台
   • 版本目录别名
   • 传递依赖
   • 冲突解析规则
5. 确定应负责管理该系列的真正版本归属方。

高级类路径陷阱

• 编译时构建成功，但运行时出现链接错误，通常意味着已解析的制品之间存在二进制不兼容，而非缺少导入。
• Jackson、Netty、SLF4J、Logback、Kotlin stdlib 和 Hibernate 系列通常应作为整体对齐版本，而不是逐个修补制品。
• 插件类路径和应用程序类路径是两个不同的世界。升级插件可能无法解决运行时库冲突，反之亦然。
• 测试运行时可能与主运行时不同。仅在测试中出现的冲突可能来自测试夹具、模拟库或测试容器支持库。
• enforcedPlatform、strictly 和排除项可以解决冲突，也可能悄无声息地将依赖图锁定在脆弱状态。应谨慎使用。
• 多个日志绑定通常会在彻底失败之前，就导致令人困惑的启动行为。
• 在普通的 Spring Boot 应用中，着色或重定位很少是首选方案。只有确实需要类路径隔离时才考虑使用。

Gradle 解析细节

• 基于变体的解析可以根据用途、JVM 版本和能力等属性选择制品。依赖即使“存在”，也可能解析到了错误的变体。
• 即使声明的版本看起来合理，BOM 导入顺序和多个平台也可能微妙地改变最终生效的系列。
• 共享模块中 api 与 implementation 的依赖泄漏，可能导致冲突只在下游使用方中出现。
• 重新打包或重定位的 JAR 中存在的重复类，可能直到运行时类加载或自动配置扫描时才显现。
• 注解处理器、KSP 和插件类路径可能需要与主应用运行时分别对齐。

专家经验法则

• 如果症状仅在运行时出现，应检查打包后的制品或运行时类路径，而不只是 IDE 依赖树。
• 如果某个库系列由 Spring Boot 管理，优先将版本管理权交还给 BOM，而不是添加更多本地版本固定。
• 如果同一冲突在多个模块中反复出现，应在平台或约定层解决，而不是逐个修补模块。
• 如果某项依赖看起来未使用，在移除前应先确认是否通过反射、自动配置或服务加载器使用。

首选解决策略

• 如果 BOM 已管理兼容版本，优先移除不必要的显式版本。
• 优先对齐整个受影响的依赖系列。
• 如果确实需要覆盖版本，优先采用直接且有文档说明的版本覆盖，而不是隐藏的排除项。
• 仅当某项依赖确实不适用于该模块时才使用排除项，而不是仅仅因为它带来不便。
• 说明为何应由所选层级管理该版本，避免下次升级时冲突再次出现。

输出约定

返回以下部分：

• Conflict summary：说明冲突的内容，以及症状出现的位置。
• Winning path：说明如何选择已解析的制品版本。
• Version authority：说明应由哪个文件或平台负责修复。
• Minimal fix：说明最小且安全的依赖或平台变更。
• Verification：说明用于确认依赖图正常的编译时和运行时检查。

护栏

• 不要在未追溯现有兼容性模型的情况下臆造版本号。
• 不要为了让依赖图变为绿色而随意添加排除项。
• 不要默认使用 force。
• 如果整个库系列的版本都不一致，不要只修复表面上失败的制品。

质量标准

优秀的执行结果会说明冲突路径，并在正确的权威层级解决冲突。 糟糕的执行结果会添加一次性的版本固定，让代码今天可以编译，却在下一个分支中再次引发同样的冲突。