gradle-kotlin-dsl-doctor

Gradle Kotlin DSL 诊断

来源映射：源自 Kotlin_Spring_Developer_Pipeline.md（SK-04）的 Tier 1 关键技能。

使命

以最小且合理的改动稳定构建。 将 Gradle 问题视为兼容性和模型问题，而不只是语法问题。

首先阅读

• settings.gradle.kts
• 根目录和模块的 build.gradle.kts
• gradle.properties
• gradle/libs.versions.toml 或其他版本目录
• gradle-wrapper.properties
• 失败任务的确切 Gradle 输出

分类故障

编辑任何内容之前，先对问题进行分类：

• 插件解析或插件版本不匹配
• Kotlin DSL 语法或类型安全访问器问题
• 依赖解析或 BOM 冲突
• JDK 工具链或目标版本不匹配
• 源集或测试运行时配置错误
• 编译器插件问题，例如 plugin.spring、plugin.jpa、KAPT 或 KSP
• 任务关联或多模块约定问题

工作顺序

1. 确定失败的任务和第一条有意义的错误信息。
2. 判断问题出在插件解析、依赖解析、编译、测试执行还是打包。
3. 找出当前的版本来源：
   • Spring Boot 插件
   • Kotlin 插件
   • Gradle Wrapper
   • JDK 工具链
   • 版本目录或约定插件
4. 确认项目是否应从 Spring Boot BOM 继承版本，而不是手动声明版本。
5. 尽可能只修改最小范围的文件。优先修复模块本地问题，而不是进行全局重写。
6. 在运行完整构建之前，建议使用能验证修复的最小命令。

Kotlin 和 Spring 检查

• 如果 Spring 管理的类依赖代理，请确认使用了 kotlin("plugin.spring")。
• 如果存在 JPA 实体，请确认使用了 kotlin("plugin.jpa")。
• 确认 JVM 目标版本与 Java 工具链一致。
• 确认 kotlin-reflect、序列化库和协程库与当前使用的 Kotlin 版本兼容。
• 确认此项目应使用 KAPT 还是 KSP 进行注解处理。

首选修复方式

• 添加新版本之前，先移除不必要的显式版本。
• 尽可能让 Spring Boot BOM 管理兼容的依赖版本。
• 优先采用小幅差异，而不是替换整个文件。
• 保留现有约定，例如版本目录、约定插件或构建逻辑模块。
• 如果修复涉及多个模块，请说明导致这种改动的依赖关系图。

高级构建诊断

• 区分依赖声明问题与变体选择问题。依赖可能存在，但仍可能解析到错误的 JVM 目标、分类器或能力。
• 检查仓库是否在 Spring Boot BOM 之外使用了 platform(...) 或 enforcedPlatform(...)。这会改变冲突解析行为。
• 检查真正的插件来源是 pluginManagement、版本目录还是约定插件，而非模块构建文件。
• 检查 Boot 插件是否应用到了应发布普通 JAR 而非可执行 JAR 的库模块。
• 如果项目尝试使用配置缓存，请检查兼容性。自定义构建逻辑中的急切任务访问和可变全局状态，往往会导致异常的 Gradle 行为。
• 检查 KAPT、KSP、代码生成或源集关联是否需要目前缺失的生成源码目录或任务排序。
• 建议添加新仓库或更改版本之前，请检查依赖锁定、校验元数据或仓库策略文件。
• 如果模块间依赖在 IDE 和 CI 中表现不同，请检查测试夹具、包含式构建和复合构建。

专家启发式

• 优先说明哪个层级负责管理版本：包装器、插件、平台、版本目录或模块覆盖。这样可以避免只修好眼前的问题，之后又反复出现版本偏差。
• 如果构建只在 CI 中失败，请先比较包装器版本、JDK 供应商、org.gradle.jvmargs、配置缓存标志和仓库凭据，再动依赖声明。
• 如果自定义任务或插件在新 Gradle 版本下出问题，请将这项变更与常规依赖或 Kotlin 编译器修复隔离开来。
• 如果构建使用依赖替换或包含式构建，请先确认解析出的制品是本地源码还是已发布的二进制文件，再诊断 API 不匹配问题。

输出约定

返回以下部分：

• 根本原因：说明哪里出了问题，以及问题发生在构建的哪个阶段。
• 最小补丁：需要进行的确切 Gradle 变更。
• 为何有效：补丁背后的兼容性规则或 Gradle 模型事实。
• 验证：按可信度从低到高列出一个或多个命令。
• 后续风险：仅当修复使构建恢复正常，但留下技术债务时提供。

注意事项

• 不要凭空编造依赖或插件版本。
• 不要将 Kotlin DSL 改写成 Groovy 或 Maven 语法。
• 不要仅仅因为其他模块看起来相似，就去修改无关模块。
• 除非有明确且充分的理由，否则不要用 force 或激进排除来掩盖版本冲突。
• 当构建模型本身有误时，不要把清除缓存作为首选修复方案。

高价值命令

在仓库允许执行命令时，使用以下命令：

• ./gradlew help
• ./gradlew build
• ./gradlew :module:compileKotlin
• ./gradlew dependencies
• ./gradlew dependencyInsight --dependency <artifact>

质量标准

良好的技能运行结果应使构建模型比之前更清晰，并提供能经受 CI 检验的修复。 糟糕的运行结果则会对问题猜测版本、改写过多内容，或忽略 Spring Boot 兼容性模型。