罗罗编程学习记录
本页内容 展开查看

04.8.3.1 Gradle Kotlin DSL 与构建优化

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.8 Kotlin / 04.8.3 构建工具链与测试

本节要解决的问题

本节聚焦 Kotlin/JVM 后端工程在 Gradle 8.x 上的构建脚本编写与构建性能优化:Kotlin DSL 语法与类型安全访问器、buildSrc 与 convention plugin、版本目录、多模块与复合构建、配置避免、增量编译与构建缓存、Kotlin 编译参数、守护进程与内存调优、依赖对齐及 CI 缓存策略。版本前提为 Kotlin 2.x、Gradle 8.x;具体插件坐标与版本号以官方文档当前版本为准。

04.8.3.1-001 Kotlin DSL 与 Groovy DSL 的核心差异是什么?

一句话结论

Kotlin DSL(*.gradle.kts)用 Kotlin 静态类型编写构建脚本,提供编译期类型检查与 IDE 补全;Groovy DSL(*.gradle)是动态语言,脚本解释执行、写法更短但缺少类型校验。

概念解释

两者操作的是同一套 Gradle 模型(Project、Task、Configuration、Dependency),区别只在脚本语言与解析时机。Kotlin DSL 脚本会被编译成 class 再执行,因此属性名拼错、方法签名不匹配会在脚本编译期报错;Groovy DSL 在运行期才解析属性,错误往往等到执行任务时暴露。

原理流程

  1. Gradle 启动后加载 settings 与各模块 build 脚本。
  2. Kotlin DSL 脚本先经过 Kotlin 编译器编译,产物进入脚本编译缓存,再在配置阶段执行。
  3. Groovy DSL 由 Groovy 运行时直接解析执行,无独立编译步骤。
  4. 两种 DSL 最终都生成相同的任务图与依赖图,构建产物一致。

代码或图示

// build.gradle.kts
plugins {
    kotlin("jvm")
}

dependencies {
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
}

常见误区

  • 以为 Kotlin DSL 构建一定更慢:首次配置因脚本编译略慢,命中脚本缓存后与 Groovy DSL 差距很小。
  • 以为两种 DSL 可以在同一个模块混用:一个模块只能选一种脚本文件,不能同时存在同名 .gradle 与 .gradle.kts。

追问

  • 老项目从 Groovy DSL 迁移要注意什么?答:逐模块转换,先迁 settings 与版本目录,再迁业务模块;类型访问器在配置不足时需显式强转。
  • 脚本编译缓存在哪里?答:Gradle 用户目录下的 Kotlin DSL 脚本缓存,清理后首次构建会重新编译脚本。

04.8.3.1-002 Kotlin DSL 的类型安全访问器是如何工作的?

一句话结论

类型安全访问器由 Gradle 根据插件与仓库约定在编译期生成类型化扩展(如 dependencies、kotlinExtension),使脚本以属性访问方式读取 extension 和配置,而不是靠字符串名反射查找。

概念解释

普通动态写法 project.extensions.findByName("kotlin") 返回弱类型对象;类型安全访问器把已应用插件注册的 extension、已知 configuration 暴露为带类型的成员,IDE 可补全、编译器可检查。访问器生成依赖 Gradle 对插件标识与 extension 类型的推断。

原理流程

  1. 应用插件后,插件向 Project 注册命名 extension。
  2. Gradle 在脚本编译期根据已知插件映射生成访问器元信息。
  3. 脚本通过 the<JavaPluginExtension>() 或对应访问器取得强类型对象。
  4. 访问器不可用时回退到 extensions.getByType<T>() 显式获取。

代码或图示

// 类型安全访问器:java extension 直接可读可写
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

// 访问器推断不出来时显式取类型
val kotlinExt = the<org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension>()

常见误区

  • 以为所有 extension 都有现成访问器:第三方插件未提供映射时,必须用 getByType<T>()。
  • 以为访问器在脚本任何位置都可用:访问器生成依赖插件已在 plugins{} 块声明,顺序上先声明再配置。

追问

  • 访问器报未解析符号怎么办?答:确认插件版本与 Gradle 版本兼容,必要时改用 extensions.getByType,并检查脚本编译缓存是否过期。
  • 如何在自定义 convention plugin 中暴露强类型配置?答:定义 extension 数据类并通过 project.extensions.create(...) 注册。

04.8.3.1-003 Kotlin DSL 中 extension 配置块是如何解析的?

一句话结论

kotlin { ... } 这类带接收者的配置块,接收者类型就是插件注册的 extension 类型;块内直接调用该类型的方法与属性,本质是 Kotlin 的带接收者 lambda。

概念解释

Gradle 插件注册 extension 后,DSL 提供形如 extensionName { configure } 的方法,参数是带 extension 接收者的 lambda。块内 this 指向 extension 对象,因此可以直接访问其属性。配置块在配置阶段执行,修改的是 extension 状态,任务执行阶段读取该状态。

原理流程

  1. 插件应用时创建 extension 实例并注册到 Project。
  2. DSL 生成或解析对应配置方法,接收 Action<T> 或带接收者 lambda。
  3. 配置块在配置阶段回调,向 extension 写入参数。
  4. 相关任务在执行阶段读取 extension 快照完成编译。

代码或图示

kotlin {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
    }
}

常见误区

  • 在配置块里执行耗时 IO 或网络请求:配置阶段应只做声明,读取外部值应放在任务动作里。
  • 以为配置块返回值可被任务直接捕获:跨阶段共享状态要用 Provider/Property 懒包装。

追问

  • 配置阶段与执行阶段如何区分?答:配置阶段组装任务图,执行阶段运行任务动作;在配置阶段访问任务输出结果会破坏懒解析。
  • 多个配置块重复设置同一属性谁生效?答:后执行的覆盖先执行的,顺序由脚本与插件应用顺序决定。

04.8.3.1-004 为什么 Kotlin DSL 首次配置比 Groovy DSL 慢?

一句话结论

Kotlin DSL 脚本需要先被 Kotlin 编译器编译并缓存,首次或脚本变更后要付一次脚本编译成本;命中脚本编译缓存后,后续配置只加载已编译 class,差距明显缩小。

概念解释

脚本编译包括解析插件 classpath、类型推断、字节码生成。Gradle 会缓存编译产物,脚本与输入不变时直接复用。Groovy DSL 无编译步骤,因此冷启动更快,但代价是缺少类型安全。

原理流程

  1. 首次执行:解析脚本依赖 classpath,编译 build.gradle.kts。
  2. 产物写入 Kotlin DSL 脚本缓存目录。
  3. 后续执行:校验脚本与输入哈希,命中则直接加载缓存 class。
  4. 脚本、插件版本或 Gradle 版本变化后缓存失效,重新编译。

代码或图示

# 观察脚本编译与配置耗时(构建扫描或 --profile)
gradle help --profile

常见误区

  • 把每次配置都慢归因于 DSL 语言:更多时候是 configuration 阶段做了重活、任务被过早创建。
  • 频繁清空 .gradle 目录:会连带清掉脚本编译缓存,导致每次都重新编译。

追问

  • 如何确认命中了脚本缓存?答:构建扫描中 Kotlin DSL 脚本编译任务状态为 FROM_CACHE 或 skipped;可对比 warm-up 前后配置耗时。
  • 多模块脚本编译能否并行?答:脚本编译可利用 Gradle 并行能力,但单模块脚本仍需先编译再配置。

04.8.3.1-005 Kotlin DSL 中如何声明插件?

一句话结论

在 plugins { } 块用 id("...") 或 Kotlin 专用简写 kotlin("jvm") 声明插件;apply false 只声明不应用,留给子模块或后续显式应用。

概念解释

plugins{} 块是现代 Gradle 声明插件的入口,它同时解析插件版本与 classpath。块内插件必须在脚本顶部,且在其他配置之前。apply false 常见于根项目统一管理插件版本、子模块按需应用的多模块结构。

原理流程

  1. plugins{} 块经 pluginManagement 解析插件 marker 坐标。
  2. 解析成功后插件 classpath 进入脚本编译 classpath,访问器可用。
  3. 默认 apply true,插件立即应用;apply false 仅登记版本。
  4. 子模块再通过 id("...") 不带版本号应用同一插件。

代码或图示

// 根项目 settings 或构建脚本中统一版本,子模块 apply false
plugins {
    kotlin("jvm") version "2.0.20" apply false
    id("io.gitlab.arturbosch.detekt") version "1.23.7" apply false
}

// 子模块
plugins {
    kotlin("jvm")
    id("io.gitlab.arturbosch.detekt")
}

常见误区

  • 在 plugins{} 块之外用 apply plugin: 混用新老风格:可行但丢失类型访问器与版本统一能力。
  • 在子模块重复写插件版本号:版本应由根项目或版本目录收口,子模块只声明 id。

追问

  • 插件版本从版本目录引用怎么写?答:alias(libs.plugins.kotlin.jvm),别名在 libs.versions.toml 的 [plugins] 段定义。
  • 本地未发布的 convention plugin 如何在 plugins{} 引用?答:通过复合构建 includeBuild 提供 marker,或在 buildSrc 中直接应用。

04.8.3.1-006 implementation、api、compileOnly、runtimeOnly 配置有什么区别?

一句话结论

api 传递给下游编译 classpath,implementation 只在本模块编译期可见、不向下游传递,compileOnly 仅编译期存在,runtimeOnly 仅运行期存在。

概念解释

配置(configuration)决定依赖出现在哪条 classpath 上。多模块工程中误用 api 会扩大传递依赖面、拖慢编译并增加耦合;库模块对外暴露的类型才需要 api,内部实现细节用 implementation。

原理流程

  1. 声明依赖时绑定到对应 configuration。
  2. 编译任务按 compile classpath 解析依赖集合。
  3. 运行任务按 runtime classpath 解析另一份集合。
  4. 下游模块编译时只能看到上游声明为 api 的依赖。

代码或图示

dependencies {
    api("com.fasterxml.jackson.core:jackson-databind")   // 对外暴露
    implementation("org.slf4j:slf4j-api")                  // 内部使用
    compileOnly("org.projectlombok:lombok")               // 仅编译期
    runtimeOnly("ch.qos.logback:logback-classic")        // 仅运行期
}

常见误区

  • 后端应用模块(不可再被依赖)过度区分 api/implementation:应用模块通常全部 implementation 即可。
  • 以为 compileOnly 会出现在最终产物运行时:不会,运行时需另配 runtimeOnly 或由服务端容器提供。

追问

  • testImplementation 与 implementation 关系?答:测试编译 classpath 在 implementation 基础上叠加 testImplementation,反之不成立。
  • 依赖被下游意外用到如何收敛?答:把不该暴露的从 api 改为 implementation,下游显式声明自己需要的依赖。

04.8.3.1-007 Kotlin DSL 中依赖坐标是如何解析的?

一句话结论

坐标由 group:artifact:version 三元组(可选 classifier)组成,Gradle 按仓库顺序查询元数据,解析传递依赖后形成模块 classpath;版本目录别名最终展开为同一坐标。

概念解释

依赖解析先查模块描述符(pom 或 module metadata),再拉取产物。Gradle 8.x 默认支持 Gradle Module Metadata,可区分能力变体与平台。坐标字符串在 DSL 中只是语法糖,等价于 DependencyNotation 解析。

原理流程

  1. 脚本解析坐标字符串为 group/name/version。
  2. 按 repositories 声明顺序查询模块元数据。
  3. 应用版本冲突规则与平台对齐规则。
  4. 解析出的模块进入对应 configuration 的解析结果。

代码或图示

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.17.2")
}

常见误区

  • 依赖只写 group:artifact 不写版本:在未被平台/BOM 管理时解析失败。
  • 仓库顺序随意导致快照/镜像包污染:应把稳定仓库在前,快照仓库单独隔离。

追问

  • 如何查看实际解析出的依赖树?答:运行依赖分析任务查看配置依赖树(具体任务名以 Gradle 版本为准),排查冲突与传递引入。
  • classifier 产物怎么写?答:坐标后追加 classifier,如测试 jar 包;版本目录中可单独声明对应别名。

04.8.3.1-008 Kotlin DSL 中如何定义一个自定义任务?

一句话结论

用 tasks.register<任务类型>("任务名") { ... } 懒注册,在动作块或配置块中声明输入输出与行为;优先注册而非立即创建,以符合配置避免原则。

概念解释

任务类型可以是 Gradle 内置 DefaultTask,也可以是自定义 Task 子类。register 只登记任务到任务图,真正实例化与配置发生在任务被执行需求触发时。配置块中设置属性,任务动作写在 doLast 或类型自带的 action 方法里。

原理流程

  1. register 生成任务注册信息,不立即构造任务对象。
  2. 任务被依赖链选中后才实例化,执行配置块。
  3. 输入输出属性被注解或 API 声明,供增量与缓存判定。
  4. 执行阶段运行任务动作。

代码或图示

tasks.register("sayHello") {
    group = "application"
    doLast {
        println("hello from gradle")
    }
}

// 带类型的自定义任务
abstract class GreetingTask : DefaultTask() {
    @get:Input
    abstract val who: Property<String>

    @TaskAction
    fun greet() = println("hello ${who.get()}")
}
tasks.register<GreetingTask>("greet") {
    who.set("kotlin")
}

常见误区

  • 在配置块里直接执行动作代码(如拷贝、打印):这些代码在配置阶段就跑,违反懒加载。
  • 用 tasks.create 强制实例化:会在配置阶段构建全部任务,拖慢配置。

追问

  • 任务输入输出如何声明才能参与增量与缓存?答:用 @Input、@OutputDirectory 等注解或 Property 标注,Gradle 据此计算缓存键。
  • 任务之间依赖怎么写?答:dependsOn("other") 或 dependsOn(otherTaskProvider),后者保持懒解析。

04.8.3.1-009 Kotlin DSL 访问已有任务属性需要类型强转吗?

一句话结论

通过 tasks.named<类型>("名字") 取得带类型的任务 provider;用无类型 tasks.named("名字") 时访问类型化属性需要强转或先指定类型。

概念解释

Gradle 内置任务(如 compileKotlin、processResources)有固定类型。DSL 提供类型化访问器时可直接配置;访问器不可靠时,named<T> 泛型指定任务类型,lambda 接收者即为该类型,无需手动强转。

原理流程

  1. tasks.named<T>(name) 返回 TaskProvider<T>。
  2. 配置块 lambda 接收 T 类型任务实例。
  3. 类型不匹配时 Gradle 在配置期抛出类型转换异常。
  4. 任务实际执行时属性值已就绪。

代码或图示

tasks.named<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>("compileKotlin") {
    compilerOptions {
        freeCompilerArgs.add("-opt-in=kotlin.RequiresOptIn")
    }
}

常见误区

  • 用 tasks["compileKotlin"] as KotlinCompile 立即取值:这会在配置阶段强制实例化任务,破坏配置避免。
  • 凭记忆写任务名:任务名与 sourceSet、插件版本相关,名称变化时应查插件文档。

追问

  • 批量配置同类任务怎么做?答:tasks.withType<KotlinCompile>().configureEach { ... },逐个懒配置。
  • 任务名在多 sourceSet 下是什么规律?答:通常按 compile<SourceSet>Kotlin 拼接,具体以插件生成结果为准。

04.8.3.1-010 Kotlin DSL 中 kotlin("jvm") 插件写法代表什么?

一句话结论

kotlin("jvm") 是 Kotlin Gradle Plugin(KGP)提供的 DSL 简写,等价于 id("org.jetbrains.kotlin.jvm"),用于在 JVM 目标工程应用 Kotlin 编译支持。

概念解释

KGP 按目标平台提供不同插件 id:JVM、多平台、Android 等。简写 kotlin(...) 只是 id("org.jetbrains.kotlin.平台") 的包装,避免手拼长 id。插件应用后注册 Kotlin extension 与编译任务。

原理流程

  1. kotlin("jvm") 展开为插件 id 并解析版本。
  2. 插件注册 compileKotlin、compileTestKotlin 等任务。
  3. 配置 kotlin { } 扩展调整编译选项。
  4. 编译任务把 Kotlin 源码编成字节码并合并到 jar。

代码或图示

plugins {
    kotlin("jvm") version "2.0.20"
}

repositories { mavenCentral() }

dependencies {
    implementation(kotlin("stdlib"))
}

常见误区

  • 以为 kotlin("jvm") 内置标准库依赖:标准库仍需在 dependencies 中声明(或由插件默认配置提供,以当前 KGP 版本行为为准)。
  • 在非 JVM 模块套用 jvm 插件:平台插件必须与目标运行时一致。

追问

  • 多平台工程用哪个插件?答:kotlin("multiplatform"),在 kotlin { jvm(); js(); } 中声明目标。
  • Kotlin 版本与 KGP 版本关系?答:插件版本即编译器版本,二者一致;升级 Kotlin 要同步升级插件版本。

04.8.3.1-011 settings.gradle.kts 与 build.gradle.kts 的职责如何划分?

一句话结论

settings.gradle.kts 负责工程级结构:仓库解析、插件管理、包含哪些模块与复合构建;build.gradle.kts 负责单个工程(根或子模块)的插件、依赖、任务与编译配置。

概念解释

settings 脚本在所有 build 脚本之前执行,决定参与构建的工程集合与插件解析渠道。根 build 脚本可做跨模块公共配置,子模块 build 脚本只描述自身。把模块清单放在 settings 是 Gradle 现代约定。

原理流程

  1. 启动时先解析 settings 脚本,构建工程树。
  2. pluginManagement 决定插件从哪里解析、版本如何对齐。
  3. include/includeBuild 确定纳入构建的模块。
  4. 随后各工程 build 脚本进入配置阶段。

代码或图示

// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories { mavenCentral() }
}
include("app", "domain", "infrastructure")

常见误区

  • 在子模块 build 脚本里声明仓库:现代约定把仓库收口到 settings 的 dependencyResolutionManagement,子模块声明会触发模式报错。
  • 把插件版本写进 settings 却不在根项目 apply false:版本登记与应用位置要配套。

追问

  • repositoriesMode 有哪几种?答:FAIL_ON_PROJECT_REPOS 禁止工程级仓库,PREFER_PROJECT 允许工程优先;具体取值以 Gradle 版本文档为准。
  • 模块目录名与工程名不一致怎么办?答:include("xxx") 后通过 project(":xxx").projectDir 指定目录。

04.8.3.1-012 pluginManagement 块的作用是什么?

一句话结论

pluginManagement 声明插件解析的仓库、版本规则与插件解析策略,作用于 plugins{} 块解析插件 marker,优先级高于普通依赖仓库配置。

概念解释

插件 classpath 与普通依赖 classpath 分开解析,因此需要独立仓库列表。pluginManagement 还可配置 plugin resolution strategy,对插件版本做统一对齐或替换。它只能出现在 settings 脚本顶部。

原理流程

  1. settings 脚本先读取 pluginManagement。
  2. 按声明仓库顺序查找插件 marker 与实现构件。
  3. 应用版本规则(如对齐到 BOM)。
  4. 解析出的插件 classpath 供各 build 脚本使用。

代码或图示

pluginManagement {
    repositories {
        gradlePluginPortal()
        maven { url = uri("https://repo.example.internal/maven") }
    }
    resolutionStrategy {
        failOnNonReproducibleResolution()
    }
}

常见误区

  • 把公司内部插件仓库只写进 dependencyResolutionManagement:插件解析找不到,必须进 pluginManagement。
  • 在 plugins{} 块之后再写 pluginManagement:位置非法,Gradle 报错。

追问

  • 如何强制某个插件用指定版本?答:resolutionStrategy 中按 id 强制版本,或在根项目统一登记版本。
  • 插件 marker 与实现构件区别?答:marker 是只含插件坐标的小构件,真正实现插件类打包在实现构件中。

04.8.3.1-013 Kotlin DSL 脚本编译缓存如何工作?

一句话结论

Gradle 把编译后的脚本 class 与输入哈希缓存到本地目录,脚本、插件 classpath、Gradle 版本任一变化即失效;命中缓存时跳过脚本编译直接执行。

概念解释

缓存输入包括脚本内容、脚本相关插件与扩展类、DSL 访问器元信息。缓存目的是抵消 Kotlin 编译成本。多人协作时该缓存只在本地,不进远程构建缓存。

原理流程

  1. 计算脚本及其依赖输入的哈希。
  2. 哈希匹配则加载已编译 class。
  3. 不匹配则调用 Kotlin 编译器重新生成 class。
  4. 新 class 写入缓存供下次使用。

代码或图示

# 脚本编译缓存在 Gradle 用户目录下的 kotlin-dsl 相关目录;
# 清理后首次构建会观察到脚本编译任务重新执行。

常见误区

  • 以为脚本缓存等同构建缓存:前者缓存脚本字节码,后者缓存任务输出产物,两者独立。
  • 修改 extension 类后不失效:buildSrc/convention plugin 变更属于输入变化,会自动触发重编译。

追问

  • 脚本缓存损坏如何处理?答:停止 daemon 后清理 Gradle 用户目录下对应缓存,重新 warm-up 构建。
  • 如何降低脚本编译频次?答:保持脚本稳定、插件版本少变动,公共逻辑下沉到 convention plugin。

04.8.3.1-014 Groovy DSL 脚本可以直接改后缀为 .kts 吗?

一句话结论

不能直接改后缀:Groovy 动态语法(字符串属性、GString 插值、动态方法)在 Kotlin 静态规则下大量不合法,需要按 Kotlin 语法逐句改写。

概念解释

Groovy 允许省略类型、动态派发、project.ext.xxx 动态属性;Kotlin 脚本要求类型明确、访问器存在。直接改名会出现未解析引用、类型不匹配等编译错误。注释与坐标字符串可保留,逻辑语句需转换。

原理流程

  1. 先复制脚本为 .kts,保留依赖坐标与仓库声明。
  2. 动态属性改为 extension API 或 extra["..."]。
  3. 任务配置改为 register/withType 懒写法。
  4. 编译脚本直至类型检查通过。

代码或图示

// Groovy 旧写法
ext { lib = "1.0" }
dependencies { implementation "com.example:lib:$lib" }
// Kotlin 改写后
val lib: String by extra
dependencies { implementation("com.example:lib:$lib") }

常见误区

  • 批量改名后靠运行期报错再修:应先让脚本编译通过,再调任务行为。
  • 忽略 Groovy 闭包与 Kotlin lambda 接收者差异:配置块写法需要适配带接收者类型。

追问

  • 迁移期间能否两种脚本共存于不同模块?答:可以按模块逐步迁移,Gradle 对每个工程独立选择脚本语言。
  • 迁移后如何回归构建行为?答:对比迁移前后任务图、依赖树与产物内容,确认一致。

04.8.3.1-015 Kotlin DSL 中如何定义并注册自定义任务类型?

一句话结论

定义继承 DefaultTask 的抽象类,用 @Input 等注解声明属性,@TaskAction 标注动作方法;再在脚本或 plugin 中 register<T>(name) 注册。

概念解释

现代 Gradle 推荐用抽象属性配合注入的 Property<T>,而不是普通可变字段。任务类型可以写在 buildSrc、convention plugin 或脚本内联。动作方法只在执行阶段运行,读取已注入的属性值。

原理流程

  1. 任务类继承 DefaultTask,抽象属性由 Gradle 注入实现。
  2. 注解声明输入输出,参与增量与缓存判定。
  3. register 绑定任务名与类型。
  4. 执行阶段实例化任务并调用 @TaskAction 方法。

代码或图示

abstract class CheckLicense : DefaultTask() {
    @get:InputDirectory
    abstract val sourceDir: DirectoryProperty

    @TaskAction
    fun check() {
        sourceDir.get().asFile.walk().filter { it.isFile }.forEach { /* 检查逻辑 */ }
    }
}

tasks.register<CheckLicense>("checkLicense") {
    sourceDir.set(layout.projectDirectory.dir("src/main"))
}

常见误区

  • 在任务构造器或属性初始化阶段读文件:此时输入未注入,应放到 @TaskAction 内。
  • 属性用普通 var 而不用 Property:无法参与懒解析与缓存键计算。

追问

  • 任务输出目录如何声明?答:@OutputDirectory 标注 DirectoryProperty,Gradle 据此清理与缓存。
  • 任务类型放哪里复用?答:多个模块复用时下沉到 buildSrc 或发布为 convention plugin。

04.8.3.1-016 Kotlin DSL 中跨脚本共享属性用什么方式?

一句话结论

配置阶段共享少量标量可用 extra(extra["key"] 或委托属性);共享依赖版本与模块级配置更推荐版本目录或 convention plugin,避免字符串键散落。

概念解释

extra 是 Project 级附加属性容器,可在根项目与子项目间读取,但类型弱、无补全。版本目录提供类型安全别名,convention plugin 提供强类型 extension,二者都是工程化的替代方案。

原理流程

  1. 根项目 extra.set("key", value) 写入属性。
  2. 子项目通过 (project.rootProject.extra.properties["key"]) 读取。
  3. 类型不安全处需显式转换。
  4. 公共依赖与编译配置改由 plugin 统一收口。

代码或图示

// 根 build.gradle.kts
extra["javaVersion"] = "17"

// 子模块
val javaVersion: String by rootProject.extra

常见误区

  • 用 extra 存依赖坐标列表:依赖应收口到版本目录,便于校验与升级。
  • 在配置阶段跨项目直接读对方任务输出:会强制配置顺序耦合,应通过任务依赖与产物配置传递。

追问

  • 根项目向子项目传闭包/对象可行吗?答:技术上可放 extra,但配置顺序脆弱,推荐 plugin 封装。
  • 委托属性 by extra 类型不匹配会怎样?答:取值时抛出类型转换异常。

04.8.3.1-017 Kotlin DSL 中如何批量过滤并配置任务?

一句话结论

用 tasks.withType<T>().configureEach { ... } 按类型懒过滤配置;需要按名字条件筛选时在配置块内判断,避免先列举全部任务。

概念解释

withType 把配置应用到所有匹配类型的任务,configureEach 保证任务按需实例化。这比 tasks.forEach { if (it is ...) } 更符合配置避免原则,也不会触发未选中任务的创建。

原理流程

  1. 注册类型过滤规则。
  2. 任务实例化时检查类型,匹配则执行配置动作。
  3. 未被选中的任务不会执行该配置块。
  4. 配置结果写入任务属性供执行阶段使用。

代码或图示

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
    compilerOptions {
        freeCompilerArgs.add("-Xjsr305=strict")
    }
}

常见误区

  • 用 tasks.matching { it.name.startsWith("compile") }.configureEach 后又访问任务集合:匹配规则本身安全,但块内不能做强制列举。
  • 把批量配置写进 afterEvaluate:会推迟到全部项目配置完,易破坏懒解析顺序。

追问

  • 只想配置某个 sourceSet 的任务怎么办?答:在匹配条件中按任务名或 extension 属性筛选,或单独 named 配置。
  • 批量配置与逐个 named 配置冲突时谁生效?答:都生效,后执行的覆盖先写入的属性。

04.8.3.1-018 Provider 与 Lazy Property 在配置阶段扮演什么角色?

一句话结论

Provider 是懒计算的值句柄,Property<T> 是可注入的懒属性;它们把"取值"推迟到执行阶段,使配置阶段不解析具体值,是配置避免与缓存复用的基础。

概念解释

普通字符串/数字在配置阶段就固定;Provider 包装计算逻辑,任务输入通过 Provider 连接,输入变化时缓存键自动重算。跨任务传值用 TaskOutput.property() 转 Provider,避免在配置阶段读取产物文件内容。

原理流程

  1. 声明 Property<String> 并 set(...) 或 set(provider)。
  2. 配置阶段只记录来源,不调用 get()。
  3. 执行阶段或缓存计算时才 get() 取值。
  4. 上游任务输出 Provider 变化会触发下游重跑。

代码或图示

abstract class ReportTask : DefaultTask() {
    @get:Input
    abstract val title: Property<String>

    @TaskAction
    fun report() = println(title.get())
}

tasks.register<ReportTask>("report") {
    title.set(provider { "build-${project.version}" })
}

常见误区

  • 在配置阶段调用 .get():提前解析值,切断懒链接,缓存与增量失效。
  • 把 Provider 当普通字段传值:任务间应传 provider,而不是先取字符串再塞进去。

追问

  • Provider 链如何派生新值?答:用 map { }、flatMap { } 派生,结果仍是懒 Provider。
  • 任务输出如何暴露为 Provider?答:输出属性本身就是 RegularFileProperty,可直接被下游任务依赖。

04.8.3.1-019 Kotlin DSL 脚本里能否定义普通 Kotlin 函数或类?

一句话结论

可以:.gradle.kts 本质是 Kotlin 脚本,可在顶层定义私有辅助函数、数据类与扩展;但跨脚本复用应下沉到 buildSrc 或 convention plugin,而不是复制粘贴。

概念解释

脚本内定义的类型只在本脚本编译单元可见。脚本作为 Kotlin 编译产物,支持函数、类、import。把构建逻辑写成函数可减少重复,但跨模块共享必须放到被脚本 classpath 引用的位置。

原理流程

  1. 脚本顶部 import 所需类型。
  2. 顶层声明辅助函数/类,编译进脚本 class。
  3. 配置块调用辅助函数完成声明式配置。
  4. 跨脚本复用改为 buildSrc 类库。

代码或图示

fun Project.baseCompileConfig() {
    kotlin {
        compilerOptions {
            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
        }
    }
}

baseCompileConfig()

常见误区

  • 在脚本函数里做执行阶段的重活:函数仍在配置阶段被调用,重逻辑应进任务动作。
  • 多个脚本复制同一辅助函数:应下沉到 buildSrc,保证单一来源。

追问

  • 脚本能引用 buildSrc 的类吗?答:能,buildSrc 编译产物自动加入脚本 classpath。
  • 脚本内类会参与构建缓存吗?答:脚本编译缓存覆盖脚本本身;任务缓存仍按任务输入输出判定。

04.8.3.1-020 应用插件后脚本访问器不可用一般是什么原因?

一句话结论

访问器不可用通常是插件未在 plugins{} 块声明、插件版本与 Gradle 版本不兼容、脚本缓存过期,或第三方插件未提供 Kotlin DSL 映射;此时用 extensions.getByType<T>() 显式获取。

概念解释

类型访问器由 Gradle 对已知插件模型生成;自定义或老插件只注册 extension 类型,不生成脚本成员。显式按类型取 extension 是兜底手段,不依赖访问器生成。

原理流程

  1. 检查 plugins{} 是否声明该插件。
  2. 核对插件版本与 Gradle/Kotlin 兼容矩阵。
  3. 清理脚本缓存后重新同步。
  4. 仍无访问器则按 extension 类型显式解析。

代码或图示

val detektExt = extensions.getByType<io.gitlab.arturbosch.detekt.extensions.DetektExtension>()
detektExt {
    config.from("config/detekt/detekt.yml")
}

常见误区

  • 一报错就升级 Gradle:先确认插件是否提供 DSL 映射,显式取类型往往更快解决。
  • 在未应用插件的脚本里引用其 extension:ClassNotFound 或未注册异常。

追问

  • 如何确认 extension 注册名与类型?答:查插件文档源码中的 extensions.create 调用,得到类型全限定名。
  • 访问器与显式取类型性能有差别吗?答:运行期都解析同一注册表,差异在编译期类型安全,不在执行性能。

04.8.3.1-021 buildSrc 在 Gradle 构建中处于什么位置?

一句话结论

buildSrc 是被 Gradle 自动编译并加入所有构建脚本 classpath 的特殊目录:里面的类、任务类型、插件可被各 build 脚本直接引用,编译先于业务配置。

概念解释

Gradle 在主构建前先把 buildSrc 当作独立工程编译,产物放入脚本 classpath。它适合放跨模块复用的任务类型、extension 模型与小工具。buildSrc 自身改动会使所有脚本缓存失效。

原理流程

  1. 启动构建时识别根目录 buildSrc。
  2. 按其构建脚本编译类与资源。
  3. 编译产物加入脚本编译与执行 classpath。
  4. 主构建各模块脚本可直接 import 使用。

代码或图示

buildSrc/
├── build.gradle.kts
└── src/main/kotlin/
    └── com/example/build/ReportTask.kt

常见误区

  • 把业务运行时代码放进 buildSrc:它只服务构建脚本,不进业务产物 classpath。
  • 以为 buildSrc 依赖会自动成为业务依赖:脚本可见不等于模块运行期可见。

追问

  • buildSrc 里能写 Kotlin 吗?答:可以,配合 Kotlin JVM 插件编译;也可用 Groovy/Java。
  • buildSrc 版本如何管理?答:其内部依赖在自身构建脚本中声明,版本目录可被 buildSrc 引用(配置方式以 Gradle 版本为准)。

04.8.3.1-022 buildSrc 的依赖能否被业务模块直接看到?

一句话结论

不能:buildSrc 的依赖只在编译构建脚本时可见,业务模块的编译与运行 classpath 不包含它们;业务需要的库必须在模块依赖中重新声明。

概念解释

buildSrc 是构建工具链的一部分,其配置类似于独立插件工程。它向脚本 classpath 暴露自身编译类,而不是把自己的 implementation 依赖传递给业务模块。这种隔离避免构建工具污染业务产物。

原理流程

  1. buildSrc 编译时解析自身依赖。
  2. 产物与依赖进入脚本 classpath 供脚本使用。
  3. 主业务模块按各自 dependencies 重新解析。
  4. 两边依赖集合互不传递。

代码或图示

// buildSrc/build.gradle.kts:仅脚本工具可见
dependencies {
    implementation(libs.plugin.kotlin.gradle)
}

// 业务模块需要 Jackson 时仍要显式声明
// app/build.gradle.kts
dependencies {
    implementation("com.fasterxml.jackson.core:jackson-databind")
}

常见误区

  • 在 buildSrc 引入库后期待业务代码 import 成功:业务编译 classpath 没有该库。
  • 用 buildSrc 做共享业务代码库:应拆成普通业务模块。

追问

  • buildSrc 产物会打进业务 jar 吗?答:不会,它只在构建期存在。
  • 如何让工具类同时被脚本和业务使用?答:拆为独立库模块,按需被两边依赖。

04.8.3.1-023 buildSrc 与复合构建(composite build)有什么区别?

一句话结论

buildSrc 是自动纳入、仅对脚本可见的内部编译单元;复合构建通过 includeBuild 纳入完整工程,可替换发布坐标、产出构件,参与依赖解析。

概念解释

buildSrc 解决"脚本复用类"问题,没有独立产物坐标;复合构建解决"本地联调多工程"问题,被纳入工程可以是库或插件,通过替换规则对外提供构件。复合构建更灵活,但配置复杂度更高。

原理流程

  1. buildSrc:自动编译,产物进脚本 classpath,无坐标替换。
  2. 复合构建:settings 中 includeBuild 引入独立工程。
  3. 可选 substitute 把外部坐标映射到本地工程产物。
  4. 主构建解析依赖时优先使用本地工程输出。

代码或图示

// settings.gradle.kts
includeBuild("../shared-library") {
    dependencySubstitution {
        substitute(module("com.example:shared-library")).using(project(":shared-library"))
    }
}

常见误区

  • 把可复用插件先放 buildSrc、再复制到复合构建:二者定位不同,插件要分发应走独立插件工程。
  • 以为 includeBuild 后本地代码改动自动重编:被纳入工程按其任务图参与增量构建,改动会触发对应重编。

追问

  • 复合构建能纳入非 Gradle 工程吗?答:纳入成员需是 Gradle 工程;其他工具链工程不在此机制范围。
  • 本地联调与 mavenLocal() 发布对比?答:复合构建直接用源码产物、免安装;mavenLocal 需先发布快照再被解析。

04.8.3.1-024 什么时候应该把 buildSrc 内容拆成独立 convention plugin?

一句话结论

当 buildSrc 里的任务类型/配置需要被多套构建复用、需要独立版本演进,或 buildSrc 体积变大导致脚本缓存频繁失效时,应拆为独立 Gradle plugin 工程,通过复合构建或仓库分发。

概念解释

buildSrc 与主工程同生共死,任何改动都让脚本缓存失效;独立 plugin 有自己的产物与版本,可被其他工程引用、单独测试。convention plugin 是把"一组插件应用与默认配置"打包的 plugin。

原理流程

  1. 梳理 buildSrc 中稳定、可复用的配置逻辑。
  2. 新建 plugin 工程,定义 extension 与 apply 逻辑。
  3. 本地用 includeBuild 联调,需要时发布到内部仓库。
  4. 主工程脚本 plugins{} 引用该 plugin 并覆盖差异配置。

代码或图示

// 独立 plugin 入口
class KotlinConventionPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.kotlin.jvm")
        // 统一编译配置
    }
}

常见误区

  • 一上来就为单工程拆插件:抽象成本高于收益,buildSrc 足够。
  • plugin 里硬编码业务路径:应通过 extension 暴露可配置项。

追问

  • plugin 如何发布?答:打包为 jar 并提供 plugin marker 构件,发布到插件门户或内部 Maven 仓库;坐标以官方文档当前版本为准。
  • 拆出后如何测试 plugin?答:用 Gradle 测试框架跑模拟工程,断言插件应用后的任务与依赖。

04.8.3.1-025 convention plugin 如何在 settings.gradle.kts 中纳入?

一句话结论

本地开发时用 includeBuild 把 plugin 工程纳入复合构建,主工程 plugins{} 按 id 引用;已发布的 plugin 则通过 pluginManagement 仓库解析,无需 includeBuild。

概念解释

convention plugin 本质是普通 Gradle 插件,区别在于它封装项目约定而非单一工具能力。本地联调靠复合构建提供 marker;正式使用从仓库拉取。插件 id 与 marker 工件一一对应。

原理流程

  1. plugin 工程实现 Plugin<Project> 并声明 id。
  2. settings 中 includeBuild("../build-plugins")。
  3. 主工程 plugins { id("com.example.convention.kotlin") }。
  4. Gradle 从纳入构建解析 marker 并应用插件。

代码或图示

// settings.gradle.kts
includeBuild("../build-plugins")

// app/build.gradle.kts
plugins {
    id("com.example.convention.kotlin")
}

常见误区

  • includeBuild 路径写成业务模块路径:plugin 工程需有独立 settings 与构建脚本。
  • 主工程与 plugin 工程 Kotlin 版本不一致导致脚本编译冲突:对齐工具链版本。

追问

  • plugin 工程自身需要版本号吗?答:发布构件需要版本;本地复合构建按工程引用,不依赖版本解析。
  • 多个 convention plugin 之间能否互相应用?答:可以,插件内部 project.plugins.apply(...) 组合。

04.8.3.1-026 本地 convention plugin 如何联调而不发布?

一句话结论

用复合构建 includeBuild 指向 plugin 源码工程,主工程直接按插件 id 引用;修改 plugin 源码后重新构建即生效,无需安装到本地 Maven 仓库。

概念解释

复合构建把 plugin 工程的产物纳入主构建的插件解析链。plugin 改动后其任务增量重编,主工程下次配置时加载新 class。这种方式适合团队内部插件快速迭代。

原理流程

  1. plugin 工程实现入口类与 marker 声明。
  2. settings 登记 includeBuild 路径。
  3. 主工程引用插件 id,Gradle 解析到纳入构建产物。
  4. 修改 plugin 后触发其编译任务,主构建复用新产物。

代码或图示

// build-plugins/build.gradle.kts
plugins {
    `java-gradle-plugin`
}
gradlePlugin {
    plugins {
        create("kotlinConvention") {
            id = "com.example.convention.kotlin"
            implementationClass = "com.example.build.KotlinConventionPlugin"
        }
    }
}

常见误区

  • 改完 plugin 只跑主工程不触发 plugin 重编:确认 plugin 工程编译任务被纳入依赖链,必要时先单独构建 plugin。
  • 在 plugin 工程里写业务模块路径假设:保持插件通用,差异由 extension 配置。

追问

  • 如何调试 plugin 代码?答:以 JVM 调试方式附加到 Gradle daemon 或运行 plugin 测试用例打断点。
  • includeBuild 的 plugin 能被另一个 included build 引用吗?答:纳入构建间的解析规则较复杂,通常通过主工程统一组合;具体边界以 Gradle 文档为准。

04.8.3.1-027 convention plugin 内部如何应用并配置插件?

一句话结论

在 apply(project) 中用 project.plugins.apply(...) 应用基础插件,再通过 project.extensions.getByType<T>() 取 extension 做统一配置;差异项留给工程覆盖。

概念解释

插件收到 Project 后完成"应用插件 + 配置 extension + 注册任务"三步。封装的是团队约定的默认值,而不是锁死所有配置;工程脚本可在插件应用后继续调整。

原理流程

  1. 实现 Plugin<Project> 接口。
  2. apply 内应用 JVM、Kotlin 等基础插件。
  3. 获取 extension 写入编译目标、依赖平台等约定。
  4. 注册必要任务并声明输入输出。

代码或图示

class KotlinConventionPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        with(project) {
            plugins.apply("org.jetbrains.kotlin.jvm")
            the<org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension>().compilerOptions {
                jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
            }
        }
    }
}

常见误区

  • 在 plugin 里用 afterEvaluate 等待工程配置:约定插件应在 apply 期完成声明,避免延迟配置。
  • 插件读取具体工程目录硬编码:通过 project.layout.projectDirectory 解析相对路径。

追问

  • 插件如何给工程加默认依赖?答:在 apply 中访问 project.dependencies 并 add 到对应 configuration。
  • 工程想覆盖插件默认值怎么办?答:插件应用后工程脚本再写同名配置,后写覆盖;默认值设计为可空或提供 override 入口。

04.8.3.1-028 自定义插件中如何访问 extension?

一句话结论

用 project.extensions.getByType<T>() 按类型获取,或 findByType<T>() 判空;注册新 extension 用 project.extensions.create("name", Type::class.java)。

概念解释

extension 注册表按类型与名字双索引。插件内取其他插件注册的扩展时按类型最稳妥;自定义配置模型则先 create 再在工程脚本中按名字配置。

原理流程

  1. 插件 apply 顺序保证目标 extension 已注册。
  2. getByType 从注册表取出强类型对象。
  3. 写入约定值或读取工程配置。
  4. 未注册时 findByType 返回 null,可做兼容分支。

代码或图示

interface AppExtension {
    var featureFlag: String
}

class AppPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val ext = project.extensions.create("app", DefaultAppExtension::class.java)
        project.afterEvaluate { println(ext.featureFlag) }
    }
}

常见误区

  • 取 extension 时插件尚未应用:调整 apply 顺序或显式先依赖基础插件。
  • 用名字字符串强转忽略类型检查:优先按类型获取。

追问

  • extension 属性如何支持懒值?答:extension 内持有 Property<T>,由 Project 实例化注入。
  • 多个插件注册同名 extension 怎么办?答:注册重名会冲突,命名应带插件前缀。

04.8.3.1-029 plugin 与 buildSrc 如何共享版本目录?

一句话结论

版本目录文件在主工程 gradle/ 下时,buildSrc 与独立 plugin 工程可通过各自脚本声明对该目录的引用(具体引用语法以 Gradle 当前版本为准);更稳妥的做法是把工具链版本单独集中管理并在两边对齐。

概念解释

Version Catalog 是工程级声明,默认供主构建使用。buildSrc 作为前置工程有自己的解析环境;独立 plugin 工程同理。跨工程共享目录需要显式关联,不能假设主工程目录自动可见。

原理流程

  1. 在目录文件中定义插件与依赖版本。
  2. buildSrc/plugin 脚本按 Gradle 支持方式引用目录或复制必要版本声明。
  3. 两边解析同一组坐标。
  4. 版本升级时集中改目录并回归两边构建。

代码或图示

// buildSrc/build.gradle.kts 中声明对版本目录的引用(语法以当前 Gradle 文档为准)
// dependencyResolutionManagement 或 dependencies 中读取 libs 别名

常见误区

  • 假设 buildSrc 自动继承主工程 libs 访问器:通常需要显式配置后才有生成访问器。
  • 两边各写一份版本号:容易漂移,应单一来源。

追问

  • 工具链插件版本放哪里最稳?答:根目录版本目录统一登记,主工程与构建工程按文档方式引用。
  • 引用失败如何排查?答:先确认目录文件位置与 Gradle 版本支持范围,再检查脚本编译错误。

04.8.3.1-030 为什么 buildSrc 改动有时会触发全量重编译?

一句话结论

buildSrc 编译产物是所有构建脚本的 classpath 输入;它一旦变化,脚本编译缓存与依赖该 classpath 的任务判定都会失效,连带大面积重新配置与编译。

概念解释

Gradle 按输入哈希判定缓存命中。buildSrc class 进入脚本 classpath 后,其哈希成为脚本缓存与部分任务输入的一部分。改动 buildSrc 类即改变该哈希,缓存条目整体作废。

原理流程

  1. 修改 buildSrc 源码。
  2. buildSrc 任务重新编译,产物哈希变化。
  3. 脚本编译缓存输入失配,脚本重编译。
  4. 依赖脚本 classpath 的任务重算输入,大量任务重跑。

代码或图示

修改 buildSrc/*.kt
  → buildSrc jar 重编
  → 脚本 Kotlin DSL 缓存失效
  → 各模块配置阶段重跑
  → 编译任务输入重算(增量范围内重编)

常见误区

  • 频繁调整 buildSrc 注释/格式也触发失效:任何源码变动都改变 class 哈希,属预期行为。
  • 把高频变动的业务代码塞进 buildSrc:放大失效面,应移出。

追问

  • 如何降低 buildSrc 失效影响?答:保持其稳定、只放构建工具;频繁变化的逻辑下沉为独立 plugin 并控制依赖面。
  • buildSrc 依赖升级也会失效吗?答:会,依赖 classpath 变化同样计入输入哈希。

04.8.3.1-031 多模块统一依赖版本如何在 convention plugin 中收口?

一句话结论

在 plugin 内统一应用平台 BOM、添加公共依赖配置与编译约定,业务模块只引用 plugin 并声明自身特有依赖;版本与公共库不再散落在各模块脚本。

概念解释

收口目标是"一处改版本、全工程生效"。plugin 负责对齐 Kotlin 标准库、日志门面、JSON 库等公共依赖;模块差异通过 extension 开关或单独 dependencies 表达。

原理流程

  1. plugin 应用基础插件并解析版本目录中的 BOM。
  2. 给公共 configuration 添加平台依赖与公共库。
  3. 配置编译参数与测试约定。
  4. 业务模块应用 plugin 后补充私有依赖。

代码或图示

override fun apply(project: Project) = with(project) {
    plugins.apply("org.jetbrains.kotlin.jvm")
    dependencies {
        add("implementation", platform(libs.bundles.jackson.platform))
        add("implementation", libs.kotlin.stdlib)
        add("testImplementation", libs.junit.jupiter)
    }
}

常见误区

  • plugin 把所有依赖都强加给不需要的模块:用 extension 开关区分 app/lib 类型模块。
  • 模块脚本绕过 plugin 直接写死版本号:评审时应拦截,版本只进目录与 plugin。

追问

  • 不同模块需要不同版本怎么办?答:平台对齐为主,少数例外在模块显式声明并注释原因。
  • 公共测试依赖放哪里?答:plugin 统一加到 testImplementation,避免每个模块重复写。

04.8.3.1-032 convention plugin 中注册任务为什么要用懒注册?

一句话结论

插件在 apply 阶段被调用,此时工程尚未配置完;用 tasks.register 懒注册任务并延迟读取属性,避免在配置阶段强制实例化与顺序耦合。

概念解释

插件 apply 早于工程脚本配置。若插件内部 create 任务并立即读工程属性,可能读到默认值。懒注册把任务实例化推迟到任务图确定后,属性通过 Provider 连接,配置顺序更健壮。

原理流程

  1. plugin apply 时只调用 register 登记任务。
  2. 配置块内用 Provider 绑定 extension 值。
  3. 任务被选中执行时才实例化并读取最终配置。
  4. 未被选中的任务不产生实例化成本。

代码或图示

tasks.register("qualityReport") {
    group = "verification"
    doLast {
        // 动作内读取运行期值,不依赖配置阶段顺序
    }
}

常见误区

  • 插件内用 tasks.named(...).get() 立即取任务:强制实例化,破坏懒加载。
  • 在 apply 阶段读工程脚本才设置的属性:应通过 Provider 或 afterEvaluate 谨慎处理,优先改造为声明式绑定。

追问

  • 插件必须依赖工程配置才能注册任务怎么办?答:用 afterEvaluate 兜底,但应评估是否能改为 extension 驱动。
  • 懒注册任务默认会执行吗?答:不会,需被其他任务依赖或命令行显式调用。

04.8.3.1-033 多模块中应用与库模块如何使用不同 plugin?

一句话结论

按模块类型拆分 convention plugin(如 library-convention、application-convention),各模块在 plugins{} 选择对应插件;公共部分由底层 plugin 组合复用。

概念解释

应用模块可打 fat jar、配置 mainClass;库模块只暴露 API、不打包运行时。二者编译约定相同,打包与依赖可见性不同。拆分插件让差异显式化,避免一个 plugin 内堆满 if 分支。

原理流程

  1. 基础 plugin 封装 Kotlin 编译与测试约定。
  2. library plugin 应用基础 plugin 并配置 API 可见性。
  3. application plugin 应用基础 plugin 并配置归档与主类。
  4. 各模块按需声明对应 plugin。

代码或图示

// 模块脚本对比
plugins { id("com.example.convention.library") }
// 另一模块
plugins { id("com.example.convention.application") }

常见误区

  • 用模块名前缀在单个 plugin 内判断类型:脆弱,改名即失效。
  • 应用模块也按库配置暴露传递依赖:扩大外部依赖面。

追问

  • 共享的插件逻辑如何复用?答:上层 plugin 在内部 apply 基础 plugin,再叠加自身配置。
  • 模块类型判断有没有通用约定?答:可通过是否应用 application 插件、extension 标记来识别,避免解析目录名。

04.8.3.1-034 buildSrc 中可以放业务运行时代码吗?

一句话结论

不应该:buildSrc 只服务构建脚本,产物不进业务 jar;业务运行时代码应放在普通库模块并被应用模块依赖。

概念解释

把业务类放 buildSrc 会造成误解:IDE 与编译期可见,但打包产物中不存在,运行期 ClassNotFound。两类代码的生命周期、依赖与产物边界不同,必须分离。

原理流程

  1. buildSrc 产物只进入脚本 classpath。
  2. 业务编译 classpath 来自模块 dependencies 解析。
  3. 两者不互相传递。
  4. 业务类迁移到库模块后由应用模块依赖引入。

代码或图示

错误做法:buildSrc/src/main/kotlin/com/example/domain/Order.kt
正确做法:shared-domain/src/main/kotlin/com/example/domain/Order.kt

常见误区

  • 图方便把共享 DTO 放 buildSrc:打包后缺失,线上报错。
  • 认为"IDE 能跳转就是可用":IDE classpath 与产物 classpath 不一致。

追问

  • 构建脚本和业务都要用到的常量怎么办?答:纯字面量可在构建工程与业务模块各声明,或抽到零依赖常量库被两边依赖。
  • buildSrc 能依赖业务模块吗?答:构建期依赖业务模块会形成循环,不推荐。

04.8.3.1-035 plugin marker 工件与插件主工件是什么关系?

一句话结论

marker 工件是只声明插件 id 与实现坐标的轻量构件,主工件是真正含插件类的 jar;Gradle 先解析 marker 找到实现,再拉取主工件。

概念解释

plugins{} 块按插件 id 解析,id 对应 marker 模块。marker 内记录实现插件的 group/artifact/version。分离 marker 是为了让插件 id 与实现坐标解耦,便于重打包与内部镜像。

原理流程

  1. 插件工程用 gradlePlugin 插件生成 marker 与主 jar。
  2. 发布时两个构件进入仓库。
  3. 主工程按 id 拉取 marker。
  4. marker 指向主 jar,Gradle 下载并加载插件类。

代码或图示

gradlePlugin {
    plugins {
        create("myPlugin") {
            id = "com.example.my-plugin"
            implementationClass = "com.example.MyPlugin"
        }
    }
}

常见误区

  • 只发布主 jar 不发布 marker:plugins{} 按 id 解析不到,脚本报错。
  • 手工拼接 marker 坐标:应由 java-gradle-plugin/gradlePlugin 约定生成。

追问

  • 内部仓库如何代理插件门户?答:在 pluginManagement 仓库中加内部镜像,marker 与实现均从镜像拉取。
  • 插件版本冲突如何排查?答:查看插件解析报告,确认 marker 与主工件版本一致。

04.8.3.1-036 Version Catalog 解决什么问题?

一句话结论

Version Catalog(版本目录)用一份 TOML 文件集中声明依赖与插件版本、别名与分组,在多模块工程中提供类型安全、可校验的统一版本来源,替代散落在脚本里的字符串坐标。

概念解释

目录包含 [versions]、[libraries]、[bundles]、[plugins] 四段。Gradle 根据目录生成访问器(如 libs.jackson.databind),脚本中按别名引用;别名拼错在脚本编译期即可发现。

原理流程

  1. 在 gradle/libs.versions.toml 定义版本、库坐标、捆绑包与插件。
  2. Gradle 解析目录生成类型安全访问器。
  3. 模块脚本用 libs.xxx 引用,展开为坐标与版本。
  4. 升级时只改目录一处,全工程同步。

代码或图示

[versions]
jackson = "2.17.2"

[libraries]
jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version = "2.0.20" }

常见误区

  • 以为目录能解决版本冲突:它只统一声明,冲突仍由解析规则与 BOM 裁决。
  • 别名随意改名不影响其他模块:访问器名跟随别名,重命名要全局同步。

追问

  • 目录文件位置有约定吗?答:默认 gradle/libs.versions.toml,自定义路径在 settings 中显式声明。
  • 目录能管理 SNAPSHOT 版本吗?答:能声明坐标与版本,但快照刷新策略仍由仓库缓存规则控制。

04.8.3.1-037 libs.versions.toml 的四段结构分别是什么?

一句话结论

[versions] 定义可复用版本号,[libraries] 定义库坐标,[bundles] 把多个库打成一组,[plugins] 定义插件 id 与版本;库可通过 version.ref 引用版本段。

概念解释

版本段集中存放版本号字符串,库段用 module 写坐标、version.ref 引用版本段,避免版本号重复抄写。bundle 是别名到多个库的映射,便于一次性添加一组相关依赖。

原理流程

  1. 版本段声明具名版本。
  2. 库段引用版本段或直接写 version。
  3. bundle 段列出库别名列表。
  4. 插件段独立维护插件 id 与版本。

代码或图示

[versions]
kotlin = "2.0.20"

[libraries]
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }

[bundles]
jackson = ["jackson-databind", "jackson-module-kotlin"]

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

常见误区

  • bundle 内别名拼写错误:目录校验阶段报错,应在同步时修复。
  • 在库段写插件坐标:插件必须放 [plugins],由 alias(...) 引用。

追问

  • 版本段能否做版本区间?答:目录一般写确定版本;区间与动态版本不适合作为统一收口方式。
  • 如何引入带 classifier 的库?答:库声明中加 classifier 字段,具体字段名以当前 Gradle 文档为准。

04.8.3.1-038 版本目录生成的访问器命名规则是什么?

一句话结论

别名按 - 与 . 分段转驼峰:jackson-databind 变成 libs.jackson.databind,插件别名 kotlin-jvm 变成 libs.plugins.kotlin.jvm;段顺序与别名段顺序一致。

概念解释

Gradle 把别名单词分隔符拆开,首段后其余段作为属性层级。含连字符的词合并为驼峰。访问器在脚本编译期生成,重命名别名会同步改变访问器路径。

原理流程

  1. 解析别名分段。
  2. 每段转驼峰命名。
  3. 库访问器挂在 libs 下,插件挂在 libs.plugins 下。
  4. 脚本按层级链访问,拼错即编译错误。

代码或图示

[libraries]
mockk-core = { module = "io.mockk:mockk", version = "1.13.11" }
dependencies {
    testImplementation(libs.mockk.core)
}

常见误区

  • 以为别名下划线也参与转换:目录别名约定用连字符,下划线行为以生成规则为准。
  • 多层别名与 bundle 访问器混淆:bundle 访问器直接返回依赖集合,用于 implementation(libs.bundles.xxx)。

追问

  • 访问器名与 Kotlin 关键字冲突怎么办?答:调整别名分段,避免生成非法标识符。
  • 如何查看生成了哪些访问器?答:IDE 对 libs. 触发补全即可看到目录解析结果。

04.8.3.1-039 版本目录与 buildSrc 常量共享版本相比有何优劣?

一句话结论

版本目录提供声明式 TOML、类型安全访问器与目录级校验,适合依赖与插件版本收口;buildSrc 常量适合构建逻辑而非版本清单,前者是现代推荐方式。

概念解释

buildSrc 中写 const val 是硬编码在 Kotlin 类里,改动需编译 buildSrc 并使脚本缓存失效;目录是数据文件,解析轻量且可被工具(依赖升级插件)识别。两者也可共存:目录管版本,buildSrc 管任务类型。

原理流程

  1. 版本升级只改 TOML 数值。
  2. Gradle 重新解析目录生成访问器。
  3. 模块脚本无需改动。
  4. buildSrc 常量方式则需改 Kotlin 源码并重编译前置工程。

代码或图示

// 旧方式:buildSrc 常量
const val JACKSON_VERSION = "2.17.2"

// 现代方式:目录 version.ref 引用

常见误区

  • 在目录里塞复杂构建逻辑:目录只做声明,逻辑归 plugin。
  • 把运行期配置项(环境地址)写进目录:版本目录面向构建依赖,不含环境配置。

追问

  • 团队依赖升级工具读哪种格式?答:多数工具识别 TOML 版本目录或锁文件,常量类识别能力有限。
  • 目录能被多个独立工程共享吗?答:可通过打包目录构件或复合构建引用,具体方式以 Gradle 文档为准。

04.8.3.1-040 bundle 在依赖声明中如何使用?

一句话结论

bundle 是目录中一组库别名的命名集合,脚本中 implementation(libs.bundles.xxx) 一次性加入该组全部依赖,适合把配套库成组引入。

概念解释

bundle 不声明版本,只聚合已有库别名。典型场景:JSON 配套(databind + kotlin module)、测试套件(断言 + mock + 运行器)。成组引入避免漏配其中某一个库。

原理流程

  1. 目录 [bundles] 列出库别名数组。
  2. Gradle 生成 bundle 访问器。
  3. 脚本把 bundle 加入 configuration。
  4. 解析时逐个展开为独立依赖条目。

代码或图示

[bundles]
test = ["junit-jupiter-api", "mockk", "kotest-assertions"]
dependencies {
    testImplementation(libs.bundles.test)
}

常见误区

  • bundle 内混入只应 compileOnly 的库:配置可见性不同,不能强绑成一组。
  • 给 bundle 单独写版本:版本属于库条目,bundle 不持有版本。

追问

  • 模块只要组内其中一个库怎么办?答:单独引用对应库别名,不使用 bundle。
  • bundle 展开后能否再排除单项?答:按单依赖 exclude 规则处理,bundle 只是声明聚合。

04.8.3.1-041 目录中版本引用(version.ref)如何工作?

一句话结论

库或插件条目的 version.ref 指向 [versions] 中的具名版本,解析时替换为该版本号;同一版本被多处引用时升级只改版本段一处。

概念解释

version.ref 建立条目与版本名的关联,避免在每个库条目重复写版本字符串。版本段缺失或引用名拼错会在目录解析阶段报错。版本段也可只被插件引用。

原理流程

  1. [versions] 定义 name = "x.y.z"。
  2. 条目写 version.ref = "name"。
  3. 解析时按名查版本段替换。
  4. 生成坐标进入依赖集合。

代码或图示

[versions]
kotlinx-serialization = "1.6.3"

[libraries]
serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }

常见误区

  • 条目同时写 version 与 version.ref:二选一,重复声明会报错。
  • 版本段改名后遗漏引用:目录校验会指出未解析引用。

追问

  • 版本段能写动态版本吗?答:技术上可写,但生产构建应锁定确定版本以保证可复现。
  • 平台 BOM 版本也放版本段吗?答:放,BOM 库条目通过 platform(...) 引入并引用版本段。

04.8.3.1-042 目录 [plugins] 段与依赖库段有何不同?

一句话结论

[plugins] 段登记插件 id 与版本,供 alias(libs.plugins.xxx) 在 plugins{} 块使用;库段登记运行/编译依赖坐标,二者解析渠道与 classpath 不同。

概念解释

插件从 pluginManagement 仓库解析 marker 与实现,库从 dependencyResolutionManagement 仓库解析。因此目录虽在同一文件,条目进入两套解析链。插件别名只能用于 plugins{} 或 apply false。

原理流程

  1. [plugins] 条目含 id 与版本。
  2. alias(...) 在 plugins 块解析插件 marker。
  3. 库条目在 dependencies 块解析模块构件。
  4. 两套 classpath 互不混入。

代码或图示

[plugins]
detekt = { id = "io.gitlab.arturbosch.detekt", version = "1.23.7" }
plugins {
    alias(libs.plugins.detekt)
}

常见误区

  • 把插件 id 写进 [libraries]:dependencies 解析不到插件 marker。
  • 在 dependencies 中 alias(libs.plugins...):用途非法,插件只能在 plugins 块引用。

追问

  • 本地 convention plugin 进目录吗?答:本地 includeBuild 提供 id,目录可只写 id 不写版本;已发布插件再登记版本。
  • 插件版本与 Kotlin 编译器版本对齐怎么管?答:在版本段用同一版本名引用 Kotlin 插件与标准库。

04.8.3.1-043 版本目录能否在 buildSrc 中使用?

一句话结论

可以,但需要按 Gradle 当前版本支持的方式为 buildSrc 工程显式关联目录;默认情况下主工程目录的 libs 访问器不会自动出现在 buildSrc 脚本中。

概念解释

buildSrc 是独立前置工程,有自己的依赖解析环境。要复用同一目录,需在其构建脚本中声明目录引用方式(具体 API 以当前 Gradle 文档为准);若关联配置成本高,可在 buildSrc 内只维护插件工具版本。

原理流程

  1. 确认 Gradle 版本对 buildSrc 引用目录的支持。
  2. 在 buildSrc 构建脚本中关联主目录文件或复制必要声明。
  3. 解析生成 buildSrc 侧访问器。
  4. 两边版本保持人工或脚本对齐。

代码或图示

# 待确认:buildSrc 引用主工程 libs.versions.toml 的精确语法随 Gradle 版本变化;
# 落地前核对当前 Gradle 版本文档中 dependencyResolutionManagement 与 versionCatalogs 配置。

常见误区

  • 直接在 buildSrc 脚本写 libs.xxx 不报错才怪:未关联目录时访问器不存在。
  • 两边版本各写一份不核对:升级时容易漏改导致工具链不一致。

追问

  • 工具链插件版本放哪最不容易漂移?答:集中到主目录,buildSrc 按文档方式引用;无法引用时在评审中强制核对。
  • 关联后升级目录需要重新同步吗?答:下次构建解析目录即可,脚本缓存按输入哈希更新。

04.8.3.1-044 目录别名冲突或重复会怎样?

一句话结论

同一文件内别名重复定义会在目录解析时报错;不同库生成相同访问器路径也会冲突,需要调整别名分段避免碰撞。

概念解释

访问器由别名生成,别名设计要保证段路径唯一。冲突在目录加载阶段暴露,不会静默选其一。插件 id 与库别名是不同命名空间,但库之间、插件之间各自不能撞名。

原理流程

  1. 解析 TOML 构建别名索引。
  2. 检测重复键与重复访问器路径。
  3. 冲突即终止配置并报错。
  4. 修正别名后重新解析。

代码或图示

# 冲突示例:两个别名生成同一访问器,需改名区分
[libraries]
jackson-core = { module = "...:core", version = "1" }
jackson.core = { module = "...:other", version = "1" }

常见误区

  • 靠改版本号解决冲突:冲突是命名问题,与版本无关。
  • 忽略目录解析警告继续构建:别名冲突通常直接失败,必须修复。

追问

  • 分组前缀能否减少冲突?答:按领域加段,如 logging-slf4j 与 logging-logback,访问器分层清晰。
  • 第三方库同名不同 group 怎么区分?答:别名加业务前缀,坐标写全 group 避免歧义。

04.8.3.1-045 平台 BOM 在版本目录中如何声明?

一句话结论

把 BOM 当作普通库条目声明坐标与版本,脚本中通过 platform(libs.xxx) 加入 dependencies;BOM 负责对齐其管理的一组传递依赖版本。

概念解释

BOM(Bill of Materials)是一份版本清单模块,自身不含代码。platform(...) 把它加到对应 configuration,解析时以 BOM 约束为准选择成员版本。目录中 BOM 条目与普通库写法相同。

原理流程

  1. 目录声明 BOM 坐标与版本。
  2. 脚本 implementation(platform(libs.bom))。
  3. 解析器应用 BOM 约束到成员依赖。
  4. 成员库不显式写版本时跟随 BOM。

代码或图示

[libraries]
jackson-bom = { module = "com.fasterxml.jackson:jackson-bom", version = "2.17.2" }
dependencies {
    implementation(platform(libs.jackson.bom))
    implementation(libs.jackson.databind)
}

常见误区

  • 加了 BOM 又在成员库写死更高版本:显式版本优先,BOM 对齐被绕过。
  • 把 BOM 加错 configuration:平台约束需加在生效的编译/运行配置上。

追问

  • BOM 对齐失败时看什么?答:查依赖解析结果,确认成员版本来自 BOM 还是被显式覆盖。
  • 多个 BOM 同时约束同一依赖怎么办?答:按 Gradle 平台优先级规则裁决,冲突时显式指定并记录原因。

04.8.3.1-046 目录中如何声明带 classifier 的构件?

一句话结论

库条目在坐标外加 classifier 字段(字段名以当前 Gradle 文档为准),用于引用测试 jar、sources 等附加构件;版本仍通过版本段或直接版本管理。

概念解释

同一模块可能发布主 jar 与 classifier 产物(如 -tests、-sources)。目录条目区分主构件与附加构件,脚本按别名分别引入。附加构件通常用于测试编译或源码审计,不进运行时。

原理流程

  1. 仓库中模块按 group:artifact:version:classifier 发布构件。
  2. 目录条目记录 classifier。
  3. 解析时拉取对应附加 jar。
  4. 加入指定 configuration。

代码或图示

[libraries]
example-tests = { module = "com.example:lib", version.ref = "example", classifier = "tests" }
dependencies {
    testImplementation(libs.example.tests)
}

常见误区

  • 把 classifier 写进 artifact 名字段:解析坐标会拼接错误,应使用独立 classifier 字段。
  • 附加构件混入运行时配置:按需加入 test 或编译期配置。

追问

  • sources jar 怎么引入?答:同样按 classifier 声明,通常仅用于 IDE 附件,不进业务运行 classpath。
  • 仓库不发布 classifier 构件会怎样?答:解析时报构件缺失,需确认发布侧配置。

04.8.3.1-047 哪些依赖不适合进版本目录?

一句话结论

一次性本地文件依赖、按环境临时调试的坐标、仅单个模块实验性引入的库不必进目录;目录收口的是工程内复用、需要统一版本的正式依赖。

概念解释

目录的价值在于共享与可升级,只为单个脚本服务的临时条目只会增加噪音。本地 files(...) 依赖不属于模块坐标,也不进目录。实验库确认保留后再迁入目录。

原理流程

  1. 判断依赖是否多模块复用或需版本对齐。
  2. 正式复用条目迁入目录并起别名。
  3. 临时依赖留在模块脚本并标注用途。
  4. 实验转正式后补登目录。

代码或图示

dependencies {
    // 临时本地文件,不进目录
    implementation(files("libs/local-tool.jar"))
}

常见误区

  • 目录堆积大量只被引用一次的别名:可读性下降,升级时评审面变大。
  • 把插件快照调试坐标固化进目录:污染统一版本基线。

追问

  • 本地 Maven 仓库依赖能进目录吗?答:坐标可声明,但仓库来源由 repositories 配置决定。
  • 如何清理目录冗余条目?答:检索别名引用次数,无引用且无保留计划的删除。

04.8.3.1-048 版本目录与旧版 ext 共享版本方式相比有什么实质变化?

一句话结论

ext 共享的是无类型字符串常量,目录共享的是结构化坐标声明并带类型安全访问器与解析校验;前者靠约定维护,后者在脚本编译期与目录解析期双重检查。

概念解释

早期多模块用根项目 ext { versions = [...] } 或 buildSrc 常量传版本号,坐标字符串仍手写。目录把 group/artifact/version 结构化,别名访问器在编译期校验存在性,目录错误更早暴露。

原理流程

  1. 旧方式:脚本拼坐标字符串,版本来自 ext 常量。
  2. 新方式:目录条目结构化为模块描述符。
  3. Gradle 生成访问器并校验目录完整性。
  4. 脚本只引用别名,不手写坐标片段。

代码或图示

// 旧 Groovy 风格:版本与坐标分散
implementation "com.fasterxml.jackson.core:jackson-databind:$jacksonVersion"

常见误区

  • 以为目录只是把 ext 换个文件存:它还带来访问器生成与条目校验,能力不止常量托管。
  • 迁移时保留手写坐标双轨:长期应逐步收敛到别名。

追问

  • 目录支持版本锁定文件吗?答:Gradle 依赖锁定是独立机制,目录负责声明,锁定文件记录解析结果(以当前版本功能为准)。
  • 老脚本能否逐步迁移到目录?答:可以,按模块分批替换坐标为别名,目录先行建立。

04.8.3.1-049 版本目录在哪个阶段被校验?

一句话结论

目录在 settings 解析后的配置早期被加载校验:别名、坐标格式、版本引用、plugin id 完整性在此阶段检查,错误先于任务执行暴露。

概念解释

目录解析早于各 build 脚本配置,因此条目拼写错误、缺失版本段、坏模块坐标会在配置期失败,不会拖到编译任务。访问器生成也基于校验通过的目录。

原理流程

  1. settings 脚本加载目录定义。
  2. 解析器校验 TOML 结构与引用闭合。
  3. 生成访问器元信息供脚本编译。
  4. 模块脚本引用别名时再做存在性检查。

代码或图示

settings 解析 → 目录校验 → 脚本编译(访问器检查)→ 模块配置 → 任务执行

常见误区

  • 以为目录错误要等编译任务才报:实际配置早期即失败。
  • 运行期才新增目录条目却不同步脚本:访问器缺失在脚本编译期暴露。

追问

  • 目录校验能否跳过坏条目继续?答:错误条目阻断构建,需修复后再同步;不提供静默忽略。
  • 如何在 CI 上提前验证目录?答:执行配置阶段任务(如 help 或依赖解析任务)即可触发校验。

04.8.3.1-050 如何升级目录中一组互相兼容的版本?

一句话结论

用同一版本段管理配套库与插件版本,升级时改版本段一处;BOM 管理的成员库只升 BOM 版本,成员不显式锁定版本,由平台对齐。

概念解释

配套版本(如 Kotlin 插件与标准库、Jackson 全家桶)必须兼容。版本段复用保证同步修改;BOM 则在解析期约束成员版本。升级后回归编译、测试与生成代码链路。

原理流程

  1. 确认上游兼容版本范围与发布说明。
  2. 修改版本段或 BOM 版本号。
  3. 重新解析依赖,检查冲突报告。
  4. 跑构建与测试验证生成代码与二进制兼容。

代码或图示

[versions]
kotlin = "2.0.20"   # 升级时只改此处,插件与 stdlib 同步

常见误区

  • 只升插件不升标准库:编译器与 stdlib 版本错位会出现字节码或 API 兼容问题。
  • 跳过兼容矩阵直接追最新版:先核对 Kotlin、KSP、编译器插件配套版本。

追问

  • 升级后生成代码报错怎么办?答:检查注解处理/编译器插件是否支持新 Kotlin 版本,按官方兼容表升级对应插件。
  • 如何记录一次升级的变动?答:依赖变更与验证结果写入变更说明,便于回滚定位。

04.8.3.1-051 多模块工程 settings.gradle.kts 的 include 规则是什么?

一句话结论

include("模块名") 按工程路径纳入子模块,默认目录名为名字去掉冒号;模块工程路径以 :xxx 表示,根工程路径为 :。

概念解释

settings 决定工程树,include 的顺序影响配置顺序但不影响依赖关系。模块目录可通过 project().projectDir 重定向。未 include 的目录不参与构建,其脚本也不被加载。

原理流程

  1. settings 脚本列出 include 条目。
  2. Gradle 为每个条目创建工程节点并定位目录。
  3. 加载各工程 build 脚本。
  4. 模块间依赖通过工程坐标声明。

代码或图示

include("domain", "infrastructure", "app")
project(":infrastructure").projectDir = file("modules/infrastructure")

常见误区

  • 目录建了但没 include:模块不进任务图,产物缺失。
  • 工程名与目录名不一致却不配置 projectDir:解析到错误目录。

追问

  • 多级模块怎么写?答:include("web:api") 对应嵌套目录,工程路径为 :web:api。
  • 如何列出当前纳入的工程?答:运行工程列表任务查看 settings 解析结果。

04.8.3.1-052 模块间 project 依赖如何声明?

一句话结论

用 implementation(project(":模块名")) 声明对另一模块的依赖,Gradle 按工程路径解析其产物;模块间依赖形成有向图,不应成环。

概念解释

工程依赖替代了发布本地构件的需要:主构建直接使用上游模块的 jar 与 class 输出。依赖配置(api/implementation)同样决定向下游的传递可见性。

原理流程

  1. 脚本 add 工程依赖到 configuration。
  2. Gradle 把对应模块输出纳入 classpath。
  3. 任务图按依赖排序执行上游编译。
  4. 形成环依赖时报配置错误。

代码或图示

dependencies {
    implementation(project(":domain"))
    api(project(":common-model"))
}

常见误区

  • 模块间循环依赖:编译顺序无法确定,应调整边界拆分模块。
  • 下游直接依赖上游的内部实现类:说明 api 边界没守住。

追问

  • 工程依赖与外部坐标依赖能互相替换吗?答:复合构建中可做 substitute 替换;普通多模块直接用 project 依赖。
  • 测试源码能否被下游依赖?答:测试类默认不对外,需要测试 jar 配置单独发布。

04.8.3.1-053 复合构建 includeBuild 解决什么问题?

一句话结论

includeBuild 把一个独立 Gradle 工程纳入当前构建,用于本地联调尚未发布的库或插件,按替换规则让主工程解析到本地工程产物而非仓库坐标。

概念解释

单仓多模块用 project 依赖即可;跨仓库联调时,源码在另一个目录,复合构建提供不发布即可替换坐标的能力。被纳入工程按独立构建运行,产物回供给主构建解析。

原理流程

  1. settings 中 includeBuild("../other")。
  2. 可选声明 dependencySubstitution 映射坐标到本地工程。
  3. 主构建解析依赖时命中替换规则。
  4. 使用本地工程输出构件。

代码或图示

includeBuild("../shared-lib")

常见误区

  • 把 includeBuild 当多模块 include 用:二者结构与替换语义不同,混用会让工程树混乱。
  • 纳入工程自身还有未提交改动导致联调不可复现:联调环境需记录纳入工程版本。

追问

  • 被纳入工程需要安装到本地仓库吗?答:不需要,复合构建直接消费其构建产物。
  • 复合构建能传递依赖给下一层纳入工程吗?答:解析规则逐层独立,复杂嵌套以 Gradle 文档为准。

04.8.3.1-054 复合构建中的 substitute 替换规则如何写?

一句话结论

在 includeBuild 块内用 substitute(module("group:name")).using(project(":子工程")) 把外部坐标映射到被纳入工程的指定子工程产物。

概念解释

替换规则只在当前复合构建解析期生效,不改动发布仓库坐标。未命中替换的坐标仍从仓库解析。规则可按模块名精确替换,避免整仓重定向。

原理流程

  1. includeBuild 引入外部工程。
  2. 配置 substitution 映射坐标到工程路径。
  3. 主构建解析该坐标时查表命中。
  4. 改用本地工程产物,仓库构件被跳过。

代码或图示

includeBuild("../shared-lib") {
    dependencySubstitution {
        substitute(module("com.example:shared-lib")).using(project(":core"))
    }
}

常见误区

  • 替换坐标与本地工程产物不一致:编译/打包出现类缺失或版本不符。
  • 在 CI 上保留本地路径替换:会导致构建找不到相对路径,应按环境分离配置。

追问

  • 如何确认替换已生效?答:查看依赖解析结果,对应模块来源显示为本地纳入工程。
  • 替换规则能按变体区分吗?答:替换针对模块坐标;变体选择仍由 configuration 规则处理。

04.8.3.1-055 本地依赖的库源码改动但不想重新发布,怎么联调?

一句话结论

用复合构建 includeBuild + substitute 把该库坐标指向本地源码工程,主构建直接消费本地编译产物;修改库源码后随主构建增量重编,无需安装到本地仓库。

概念解释

传统方式要先 publishToMavenLocal 再让主工程解析 mavenLocal,步骤多且容易残留旧快照。复合构建在同一构建会话内联动两边任务,源码改动即时反映。

原理流程

  1. 本地检出待联调库源码。
  2. settings 纳入并配置坐标替换。
  3. 主构建解析时使用本地库工程输出。
  4. 改动库源码触发其编译任务,主工程重新链接。

代码或图示

主工程 ──解析 com.example:lib:1.0-SNAPSHOT──▶ substitute ──▶ ../lib 工程产物

常见误区

  • 同时存在 mavenLocal 旧快照:解析来源优先规则可能命中旧包,需排除干扰。
  • 本地库分支与主工程预期版本不匹配:API 漂移导致编译错误,应先对齐分支。

追问

  • 联调结束如何切回发布版本?答:移除 includeBuild 与替换规则,恢复从仓库解析。
  • 复合构建支持调试库源码吗?答:主构建 classpath 链接本地工程输出,IDE 可关联源码断点。

04.8.3.1-056 根项目统一配置时 subprojects/allprojects 有什么反模式?

一句话结论

allprojects { }/subprojects { } 对全部工程批量施加配置,隐式耦合、破坏配置隔离,现代约定是用 convention plugin 按类型显式应用,只在需要的模块收口。

概念解释

批量块在配置阶段遍历工程树,容易给不该配置的模块(如构建工程)强加依赖与任务;模块差异被埋在循环条件里难以追踪。convention plugin 由模块主动声明,边界清晰。

原理流程

  1. 旧写法:根脚本 subprojects 块内统一加仓库、依赖、编译参数。
  2. 所有子工程被无条件配置。
  3. 新写法:公共能力封装为 plugin,模块 plugins{} 选择应用。
  4. 配置来源显式可追溯到模块脚本。

代码或图示

// 不推荐:隐式覆盖所有子工程
subprojects {
    repositories { mavenCentral() }
}

// 推荐:plugin 显式应用
plugins { id("com.example.convention.kotlin") }

常见误区

  • 用 subprojects 给测试模块加运行时依赖:非测试模块也被污染。
  • 在批量块内读子工程名字做分支:模块改名即失效,条件脆弱。

追问

  • 根项目还能做哪些全局配置?答:settings 层仓库、版本目录、根任务聚合;模块级配置尽量下沉 plugin。
  • 批量块与 convention plugin 性能差异?答:后者按需实例化与配置,配置避免友好。

04.8.3.1-057 多模块产物归档与依赖裁剪要注意什么?

一句话结论

应用模块归档时只打包运行期必需依赖,库模块产物保持轻量;通过 configuration 区分 api/implementation,避免把内部工具库打进发布包。

概念解释

fat jar/bootJar 打包基于 runtime classpath 解析。implementation 依赖仍会进运行产物,但不会对外暴露编译;不需要随产物分发的库应放到 compileOnly 或由运行环境提供。

原理流程

  1. 明确模块是库还是应用。
  2. 按可见性声明依赖配置。
  3. 归档任务解析 runtime classpath 打包。
  4. 检查产物内容,剔除误打包的编译期/测试库。

代码或图示

tasks.jar {
    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
}
// 应用模块 fat jar 配置按所用打包插件为准

常见误区

  • 测试依赖漏配到 testImplementation:被打进运行产物。
  • 库模块把实现细节库标 api:下游被动接收一堆传递依赖。

追问

  • 如何查看打包内容?答:解压产物或运行依赖/归档分析任务,核对条目列表。
  • 多模块共享资源如何打包?答:资源随模块 jar 进入 classpath,不重复拷贝到应用产物。

04.8.3.1-058 模块分组与输出目录如何组织?

一句话结论

工程路径按领域分层(如 :order:api、:order:domain),构建输出默认落在各模块 build/ 下;归档产物通过发布任务或根聚合任务收集,不手工挪动 _site 之外的生成物。

概念解释

目录分组影响 include 路径与依赖可读性,不改变 Gradle 解析规则。输出目录由布局约定决定,自定义输出应通过任务输出属性声明,而不是脚本里硬编码拷贝路径。

原理流程

  1. 目录与工程路径按领域命名。
  2. 编译/打包任务写入模块 build 目录。
  3. 聚合任务读取各模块输出 Provider。
  4. 最终产物由发布或归档任务统一产出。

代码或图示

app/
order-api/
order-domain/
order-infra/

常见误区

  • 任务动作里写死输出绝对路径:机器迁移后失效,应用 layout.buildDirectory。
  • 手工清理模块 build 目录后不更新任务状态:下次构建按增量规则重算。

追问

  • 如何统一改输出根目录?答:通过 layout.buildDirectory 属性配置,不要在脚本拼字符串路径。
  • 聚合所有 jar 的任务怎么写?答:注册任务收集各模块 jar 输出 Provider,执行阶段拷贝或归档。

04.8.3.1-059 单模块构建与全量构建命令如何选择?

一句话结论

命令行指定模块路径与任务名可只构建该模块及其依赖;不带模块限定则执行全工程任务图。按需构建减少反馈时间,CI 全量构建保证整体一致。

概念解释

Gradle 按任务依赖决定是否需要先构建上游模块。单模块构建会自动编译其依赖的工程模块,跳过无关分支。全量构建在合并前或 CI 上运行,覆盖所有模块。

原理流程

  1. 命令行解析目标任务与模块路径。
  2. 构建任务图,纳入必要上游模块。
  3. 无关模块不进入执行图。
  4. CI 上执行根工程全量任务。

代码或图示

# 仅构建 app 模块及其上游(命令以项目脚本封装为准)
gradle :app:build

# 全量
gradle build

常见误区

  • 单模块通过测试后就提交:未跑全量集成与跨模块编译,合并前需补全量。
  • 认为跳过的模块没有风险:接口变更可能影响未构建的下游。

追问

  • 如何只跑某个模块测试?答::模块:test,上游依赖按图构建。
  • 并行构建如何开启?答:在配置中开启并行执行,任务独立时各模块并行编译。

04.8.3.1-060 复合构建与发布到本地 Maven 仓库联调相比优劣如何?

一句话结论

复合构建直接链接源码产物、免安装、改动联动;本地 Maven 仓库方式兼容只认坐标的消费方,但需要手动发布快照、易残留旧包。

概念解释

mavenLocal 依赖解析把本地仓库当普通仓库,发布动作独立于主构建;复合构建在一次会话内完成源码到产物的替换。消费方无法改造时(如外部工程只读坐标)才需要本地仓库发布。

原理流程

  1. 库工程发布快照到 mavenLocal。
  2. 主工程仓库列表包含 mavenLocal 并解析快照。
  3. 改动库需重新发布才生效。
  4. 复合构建则跳过发布步骤,直接消费工程输出。

代码或图示

方式 A:lib publishToMavenLocal → 主工程解析 mavenLocal
方式 B:includeBuild 源码产物 → 主工程直接替换坐标

常见误区

  • 本地仓库残留旧快照被优先解析:出现"改了没生效",需清理或调整仓库顺序。
  • 把 mavenLocal 放仓库列表首位污染 CI:CI 环境不应依赖开发者本地仓库。

追问

  • 快照版本刷新策略怎么配?答:按 Gradle 缓存规则控制快照过期,生产构建应锁定发布版本。
  • 两种方式能否并存?答:可切换,但同一构建内避免替换规则与本地快照互相干扰。

04.8.3.1-061 included build 的依赖可见性有什么限制?

一句话结论

被纳入构建有自己的依赖图与配置隔离,其实现依赖不自动暴露给主工程;主工程只消费纳入工程对外产物,跨构建共享平台或插件需显式声明。

概念解释

复合构建是多个独立 Gradle 运行单元的组合,各自解析依赖。纳入工程的 implementation 依赖不会传递到主工程编译 classpath。平台 BOM 等共享约束需在两边分别配置。

原理流程

  1. 纳入工程独立解析自身依赖。
  2. 产物作为构件回供主构建。
  3. 主工程按自己的依赖规则再解析。
  4. 两侧 classpath 不自动合并。

代码或图示

included lib:compile classpath ──▶ lib jar ──▶ 主工程 runtime/compile classpath
(lib 的传递依赖仍按其发布元数据参与主工程解析)

常见误区

  • 以为纳入工程加过的库主工程可直接 import:需主工程显式声明。
  • 在纳入工程与主工程放不同版本同一库:解析时按冲突规则裁决,可能出现不一致。

追问

  • 纳入工程的插件会应用到主工程吗?答:不会,主工程插件解析独立;插件联调需按插件复合构建方式纳入。
  • 如何核对跨构建依赖版本?答:分别查看两边依赖报告,确认对齐。

04.8.3.1-062 多模块版本对齐与依赖收敛怎么做?

一句话结论

用平台 BOM 约束成员版本,版本目录统一登记坐标,convention plugin 收口公共依赖;定期分析依赖树,移除重复与过时传递依赖。

概念解释

对齐目标是同一库在全工程只有一个解析版本。BOM 提供约束,目录提供声明,插件提供默认引入。依赖收敛还要排除不需要的传递依赖,缩小 classpath 体积与冲突面。

原理流程

  1. 目录登记公共库与 BOM 版本。
  2. plugin 给模块加平台依赖与公共库。
  3. 解析阶段按冲突规则选版本。
  4. 定期审查依赖树,排除冗余传递项。

代码或图示

dependencies {
    implementation(platform(libs.oss.bom))
    implementation(libs.bundles.common)
}

常见误区

  • 各模块显式写不同小版本:BOM 约束被绕过,对齐失效。
  • 只看直接依赖不看传递树:冲突常由传递依赖引入。

追问

  • 如何发现版本漂移?答:依赖分析任务列出各配置解析版本,对比是否超出 BOM 约束。
  • 排除传递依赖怎么写?答:在对应依赖上 exclude 模块坐标,记录排除原因。

04.8.3.1-063 configuration avoidance(配置避免)是什么?

一句话结论

配置避免是 Gradle 延迟创建与配置任务的策略:只有被执行需求选中的任务才实例化并执行配置块,减少配置阶段遍历全部任务的开销。

概念解释

传统 tasks.create 在配置阶段就构造所有任务并运行其配置块;工程模块一多,配置时间线性膨胀。register 只保存注册信息,任务图确定后按需实例化。配置避免是 Gradle 性能优化的基础原则之一。

原理流程

  1. 脚本与插件调用 register 登记任务类型与名称。
  2. 配置阶段不实例化未被选中任务。
  3. 任务图根据命令行与依赖关系确定目标任务集合。
  4. 仅目标集合内任务被实例化并执行配置块。

代码或图示

// 懒注册:配置阶段只登记
tasks.register("check") {
    // 仅任务实例化后执行
}

常见误区

  • 以为用了 register 就自动避免配置:块内若强制解析其他任务或读 Project 状态,仍会破坏懒加载。
  • 在配置阶段遍历 tasks 集合:触发全部任务实例化,配置避免失效。

追问

  • 配置避免与 configuration cache 关系?答:前者减少配置阶段工作,后者缓存整个配置结果供下次复用;两者互补。
  • 老插件不支持懒注册怎么办?答:升级到支持现代任务 API 的插件版本,或评估迁移成本。

04.8.3.1-064 tasks.register 与 tasks.create 的区别是什么?

一句话结论

register 返回 TaskProvider 并延迟实例化,符合配置避免;create 立即构造任务对象并执行配置,在配置阶段产生成本,新脚本应避免使用。

概念解释

create 在调用当下就把任务加入已实例化集合,配置块立即运行;register 只记录注册动作。需要任务对象引用时,优先用 Provider 在动作或依赖声明中传递,而不是立即 .get()。

原理流程

  1. register:保存类型、名称、配置 lambda。
  2. 任务被选中后实例化,配置 lambda 执行。
  3. create:调用即实例化并配置。
  4. 配置阶段任务数量越大,create 累积耗时越明显。

代码或图示

val report = tasks.register("report") { doLast { /* ... */ } }
tasks.named("build") { dependsOn(report) }

常见误区

  • 用 register 后立刻 .get() 取任务:退化为立即实例化。
  • 为了访问任务属性选 create:应用 named<T> 类型化 provider 延迟访问。

追问

  • 插件兼容旧 Gradle 时怎么办?答:现代 Gradle 版本均提供 register;遗留脚本逐步替换 create。
  • 如何检查脚本里是否还有 create?答:搜索构建脚本中的 tasks.create 调用并改造。

04.8.3.1-065 为什么要避免在配置阶段解析任务列表?

一句话结论

配置阶段列举全部任务会强制实例化它们并执行配置块,抵消配置避免策略;任务间关系应通过 Provider 与依赖声明懒连接。

概念解释

tasks.forEach、tasks.withType 立即遍历、tasks["name"] 立即取值都会触发实例化。配置阶段目标是组装任务图,不是运行任务。读任务列表常用于批量配置,应改为 configureEach 懒规则。

原理流程

  1. 命令行确定目标任务。
  2. 懒规则按类型/名称登记待配置条件。
  3. 实例化发生在任务图确定后。
  4. 立即遍历会把未选中任务也拉入配置阶段。

代码或图示

// 不推荐:立即遍历
tasks.filterIsInstance<KotlinCompile>().forEach { it.compilerOptions { ... } }

// 推荐:懒规则
tasks.withType<KotlinCompile>().configureEach { compilerOptions { ... } }

常见误区

  • 在配置块里打印全部任务名调试:调试完应移除,避免污染生产构建脚本。
  • 用任务名前缀在配置阶段做匹配后立即取值:保持 provider 链即可。

追问

  • 必须知道全部任务名才能注册依赖怎么办?答:用类型匹配或约定命名规则懒连接,不提前列举。
  • 配置阶段读任务输出文件内容:应改为任务输入通过 Provider 传递。

04.8.3.1-066 afterEvaluate 的危害与替代方式是什么?

一句话结论

afterEvaluate 把配置推迟到工程评估之后执行,容易造成顺序脆弱、破坏配置避免;替代方案是用懒属性、Provider 绑定与 convention plugin 声明式配置。

概念解释

afterEvaluate 注册的动作在本工程脚本配置完后运行,常被用来等待其他脚本设置好属性。它让配置顺序成为隐式依赖,插件复用困难,也阻止部分懒优化。现代 Gradle 鼓励在 apply/register 时用 Provider 连接值来源。

原理流程

  1. 脚本正常配置阶段执行。
  2. afterEvaluate 动作排入队列。
  3. 工程评估完成后批量执行队列。
  4. 此时再读任务/属性可能已绕过懒解析。

代码或图示

// 脆弱写法
afterEvaluate {
    tasks.named("compileKotlin") { /* 依赖其他脚本先设置的值 */ }
}

// 替代:Provider 派生
val flag = providers.gradleProperty("feature").orElse("default")

常见误区

  • 插件内普遍使用 afterEvaluate 读工程配置:应设计 extension 让值在声明期绑定。
  • 多段 afterEvaluate 互相依赖:执行顺序难追踪,问题随模块增多放大。

追问

  • 遗留脚本暂时离不开 afterEvaluate 怎么办?答:先缩小使用范围,逐步把取值改为 Provider 链,再移除回调。
  • afterEvaluate 在多工程中何时触发?答:每个工程评估完成后分别触发,跨工程顺序仍不可靠。

04.8.3.1-067 为什么缓存生效要求任务逻辑不读取 Project 状态?

一句话结论

构建缓存与增量判定基于声明的输入快照;任务动作读取未声明的 Project 属性、环境变量或文件会让缓存键失真,导致命中缓存却得到错误结果。

概念解释

可缓存任务必须把影响输出的所有因素声明为输入。动作内部直接读 project.version、系统属性、未列入输入的目录,Gradle 无法感知这些变量,缓存复用时仍按旧输入判定命中。

原理流程

  1. 任务输入属性声明为 @Input/@InputFiles 等。
  2. 执行前快照输入哈希计算缓存键。
  3. 命中缓存则下载历史输出,跳过动作。
  4. 未声明的读取项变化不会进键,造成错误复用。

代码或图示

abstract class GenTask : DefaultTask() {
    @get:Input
    abstract val version: Property<String>

    @TaskAction
    fun gen() {
        // 只读取已注入的 version,不在动作内访问 project 其他状态
    }
}

常见误区

  • 任务动作里 project.file(...) 读未声明目录:输入遗漏,缓存不可靠。
  • 在动作内读环境变量却不声明为输入:CI 与本地环境差异导致缓存命中错误。

追问

  • 任务必须读项目元数据怎么办?答:在配置期把需要的值提取到 Property 并声明为输入。
  • 如何验证任务可缓存?答:连续两次构建对比任务状态,第二次应 FROM_CACHE 或 UP_TO_DATE;改动输入后应重跑。

04.8.3.1-068 任务依赖声明 finalizedBy/dependsOn 如何保持懒解析?

一句话结论

dependsOn 与 finalizedBy 可接受 TaskProvider,依赖关系在任务图阶段解析,不强制立即实例化被依赖任务。

概念解释

把任务名字符串传给 dependsOn 也可工作,但 provider 形式保留懒链接:被依赖任务未被选中时不必提前创建。finalizedBy 表示无论主任务成功失败都执行收尾任务。

原理流程

  1. 注册主任务与收尾任务,各持 Provider。
  2. 主任务声明 finalizedBy(provider)。
  3. 任务图解析时建立节点边。
  4. 执行阶段按拓扑顺序运行。

代码或图示

val cleanReport = tasks.register("cleanReport") { doLast { /* ... */ } }
tasks.register("report") {
    finalizedBy(cleanReport)
    doLast { /* ... */ }
}

常见误区

  • 依赖声明时 .get() 任务:提前实例化,破坏懒解析。
  • 把收尾任务挂到错误生命周期:finalizedBy 始终执行,应区分 mustRunAfter 顺序约束。

追问

  • mustRunAfter 与 dependsOn 区别?答:前者只约束顺序,不强制纳入执行;后者建立必选依赖边。
  • 任务依赖按条件动态添加怎么办?答:在配置块内根据 extension 值选择 provider 声明,保持懒链接。

04.8.3.1-069 配置阶段执行 println 会带来什么问题?

一句话结论

配置阶段的打印语句在每次构建(即使目标任务无关)都会执行,拖慢配置并污染输出;诊断打印应放进任务动作或临时排查后移除。

概念解释

配置阶段遍历脚本与插件,块内顶层代码先于任务动作运行。循环打印、IO 操作都会计入配置耗时。任务动作内的打印只在任务被执行时输出。

原理流程

  1. 脚本配置阶段执行顶层语句。
  2. 顶层 println 立即输出。
  3. 任务图确定后才执行动作块。
  4. 无关目标任务不会触发动作打印。

代码或图示

// 配置阶段每次都打印(不推荐)
println("configuring app module")

tasks.register("run") {
    doLast { println("executing run") } // 仅执行时打印
}

常见误区

  • 用顶层打印判断任务是否配置:应观察任务状态而非配置日志。
  • 在配置块里做网络/文件 IO:同属配置阶段重活,应移入任务动作。

追问

  • 如何统计配置阶段耗时?答:用构建 profile 报告查看脚本与插件配置时间分布。
  • 插件里的诊断日志怎么放?答:通过 logger 在动作阶段输出,避免配置期噪音。

04.8.3.1-070 任务输入输出注解如何参与增量与缓存判定?

一句话结论

@Input、@InputFile/@InputFiles、@OutputDirectory/@OutputFile 等注解声明任务影响输出的因素;Gradle 据此快照输入、对比历史输出,判定 UP_TO_DATE、FROM_CACHE 或需要重跑。

概念解释

未标注的属性不进输入快照,动作读取它就属于隐式输入。输出注解让 Gradle 管理产物目录、判断产物是否存在。属性类型应优先用 Property<T>、DirectoryProperty 等懒类型,配合注解使用。

原理流程

  1. 任务类属性标注输入/输出注解。
  2. 执行前快照输入值与文件哈希。
  3. 与上次运行记录对比:一致且输出存在则 UP_TO_DATE。
  4. 开启缓存时按输入哈希查远程/本地缓存命中历史输出。

代码或图示

abstract class CopyDocs : DefaultTask() {
    @get:InputDirectory
    abstract val source: DirectoryProperty
    @get:OutputDirectory
    abstract val target: DirectoryProperty

    @TaskAction
    fun copy() { /* 拷贝逻辑 */ }
}

常见误区

  • 输出目录里混入未由任务生成的文件:Gradle 清理与缓存判定可能误删或误判。
  • 把常量字符串标成 @Input 之外的字段:不影响缓存,但阅读时易误解其角色。

追问

  • 如何声明输入是否参与顺序无关比较?答:文件集合可用相应注解控制顺序敏感与否,具体注解以 Gradle 当前文档为准。
  • 任务读取系统属性怎么办?答:声明为输入属性(如 @Input 的 Property),不要在动作内直接读系统环境。

04.8.3.1-071 Gradle 增量构建如何判定任务是否需要重跑?

一句话结论

增量构建对比任务上次执行记录与当前输入输出:输入未变、产物存在且有效则跳过;任一输入变化、产物缺失或被清理则重跑。

概念解释

每次执行后 Gradle 记录输入哈希、输出清单与执行元数据。下次构建先做快照对比,未变化任务标记 UP_TO_DATE。文件内容哈希比时间戳更可靠,避免触碰时间造成误重跑。

原理流程

  1. 任务图确定后逐个检查可增量任务。
  2. 快照当前输入值与文件哈希。
  3. 与历史记录对比并检查产物完整性。
  4. 未变化跳过,变化则执行动作并更新记录。

代码或图示

任务执行记录:输入哈希 + 输出文件清单 + 执行元数据
下次构建:当前快照 ──对比──▶ 一致 → UP_TO_DATE;不一致 → 执行

常见误区

  • 改动注释就全量重编:注释变化同样改变源码哈希,属预期;Kotlin 增量编译可在类粒度缩小影响面。
  • 手工改 build 目录产物:记录与产物不一致,下次可能重跑或报错。

追问

  • 增量记录存哪里?答:Gradle 在构建目录维护任务历史记录,清理 build 目录后首次全量重跑。
  • 如何强制重跑某任务?答:可强制刷新该任务(命令参数以当前 Gradle 版本为准),或清理对应输出。

04.8.3.1-072 本地构建缓存与远程构建缓存有什么区别?

一句话结论

本地缓存只在本机 Gradle 缓存目录复用历史任务输出;远程缓存是团队共享的服务端缓存,不同机器、不同流水线之间可互相复用任务产物。

概念解释

两类缓存键计算规则相同,区别在存储位置与共享范围。本地缓存加速重复构建与切换分支;远程缓存让 CI 构建产物被开发机命中,或流水线之间复用。缓存条目按输入哈希寻址。

原理流程

  1. 任务可缓存且输入哈希计算完成。
  2. 先查本地缓存,未命中再查远程缓存。
  3. 命中则下载/复用历史输出,跳过动作。
  4. 未命中执行任务,产物写入本地并上传远程(按配置)。

代码或图示

// 目录或 gradle.properties 中开启缓存(具体属性名以当前 Gradle 文档为准)
// org.gradle.caching=true

常见误区

  • 以为开启缓存就一定复用:任务必须声明输入输出且无隐式状态,才具备可缓存性。
  • 远程缓存长期不清理:旧条目占用空间,需按策略过期清理。

追问

  • 远程缓存服务怎么部署?答:使用兼容 Gradle 缓存协议的 HTTP 服务端;团队内选型与部署以基础设施方案为准。
  • 缓存条目包含源码吗?答:缓存的是任务输出产物与元数据,不直接缓存源码;输入哈希引用源文件内容。

04.8.3.1-073 构建缓存键由什么构成?

一句话结论

缓存键由任务类自身、输入属性值与文件哈希、构建环境属性(如 Gradle 版本、操作系统、JVM 版本相关声明)等共同哈希生成;输出不参与键计算。

概念解释

相同输入在不同环境若产出不同结果,环境差异必须进入键,否则跨环境复用会出错。Gradle 对部分内置环境维度自动纳入;自定义任务需把影响结果的配置显式声明。

原理流程

  1. 收集任务类型与实现类哈希。
  2. 快照所有标注输入的属性与文件。
  3. 合并已声明的环境维度。
  4. 计算哈希作为缓存键查找条目。

代码或图示

缓存键 = hash(任务实现类, 输入属性, 输入文件哈希, 环境维度)

常见误区

  • 任务依赖未声明的 JDK 版本:跨 JDK 复用缓存可能产出不兼容字节码。
  • 生成代码包含绝对路径:环境差异被写进产物,导致缓存命中率下降甚至错误复用。

追问

  • 如何让任务忽略某些环境差异?答:只在产物确实不受影响时排除对应维度,需谨慎验证。
  • 缓存键冲突如何排查?答:对比两次构建的任务输入快照,找出未声明的差异项。

04.8.3.1-074 Kotlin 增量编译机制是怎样的?

一句话结论

Kotlin 编译在 KGP 配合下做类粒度的增量分析:比较上次编译的类快照与当前源码,只重编受影响的类及其依赖,而非整模块全量编译。

概念解释

编译器记录类之间的依赖关系(源码类、元数据)。修改一个类后,分析哪些类的公共/内部 API 受影响,缩小重编集合。增量效果受改动类型影响:修改 public 签名影响面大于修改方法体。

原理流程

  1. 上次编译生成类快照与依赖信息。
  2. 本次扫描变更源码文件。
  3. 分析受影响类集合(直接变更 + 依赖传递)。
  4. 只编译集合内类,合并进输出。

代码或图示

修改 A.kt 方法体 → 仅 A 及其直接依赖重编
修改 A.kt public 签名 → 引用 A 的类一并纳入重编

常见误区

  • 以为改一行永远只编一个文件:签名变更会沿引用链扩散。
  • 关闭增量编译后误判性能:编译参数与配置会影响增量是否启用。

追问

  • 增量编译与 Gradle 任务增量是一回事吗?答:前者是 Kotlin 编译器内部类粒度分析,后者是 Gradle 任务级 UP_TO_DATE 判定,两层配合。
  • 增量状态损坏怎么办?答:清理模块 build 目录后全量重建一次。

04.8.3.1-075 为什么改一行源码有时触发全量重编译?

一句话结论

当改动触及 public 签名、注解、序列化/生成代码元数据,或增量快照失效、类被广泛引用时,受影响集合扩大到近乎全模块;K2 编译器下增量行为也可能随版本调整(待确认具体边界)。

概念解释

方法体内部改动影响面小;改函数签名、类层次、属性可见性会让所有引用方的类型检查失效。此外增量数据缺失、构建脚本/插件变更、classpath 大改也会使编译器退化为全量。

原理流程

  1. 识别变更文件与变更类型。
  2. 沿依赖图扩散受影响类。
  3. 扩散范围超过阈值或快照不可用时全量编译。
  4. 输出新快照供下次增量使用。

代码或图示

方法体改动:小范围重编
签名/父类/注解改动:引用链扩散 → 大范围重编
快照缺失或 classpath 变更:全量编译

常见误区

  • 把全量重编归咎于机器性能:先分析改动类型与增量状态。
  • 频繁切换分支清空 build 目录:丢失增量快照,下次冷构建全量。

追问

  • 如何查看本次编译是增量还是全量?答:观察编译任务日志与 KGP 报告(具体输出以版本为准)。
  • K2 下增量有何变化?答:K2 重写前端,增量策略随版本演进;行为细节标待确认,以 Kotlin 发布说明为准。

04.8.3.1-076 构建缓存命中后任务如何被跳过?

一句话结论

缓存命中时 Gradle 直接把历史输出产物恢复到任务声明的输出位置,跳过任务动作执行,任务状态标记为 FROM_CACHE。

概念解释

缓存条目保存上次成功执行的输出文件集合。命中后 Gradle 按输出声明还原文件,无需重新编译/生成。前提是任务可缓存、输入哈希一致、输出位置可被覆盖还原。

原理流程

  1. 计算缓存键并查询本地/远程缓存。
  2. 命中条目后校验产物清单。
  3. 还原输出文件到任务输出目录。
  4. 动作不执行,下游任务按新输出继续。

代码或图示

缓存查询命中 → 还原产物 → 任务状态 FROM_CACHE → 下游消费输出

常见误区

  • 缓存命中但产物含本机绝对路径:还原后路径不一致,需在生成阶段规避绝对路径。
  • 任务有副作用(写外部服务)却标可缓存:命中后副作用被跳过,外部状态与产物不一致。

追问

  • 可缓存任务如何显式开关?答:任务配置 cacheIf/outputs.cacheIf 声明命中条件,具体 API 以版本为准。
  • 下游任务缓存是否独立命中?答:下游按自身输入快照判定,上游产物哈希是其输入的一部分。

04.8.3.1-077 远程缓存在 CI 上的价值是什么?

一句话结论

远程缓存让流水线各次运行、各模块之间复用历史任务产物,减少重复编译与生成工作;开发机也可拉取 CI 已构建产物,缩短冷构建时间。

概念解释

CI 环境每次通常是干净工作区,本地增量快照不可用;远程缓存跨机器共享输出,命中后跳过编译。收益最大的是编译、打包、代码生成等耗时任务。命中率依赖输入稳定与缓存键可复现。

原理流程

  1. CI 构建任务执行前查远程缓存。
  2. 未命中则执行并上传产物条目。
  3. 后续流水线或开发机按同一输入命中。
  4. 缓存按策略过期清理。

代码或图示

CI run A 编译产物上传 remote cache
CI run B / 开发机 同输入命中 → 跳过编译

常见误区

  • CI 上任务仍读取机器特定路径/端口:缓存键不稳定,命中率低。
  • 把含环境密钥的产物上传远程缓存:安全风险,敏感内容不得进缓存条目。

追问

  • 并行流水线共享缓存会互相污染吗?答:缓存按只读复用 + 新条目写入,产物不可变;并发写入同键内容应一致。
  • 缓存命中率如何度量?答:查看构建扫描中任务 FROM_CACHE 比例,定位未命中任务类型。

04.8.3.1-078 如何让自定义任务具备可缓存性?

一句话结论

完整声明输入输出注解、动作内只读输入并只写输出目录、不访问未声明环境状态,并通过缓存条件允许命中复用;之后两次相同输入构建应命中缓存。

概念解释

可缓存性是任务设计属性,不是开关一打的结果。隐式输入、外部副作用、输出目录混入杂项都会破坏缓存。任务类型抽象属性化后更易满足条件。

原理流程

  1. 定义任务类,属性用 Property/DirectoryProperty。
  2. 标注全部输入与输出。
  3. 动作只消费输入、生成输出。
  4. 配置缓存条件并实测命中。

代码或图示

abstract class GenConfig : DefaultTask() {
    @get:Input
    abstract val env: Property<String>
    @get:OutputFile
    abstract val output: RegularFileProperty

    @TaskAction
    fun generate() { /* 依据 env 写 output */ }
}

常见误区

  • 任务动作里调用外部命令且命令版本未声明:环境差异不进键。
  • 多个任务写同一输出目录:产物归属混乱,缓存还原互相覆盖。

追问

  • 任务需要读源码目录又读资源目录怎么标?答:分别声明输入文件集合,均可参与哈希。
  • 缓存条目何时失效?答:输入哈希变化即产生新键;旧条目靠缓存清理策略回收。

04.8.3.1-079 缓存未命中常见原因有哪些?

一句话结论

常见原因包括输入未声明导致哈希不稳定、产物含绝对路径或时间戳、环境维度差异、任务有外部副作用、Gradle/插件版本变化,以及本地缓存被清理。

概念解释

未命中表现为任务每次重跑且状态非 FROM_CACHE。排查顺序:先看任务是否可缓存,再核对输入声明是否完整,最后检查环境与产物内容。构建扫描可对比两次运行的输入差异。

原理流程

  1. 确认任务类型支持缓存且未被禁用。
  2. 对比两次构建输入快照差异。
  3. 检查产物是否写入路径、时间戳、机器名。
  4. 核对 Gradle、JDK、插件版本是否变化。

代码或图示

未命中排查:可缓存性 → 输入完整性 → 产物杂质 → 环境维度 → 版本变化

常见误区

  • 把未命中当作缓存服务故障:多数情况是任务输入设计问题,先查任务本身。
  • 反复清理缓存目录试图解决:治标不治本,输入不稳定依旧未命中。

追问

  • 产物里的时间戳如何去掉?答:生成阶段固定可复现输出,避免写入构建时刻。
  • 如何对比两次输入?答:用构建扫描或任务输入报告定位差异属性。

04.8.3.1-080 clean 与构建缓存是什么关系?

一句话结论

clean 删除模块 build 目录下的任务输出,但不删除 Gradle 缓存记录;下次构建若无缓存命中会重新生成,命中缓存则从本地/远程还原产物。

概念解释

clean 清的是工作区产物,缓存记录存于 Gradle 缓存目录。删除输出后任务历史记录可能仍在,但产物缺失;增量判定结合缓存,可从缓存还原。两者存储位置与作用不同。

原理流程

  1. clean 删除 build 目录产物。
  2. 任务历史记录与缓存条目保留。
  3. 下次构建输入对比,产物缺失但缓存命中则还原。
  4. 未命中则重新执行动作。

代码或图示

clean:移除 build/ 输出
缓存:保留历史输入哈希与产物条目

常见误区

  • 以为 clean 后必然全量重跑:缓存可还原输出,是否重跑取决于命中。
  • 手动删 build 目录代替 clean:历史记录残留可能造成状态不一致,建议用 clean 任务。

追问

  • 如何彻底清空本地缓存?答:停止 daemon 后清理 Gradle 缓存目录;清理后首次构建全量。
  • CI 每次 clean 是否还需要缓存?答:需要,clean 清工作区,缓存跨运行复用产物。

04.8.3.1-081 jvmTarget 如何选择?

一句话结论

jvmTarget 决定 Kotlin 编译产出的字节码版本,应与运行时 JVM 版本对齐;选择低于或等于生产 JDK 版本,过高会在旧运行时上抛版本错误。

概念解释

Kotlin 编译器把源码编译为指定 class 版本。jvmTarget 与 toolchain/编译 JDK 不必相同:用高版本 JDK 编译可输出低版本字节码。后端服务通常按部署运行时选择 LTS 版本。

原理流程

  1. 确认生产运行 JVM 版本。
  2. 在 Kotlin 编译选项设置对应 jvmTarget。
  3. 编译器按目标版本生成 class。
  4. 运行时加载校验 class 版本兼容。

代码或图示

kotlin {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
    }
}

常见误区

  • jvmTarget 设为最新版却部署在旧 JRE:类版本异常,启动失败。
  • 模块间 jvmTarget 不一致:高版本字节码被低版本模块引用时出兼容问题。

追问

  • jvmTarget 与 sourceCompatibility 关系?答:二者应保持一致或按 JVM 规范对齐;Kotlin 模块以 Kotlin 选项为准,Java 编译任务另设。
  • 如何查看输出字节码版本?答:检查 class 文件主版本号或反编译工具确认目标版本。

04.8.3.1-082 freeCompilerArgs 常用参数有哪些?

一句话结论

freeCompilerArgs 透传给 Kotlin 编译器的自由参数,常见包括 opt-in 声明、JSR305 严格性、默认方法兼容等;具体可用参数随 Kotlin 版本变化,不确定的参数标待确认并在编译器输出中核对。

概念解释

DSL 未专门暴露的编译器开关通过 freeCompilerArgs 传入。参数写错时编译器报未识别选项。团队公共参数应在 convention plugin 统一配置,避免模块各写一份。

原理流程

  1. 在编译任务 compilerOptions 中追加参数。
  2. KGP 把参数传给编译器进程。
  3. 编译器按参数开启实验特性或调整行为。
  4. 不兼容参数在编译期报错。

代码或图示

compilerOptions {
    freeCompilerArgs.addAll(
        "-opt-in=kotlin.RequiresOptIn",
        "-Xjsr305=strict"
    )
}

常见误区

  • 把实验性 -X 参数当稳定接口长期依赖:版本升级可能移除或改名。
  • 同一参数重复添加:以编译器实际处理为准,建议去重后统一配置。

追问

  • 如何查看当前版本支持的编译器参数?答:运行编译器帮助输出或查 Kotlin 官方文档;-X 开头参数标注为实验性。
  • opt-in 与 freeCompilerArgs 中 opt-in 的区别?答:也可在注解/文件级别声明;全局开关通过编译参数统一开启。

04.8.3.1-083 kotlin-stdlib 版本与编译器版本是什么关系?

一句话结论

标准库版本应与 Kotlin 编译器(KGP 插件)版本对齐或兼容:编译器生成的字节码依赖同版本 stdlib API,错位可能出现链接错误或新 API 找不到。

概念解释

编译器与标准库同仓发布,API 与实现配套。KGP 版本即编译器版本;stdlib 作为依赖引入。升级 Kotlin 时插件与 stdlib 版本应一起对齐,第三方库兼容范围以其说明为准。

原理流程

  1. 目录登记 Kotlin 版本段。
  2. 插件与 stdlib 条目引用同一版本。
  3. 编译使用该版本编译器,运行 classpath 含同版本 stdlib。
  4. 版本错位时检查编译与运行期 API 匹配。

代码或图示

[versions]
kotlin = "2.0.20"

[libraries]
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

常见误区

  • 只升级插件不动 stdlib:编译期通过、运行期缺类或行为不一致。
  • 强制压低 stdlib 版本迁就老库:先确认兼容范围,冲突时升级老库。

追问

  • stdlib 能否不显式声明?答:以当前 KGP 默认行为为准;显式声明版本更可控。
  • 多平台 stdlib 有何差异?答:JVM 用 kotlin-stdlib,其他平台有对应变体;按目标平台声明。

04.8.3.1-084 languageVersion 与 apiVersion 有什么区别?

一句话结论

languageVersion 控制允许使用的语法版本,apiVersion 控制生成代码对标准库 API 的兼容版本;前者约束源码写法,后者约束产出可兼容的库 API 范围。

概念解释

languageVersion 低则新语法不可用,便于老代码逐步迁移。apiVersion 影响生成字节码引用的 stdlib API 级别,发布库时保证消费方 stdlib 版本兼容。两者通常配合设置。

原理流程

  1. 编译参数设置语言版本与 API 版本。
  2. 解析源码时按 languageVersion 检查语法。
  3. 生成代码按 apiVersion 选择可用 API 调用。
  4. 版本过低时新特性/新 API 报编译错误。

代码或图示

compilerOptions {
    languageVersion.set(org.jetbrains.kotlin.config.LanguageVersion.KOTLIN_2_0)
    apiVersion.set(org.jetbrains.kotlin.config.ApiVersion.KOTLIN_2_0)
}

常见误区

  • 把二者混为一个版本号:约束对象不同,发布库场景要分别评估消费方兼容。
  • 升级编译器却锁死旧 languageVersion:新语法不可用,迁移收益受限。

追问

  • 服务端应用需要设 apiVersion 吗?答:应用直接部署,按运行 stdlib 即可;库模块才需重点考虑 apiVersion 兼容。
  • 版本枚举随编译器更新吗?答:新 Kotlin 版本增加对应枚举值,以当前编译器文档为准。

04.8.3.1-085 toolchain 与 jdkHome 如何配置?

一句话结论

Java toolchain 声明编译与运行使用的 JDK 版本,Gradle 自动定位或下载对应 JDK;jdkHome 是旧方式手动指定 JDK 路径,现代配置优先用 toolchain。

概念解释

toolchain 把 JDK 版本作为构建输入,不同模块可用不同 JDK 版本编译,守护进程 JVM 与编译 JDK 分离。jdkHome 直接指向本机安装目录,不可移植,团队协作易不一致。

原理流程

  1. 在 java extension 声明 toolchain 版本。
  2. Gradle 检测本机匹配 JDK 或按配置下载。
  3. 编译任务使用该 JDK 工具链。
  4. 运行/测试任务按同一工具链执行。

代码或图示

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

常见误区

  • 依赖本机默认 JAVA_HOME:团队机器版本不一致,构建结果不可复现。
  • toolchain 版本与 jvmTarget 不匹配:按 JVM 规范确认二者兼容范围。

追问

  • toolchain JDK 自动下载放哪里?答:Gradle 管理的 JDK 缓存目录,具体位置以当前文档为准。
  • 多模块混用 JDK 17 与 21 可行吗?答:可为不同工程配不同 toolchain,但模块间字节码兼容需核对。

04.8.3.1-086 allWarningsAsErrors 有什么影响?

一句话结论

开启后编译器警告视为错误,编译失败;适合质量门禁严格的工程,但要平衡新升级工具链带来的新增警告,避免构建被存量警告阻断。

概念解释

Kotlin 编译参数把警告级别提升为错误。开启后未使用参数、过时 API、隐式签名等警告都会中断编译。团队可选择全量开启,或在门禁中单独统计警告数。

原理流程

  1. 编译选项设置警告升级错误。
  2. 编译器产生的每条警告按错误处理。
  3. 存在警告即编译任务失败。
  4. 修复或显式抑制后才能通过。

代码或图示

compilerOptions {
    allWarningsAsErrors.set(true)
}

常见误区

  • 升级 Kotlin 后新增警告导致全量阻断:先梳理存量警告再开启门禁。
  • 用抑制注解掩盖真问题:抑制需写明原因并评审。

追问

  • 只对部分警告报错可行吗?答:按编译器支持的警告级别配置,细粒度规则以版本文档为准。
  • 测试代码也要开启吗?答:可按 sourceSet 分别配置,测试代码警告可适当放宽。

04.8.3.1-087 反射与序列化场景需要哪些编译器参数或插件?

一句话结论

kotlinx-serialization 由编译器插件在编译期生成序列化器,无需反射;反射式框架才依赖运行期反射能力。编译器参数层面注意保留元数据与 -opt-in 声明,具体插件按官方文档接入。

概念解释

序列化插件为 @Serializable 类生成 serializer() 实现,避免运行期扫描字段。反射框架读取类元数据时,需确保编译未剥离元数据;Kotlin 默认保留必要元数据,混淆/裁剪场景另需配置。

原理流程

  1. 应用序列化编译器插件。
  2. 编译期为标注类生成序列化代码。
  3. 运行期直接调用生成器,不反射字段。
  4. 反射框架则在运行期读取类结构。

代码或图示

@Serializable
data class User(val id: Long, val name: String)

常见误区

  • 以为序列化靠反射:kotlinx-serialization 是编译期生成,行为与 Jackson 反射式不同。
  • 压缩/混淆后反射框架失效:需保留对应类元数据,按框架规则配置。

追问

  • 序列化插件版本与 Kotlin 版本绑定吗?答:插件随 Kotlin 发布,版本需对齐兼容矩阵。
  • 反射读取私有成员有何限制?答:JVM 反射可突破访问检查,但模块化 JDK 下受封装限制。

04.8.3.1-088 多模块 jvmTarget 不一致会有什么问题?

一句话结论

高版本字节码被低版本目标模块或运行时引用会抛类版本错误;多模块应统一 jvmTarget 与 toolchain,在 convention plugin 中收口。

概念解释

字节码版本沿依赖链传递:上游 class 版本高于下游运行 JVM 即不兼容。模块单独编译通过不代表链接运行正常。统一目标版本可避免部署时才暴露问题。

原理流程

  1. 各模块编译产出对应版本 class。
  2. 下游 classpath 引用上游产物。
  3. JVM 加载时校验 class 主版本。
  4. 版本高于运行时支持则启动/加载失败。

代码或图示

模块 A 编译目标 21,模块 B 运行于 JVM 17
→ 加载 A 的 class 报 UnsupportedClassVersionError

常见误区

  • 只在应用模块设目标版本:库模块按默认目标编译,仍可能版本偏高。
  • 本地 JDK 新、部署 JDK 旧未核对:部署环境才暴露版本错误。

追问

  • 如何统一检查各模块目标版本?答:在 plugin 中集中设置,或扫描编译任务配置核对。
  • 混合 JDK 版本编译的取舍?答:优先全工程统一 LTS 版本,确需差异时隔离模块边界。

04.8.3.1-089 Gradle daemon 是如何工作的?

一句话结论

daemon 是后台常驻的 JVM 进程,跨多次构建复用 Gradle 与类加载状态,避免每次启动 JVM、加载 Gradle 类与预热虚拟机;构建结束后进程保留待命。

概念解释

普通命令行会在单次构建后退出;daemon 模式下 Gradle 客户端与常驻进程通信,后续构建复用进程内存与缓存。配置变更、JVM 参数变化会触发新 daemon。

原理流程

  1. 首次启动 fork 一个 JVM daemon。
  2. 客户端把构建请求发给 daemon。
  3. daemon 在进程内完成配置与执行。
  4. 空闲等待下次调用,超过闲置期回收。

代码或图示

客户端 CLI ──▶ 常驻 daemon JVM(复用 classpath、JIT、缓存)

常见误区

  • 以为 daemon 保留的是任务执行状态:复用的是进程与类加载,任务结果仍按增量/缓存判定。
  • daemon 异常后仍复用旧进程:状态可疑时可停止 daemon 后重新构建。

追问

  • 如何查看运行中的 daemon?答:用 daemon 状态命令查看进程与闲置时间(命令名以当前版本为准)。
  • 什么情况会新开 daemon?答:JVM 参数、Gradle 版本、配置目录不匹配时按规则启动新进程。

04.8.3.1-090 daemon JVM 内存如何调优?

一句话结论

通过 org.gradle.jvmargs 设置 daemon 堆内存与 GC 参数;大工程堆不足会频繁 GC 甚至 OOM,堆过大则增加回收停顿,应按工程规模实测调整。

概念解释

daemon 堆容纳 Gradle 模型、任务类与构建缓存元数据。多模块大工程默认堆可能不够。调优依据是 GC 日志与构建 profile,而非盲目加大。编译任务的 JVM 内存另由 Kotlin 编译守护进程控制。

原理流程

  1. 查看构建耗时与 GC 占用。
  2. 调整 jvmargs 堆大小与 GC 参数。
  3. 重启 daemon 使参数生效。
  4. 对比多次构建配置与执行耗时。

代码或图示

# gradle.properties
org.gradle.jvmargs=-Xmx2g -XX:+UseG1GC

常见误区

  • 堆开到机器物理上限:其他进程与编译守护进程争抢内存,整体反而变慢。
  • 调大后不重启 daemon:旧进程沿用旧参数,调优不生效。

追问

  • 如何判断是堆不足还是任务本身慢?答:profile 报告区分配置、执行与 GC 时间;GC 占比高再调堆。
  • 并行构建内存如何估算?答:并行任务数 × 单任务内存 + daemon 基础堆,预留余量。

04.8.3.1-091 Kotlin 编译守护进程与 Gradle daemon 有何区别?

一句话结论

Gradle daemon 承载构建脚本与任务执行;Kotlin 编译守护进程是 KGP 为编译任务拉起的独立 JVM,常驻复用编译器实例,二者是不同进程、各自调优。

概念解释

Kotlin 编译器在独立进程中运行以隔离编译崩溃、复用编译器类加载。编译守护进程有自己的内存参数与闲置策略。编译慢或 OOM 时需分别检查两个进程的内存配置。

原理流程

  1. Gradle daemon 调度编译任务。
  2. KGP 向 Kotlin 编译守护进程提交编译请求。
  3. 守护进程复用编译器实例处理增量编译。
  4. 空闲后按策略回收。

代码或图示

Gradle daemon(构建编排)──任务调度──▶ Kotlin daemon(编译器实例)

常见误区

  • 只调 Gradle daemon 堆就期望编译变快:编译内存由 Kotlin 守护进程参数控制。
  • 编译 OOM 归因为构建脚本:先查编译进程堆设置。

追问

  • 编译守护进程参数在哪配?答:通过 KGP 提供的编译选项或 Gradle 属性配置(具体属性名以当前 KGP 文档为准)。
  • 能否关闭编译守护进程?答:可按配置禁用常驻,但每次编译重启编译器,冷构建更慢。

04.8.3.1-092 为什么 CI 上常使用 --no-daemon?

一句话结论

CI 工作区通常单次任务后即销毁,daemon 复用价值低;关闭 daemon 避免常驻进程占用资源与跨构建状态残留,保证每次构建环境干净。

概念解释

本地开发反复构建,daemon 复用收益明显;CI 每次流水线是干净环境,进程保留到闲置回收反而占用内存。无 daemon 模式单次启动 JVM 成本由 CI 并行度与缓存收益抵消。

原理流程

  1. CI 脚本以无 daemon 模式调用 Gradle。
  2. 单次构建 JVM 启动后完成配置与执行。
  3. 构建结束进程退出,不保留状态。
  4. 下次流水线重新启动,配合远程缓存复用产物。

代码或图示

CI:gradle build --no-daemon(脚本封装参数以项目约定为准)
本地:默认 daemon 复用

常见误区

  • 把本地调优的 daemon 内存参数照搬到 CI:无 daemon 模式下参数作用对象不同。
  • CI 残留 daemon 占满执行机内存:按平台策略回收或显式关闭。

追问

  • CI 无 daemon 会损失增量编译吗?答:进程内复用丢失,但任务级增量与远程缓存仍生效。
  • 哪些 CI 场景可保留 daemon?答:同一执行机连续多次构建且资源充足时可评估,以流水线性能实测为准。

04.8.3.1-093 daemon 闲置回收机制是怎样的?

一句话结论

daemon 空闲超过设定时间后自动退出,释放内存;闲置超时与 JVM 退出行为由 Gradle 配置控制,参数名与默认值以当前版本文档为准。

概念解释

常驻进程需要回收策略避免长期占用。闲置期间不接构建请求,超时后 JVM 退出。下次需要时重新启动。机器重启或手动停止也会终止 daemon。

原理流程

  1. 一次构建结束后 daemon 进入待命。
  2. 计时器累计闲置时间。
  3. 超过阈值触发退出。
  4. 新构建请求时按需拉起。

代码或图示

构建完成 → 闲置计时 → 超时退出 → 下次请求重新 fork

常见误区

  • 长时间不构建仍占内存:确认闲置回收配置与机器进程状态。
  • 手动停止 daemon 后担心构建异常:下次自动拉起,不影响增量记录。

追问

  • 如何手动停止全部 daemon?答:执行 stop 命令(以当前 Gradle 命令为准)。
  • 多版本 Gradle 会起多个 daemon 吗?答:不同版本/参数各有对应 daemon,互不混用。

04.8.3.1-094 平台 BOM 的版本对齐机制是什么?

一句话结论

BOM 在配置中作为平台依赖加入,解析器读取其声明的成员版本约束,为未显式指定版本的成员库选择 BOM 给定版本,实现一组库版本一致。

概念解释

BOM 自身是元数据模块,列出兼容的成员坐标与版本。平台约束优先级高于传递依赖自带版本,但低于模块显式声明的版本。对齐只覆盖 BOM 管理范围内的成员。

原理流程

  1. 脚本添加 platform(bom) 到 configuration。
  2. 解析器加载 BOM 版本清单。
  3. 成员库无显式版本时取 BOM 版本。
  4. 冲突时按平台优先级规则裁决。

代码或图示

dependencies {
    implementation(platform(libs.oss.bom))
    implementation(libs.oss.core)   // 版本跟随 BOM
}

常见误区

  • 以为 BOM 能升级不在清单内的库:未管理成员不受约束。
  • 成员显式写版本后还期待 BOM 对齐:显式版本优先,约束被绕过。

追问

  • BOM 约束与依赖冲突规则谁优先?答:平台约束参与冲突裁决,具体优先级顺序以 Gradle 文档为准。
  • 如何查看某库是否被 BOM 管理?答:依赖报告中标注平台来源与选定版本。

04.8.3.1-095 Gradle 版本冲突选择规则是怎样的?

一句话结论

同一模块出现多个版本时,Gradle 默认选择最高版本;平台约束、强制版本与显式声明按规则参与裁决,最终解析结果可在依赖报告中核对。

概念解释

依赖图合并后,同一 group:name 的不同版本进入冲突解决。默认最高版本策略保证运行 classpath 只有一份该模块。平台 BOM 提供期望版本,强制规则可覆盖选择。

原理流程

  1. 合并直接与传递依赖图。
  2. 按模块坐标分组多版本候选。
  3. 应用冲突策略(默认最高版本)与平台/强制规则。
  4. 选定版本进入解析结果。

代码或图示

候选:lib 1.2.0、lib 1.5.0(传递)
默认裁决:选择 1.5.0

常见误区

  • 以为选最低兼容版本:默认策略是最高,需要固定版本要显式约束。
  • 忽略传递依赖版本:冲突常由间接引入,需看全树。

追问

  • 想强制锁定某版本怎么做?答:平台约束或 resolutionStrategy 强制版本,记录原因。
  • 仲裁结果与预期不符看什么?答:依赖报告展示候选来源与选择理由。

04.8.3.1-096 传递依赖被意外升级或降级如何排查?

一句话结论

通过依赖树定位引入路径与最终版本,区分直接声明、传递引入与平台约束;异常版本通常来自某上游库的元数据或冲突裁决,按路径排除或显式对齐。

概念解释

本地 classpath 的版本是解析结果,不是任一声明点的版本。排查从最终版本反查哪些路径声明了哪些候选,再决定排除、显式版本或升级上游。

原理流程

  1. 输出目标模块依赖报告。
  2. 列出所有引入路径与候选版本。
  3. 确认裁决规则与平台约束来源。
  4. 针对性排除传递项或显式对齐版本。

代码或图示

app ──▶ service-lib ──▶ common:2.0
app ──▶ worker-lib ──▶ common:1.8
裁决:common:2.0(最高版本)

常见误区

  • 直接在本模块把版本压低:冲突下可能仍被最高版本覆盖,需处理上游。
  • 只看直接依赖列表:传递路径隐藏在二级、三级依赖中。

追问

  • 排除传递依赖怎么写?答:在引入它的依赖上 exclude group/module,避免全局误伤。
  • 升级上游库后版本自动对齐吗?答:上游元数据变化后重新解析,仍需核对裁决结果。

04.8.3.1-097 Gradle、Kotlin 编译器、KSP 等插件的兼容矩阵如何核对?

一句话结论

三者版本必须按官方兼容表配套:KGP 即 Kotlin 编译器版本,KSP 版本绑定特定 Kotlin 版本,Gradle 版本又需支持该 KGP;升级时先查官方矩阵再联动调整。

概念解释

KSP 处理器处理 Kotlin 源码,其版本与编译器 API 绑定;KGP 对 Gradle 最低版本有要求。错位会出现编译失败、KSP 报编译器版本不匹配。矩阵细节随版本演进,不确定处标待确认并以官方发布说明为准。

原理流程

  1. 确定目标 Kotlin 版本。
  2. 查对应兼容的 KSP 版本与 Gradle 最低版本。
  3. 同步升级目录中的插件、stdlib、KSP 条目。
  4. 构建验证注解处理与编译链路。

代码或图示

Kotlin 2.0.x ──配套 KSP 版本(见官方矩阵)──▶ 兼容 Gradle 8.x 区间

常见误区

  • 单独追新 KSP 而 Kotlin 不变:KSP 报不支持当前编译器版本。
  • 升级 Gradle 后才发现 KGP 太老:先核对矩阵再动构建版本。

追问

  • 在哪里查兼容矩阵?答:Kotlin 官网 KSP 文档与 Gradle/KGP 发布说明;本批版本基线为 Kotlin 2.x、Gradle 8.x、KSP 2.x。
  • 矩阵之间存在空窗期怎么办?答:选择官方明确配套的稳定组合,不自行混搭小版本。

04.8.3.1-098 CI 上的 Gradle 缓存策略如何设计?

一句话结论

CI 应缓存 Gradle 用户目录中的 wrapper 发行版与构建缓存,开启远程构建缓存复用任务产物;工作区产物按流水线策略清理,避免缓存膨胀与跨任务污染。

概念解释

wrapper 发行版缓存避免每次下载 Gradle;本地构建缓存目录缓存任务输出;远程缓存跨流水线共享。CI 配置需区分可缓存目录与生成物目录,并行任务之间隔离工作区。

原理流程

  1. 流水线拉取代码后恢复 Gradle 缓存目录。
  2. 构建使用缓存的 wrapper 与任务产物。
  3. 结束后回写本地缓存并上传远程条目。
  4. 按策略过期清理缓存体积。

代码或图示

CI 阶段:restore cache → build(命中远程/本地缓存)→ save cache → 上传远程条目

常见误区

  • 把模块 build 目录当缓存持久化:生成物应重建,持久化会带来状态污染。
  • 缓存键不含分支/版本维度:跨分支错误复用产物。

追问

  • wrapper 版本升级后缓存如何失效?答:不同 Gradle 版本发行版目录隔离,自然分开缓存。
  • 缓存与并行流水线冲突吗?答:产物不可变、按哈希寻址;写入按条目追加,工作区各自隔离。

04.8.3.1-099 如何用构建扫描或 profile 定位构建慢的环节?

一句话结论

通过构建 profile/扫描报告拆分配置阶段、任务执行、依赖解析与各任务耗时,定位最长任务与配置瓶颈,再针对性优化增量、缓存与并行。

概念解释

慢构建要先量化再优化:配置慢查任务创建与脚本逻辑;执行慢查编译、测试、打包任务;解析慢查仓库与网络。凭感觉加大内存往往无效。

原理流程

  1. 生成 profile 报告或构建扫描链接。
  2. 拆分配置、依赖解析、任务执行时间。
  3. 列出耗时 Top 任务及其状态(重跑/UP_TO_DATE/FROM_CACHE)。
  4. 按瓶颈类型选择优化手段。

代码或图示

耗时拆解:脚本配置 → 依赖解析 → 任务执行(编译/测试/打包)→ 收尾

常见误区

  • 只看总构建时长:不拆分阶段无法判断瓶颈在配置还是执行。
  • 优化未命中缓存的任务却不查输入声明:缓存命中率低才是根因。

追问

  • 配置阶段耗时高怎么优化?答:减少 create/遍历、下沉 convention plugin、启用配置缓存。
  • 执行阶段编译占比高怎么优化?答:核对增量是否生效、编译守护进程内存与模块拆分。

04.8.3.1-100 一次 Kotlin/Gradle 版本升级在工程上应按什么流程落地?

一句话结论

先查兼容矩阵确定配套版本组合,在版本目录统一升级,单模块试点编译与测试,再全量回归构建、生成代码链路与 CI 缓存策略,最后观察警告与性能。

概念解释

升级涉及编译器、标准库、KSP/编译器插件、Gradle 与静态分析工具的配套。直接全量跳版本容易在生成代码、字节码兼容处出问题。分步升级可回滚、定位影响面。

原理流程

  1. 查 Kotlin/Gradle/KSP/插件兼容矩阵,确定目标组合。
  2. 目录升级版本段,本地试点模块编译。
  3. 修复新警告与 API 迁移点。
  4. 全量构建 + 测试 + 打包,验证 CI 缓存与产物。

代码或图示

矩阵确认 → 目录升级 → 试点编译 → 警告/迁移修复 → 全量回归 → CI 与缓存验证

常见误区

  • 一次性跨多个大版本升级:迁移说明与行为变化叠加,问题难定位。
  • 升级后不跑生成代码链路:注解处理/序列化插件兼容问题只在编译期暴露。

追问

  • 升级后编译报错如何分类?答:语法迁移、API 弃用、插件不兼容三类分别处理;插件类先升级配套版本。
  • 如何判断升级收益?答:对比升级前后配置与编译耗时、警告数量与产物体积。

参考来源

  • Gradle 官方文档:Kotlin DSL 使用指南,覆盖脚本结构、类型安全访问器与任务配置,https://docs.gradle.org/current/userguide/kotlin_dsl.html
  • Gradle 官方文档:Version Catalog 目录格式与访问器规则,https://docs.gradle.org/current/userguide/version_catalog.html
  • Gradle 官方文档:任务配置避免(Task Configuration Avoidance)与懒注册 API,https://docs.gradle.org/current/userguide/task_configuration_avoidance.html
  • Kotlin 官方文档:Gradle 构建脚本与 Kotlin 编译器选项配置,https://kotlinlang.org/docs/gradle.html
  • Kotlin 官方文档:Kotlin 编译器选项与 freeCompilerArgs 说明,https://kotlinlang.org/docs/gradle-compiler-options.html

待整理清单

  • [ ] 核对当前 Gradle 8.x 版本下 buildSrc 引用主工程版本目录的精确配置语法(见 04.8.3.1-043)
  • [ ] 核对 Kotlin 2.x K2 编译器下增量编译的失效边界与全量触发条件(见 04.8.3.1-075)
  • [ ] 核对 Kotlin 编译守护进程内存与闲置回收的具体属性名(见 04.8.3.1-091、04.8.3.1-093)
  • [ ] 补充团队内部仓库镜像与插件门户代理的实际配置示例
  • [ ] 收集本工程多模块依赖树样本,用于版本对齐与冲突排查题的落地对照