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 在运行期才解析属性,错误往往等到执行任务时暴露。
原理流程
- Gradle 启动后加载 settings 与各模块 build 脚本。
- Kotlin DSL 脚本先经过 Kotlin 编译器编译,产物进入脚本编译缓存,再在配置阶段执行。
- Groovy DSL 由 Groovy 运行时直接解析执行,无独立编译步骤。
- 两种 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 类型的推断。
原理流程
- 应用插件后,插件向 Project 注册命名 extension。
- Gradle 在脚本编译期根据已知插件映射生成访问器元信息。
- 脚本通过
the<JavaPluginExtension>()或对应访问器取得强类型对象。 - 访问器不可用时回退到
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 状态,任务执行阶段读取该状态。
原理流程
- 插件应用时创建 extension 实例并注册到 Project。
- DSL 生成或解析对应配置方法,接收
Action<T>或带接收者 lambda。 - 配置块在配置阶段回调,向 extension 写入参数。
- 相关任务在执行阶段读取 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 无编译步骤,因此冷启动更快,但代价是缺少类型安全。
原理流程
- 首次执行:解析脚本依赖 classpath,编译
build.gradle.kts。 - 产物写入 Kotlin DSL 脚本缓存目录。
- 后续执行:校验脚本与输入哈希,命中则直接加载缓存 class。
- 脚本、插件版本或 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 常见于根项目统一管理插件版本、子模块按需应用的多模块结构。
原理流程
plugins{}块经 pluginManagement 解析插件 marker 坐标。- 解析成功后插件 classpath 进入脚本编译 classpath,访问器可用。
- 默认
apply true,插件立即应用;apply false仅登记版本。 - 子模块再通过
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。
原理流程
- 声明依赖时绑定到对应 configuration。
- 编译任务按 compile classpath 解析依赖集合。
- 运行任务按 runtime classpath 解析另一份集合。
- 下游模块编译时只能看到上游声明为
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 解析。
原理流程
- 脚本解析坐标字符串为 group/name/version。
- 按
repositories声明顺序查询模块元数据。 - 应用版本冲突规则与平台对齐规则。
- 解析出的模块进入对应 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 方法里。
原理流程
register生成任务注册信息,不立即构造任务对象。- 任务被依赖链选中后才实例化,执行配置块。
- 输入输出属性被注解或 API 声明,供增量与缓存判定。
- 执行阶段运行任务动作。
代码或图示
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 接收者即为该类型,无需手动强转。
原理流程
tasks.named<T>(name)返回TaskProvider<T>。- 配置块 lambda 接收
T类型任务实例。 - 类型不匹配时 Gradle 在配置期抛出类型转换异常。
- 任务实际执行时属性值已就绪。
代码或图示
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 与编译任务。
原理流程
kotlin("jvm")展开为插件 id 并解析版本。- 插件注册
compileKotlin、compileTestKotlin等任务。 - 配置
kotlin { }扩展调整编译选项。 - 编译任务把 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 现代约定。
原理流程
- 启动时先解析 settings 脚本,构建工程树。
- pluginManagement 决定插件从哪里解析、版本如何对齐。
- include/includeBuild 确定纳入构建的模块。
- 随后各工程 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 脚本顶部。
原理流程
- settings 脚本先读取
pluginManagement。 - 按声明仓库顺序查找插件 marker 与实现构件。
- 应用版本规则(如对齐到 BOM)。
- 解析出的插件 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 编译成本。多人协作时该缓存只在本地,不进远程构建缓存。
原理流程
- 计算脚本及其依赖输入的哈希。
- 哈希匹配则加载已编译 class。
- 不匹配则调用 Kotlin 编译器重新生成 class。
- 新 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 脚本要求类型明确、访问器存在。直接改名会出现未解析引用、类型不匹配等编译错误。注释与坐标字符串可保留,逻辑语句需转换。
原理流程
- 先复制脚本为
.kts,保留依赖坐标与仓库声明。 - 动态属性改为 extension API 或
extra["..."]。 - 任务配置改为
register/withType懒写法。 - 编译脚本直至类型检查通过。
代码或图示
// 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 或脚本内联。动作方法只在执行阶段运行,读取已注入的属性值。
原理流程
- 任务类继承
DefaultTask,抽象属性由 Gradle 注入实现。 - 注解声明输入输出,参与增量与缓存判定。
register绑定任务名与类型。- 执行阶段实例化任务并调用
@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,二者都是工程化的替代方案。
原理流程
- 根项目
extra.set("key", value)写入属性。 - 子项目通过
(project.rootProject.extra.properties["key"])读取。 - 类型不安全处需显式转换。
- 公共依赖与编译配置改由 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 ...) } 更符合配置避免原则,也不会触发未选中任务的创建。
原理流程
- 注册类型过滤规则。
- 任务实例化时检查类型,匹配则执行配置动作。
- 未被选中的任务不会执行该配置块。
- 配置结果写入任务属性供执行阶段使用。
代码或图示
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,避免在配置阶段读取产物文件内容。
原理流程
- 声明
Property<String>并set(...)或set(provider)。 - 配置阶段只记录来源,不调用
get()。 - 执行阶段或缓存计算时才
get()取值。 - 上游任务输出 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 引用的位置。
原理流程
- 脚本顶部 import 所需类型。
- 顶层声明辅助函数/类,编译进脚本 class。
- 配置块调用辅助函数完成声明式配置。
- 跨脚本复用改为 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 是兜底手段,不依赖访问器生成。
原理流程
- 检查
plugins{}是否声明该插件。 - 核对插件版本与 Gradle/Kotlin 兼容矩阵。
- 清理脚本缓存后重新同步。
- 仍无访问器则按 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 自身改动会使所有脚本缓存失效。
原理流程
- 启动构建时识别根目录
buildSrc。 - 按其构建脚本编译类与资源。
- 编译产物加入脚本编译与执行 classpath。
- 主构建各模块脚本可直接 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 依赖传递给业务模块。这种隔离避免构建工具污染业务产物。
原理流程
- buildSrc 编译时解析自身依赖。
- 产物与依赖进入脚本 classpath 供脚本使用。
- 主业务模块按各自 dependencies 重新解析。
- 两边依赖集合互不传递。
代码或图示
// 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 解决"脚本复用类"问题,没有独立产物坐标;复合构建解决"本地联调多工程"问题,被纳入工程可以是库或插件,通过替换规则对外提供构件。复合构建更灵活,但配置复杂度更高。
原理流程
- buildSrc:自动编译,产物进脚本 classpath,无坐标替换。
- 复合构建:settings 中
includeBuild引入独立工程。 - 可选
substitute把外部坐标映射到本地工程产物。 - 主构建解析依赖时优先使用本地工程输出。
代码或图示
// 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。
原理流程
- 梳理 buildSrc 中稳定、可复用的配置逻辑。
- 新建 plugin 工程,定义 extension 与
apply逻辑。 - 本地用 includeBuild 联调,需要时发布到内部仓库。
- 主工程脚本
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 工件一一对应。
原理流程
- plugin 工程实现
Plugin<Project>并声明 id。 - settings 中
includeBuild("../build-plugins")。 - 主工程
plugins { id("com.example.convention.kotlin") }。 - 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。这种方式适合团队内部插件快速迭代。
原理流程
- plugin 工程实现入口类与 marker 声明。
- settings 登记 includeBuild 路径。
- 主工程引用插件 id,Gradle 解析到纳入构建产物。
- 修改 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 + 注册任务"三步。封装的是团队约定的默认值,而不是锁死所有配置;工程脚本可在插件应用后继续调整。
原理流程
- 实现
Plugin<Project>接口。 apply内应用 JVM、Kotlin 等基础插件。- 获取 extension 写入编译目标、依赖平台等约定。
- 注册必要任务并声明输入输出。
代码或图示
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 再在工程脚本中按名字配置。
原理流程
- 插件 apply 顺序保证目标 extension 已注册。
getByType从注册表取出强类型对象。- 写入约定值或读取工程配置。
- 未注册时
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 工程同理。跨工程共享目录需要显式关联,不能假设主工程目录自动可见。
原理流程
- 在目录文件中定义插件与依赖版本。
- buildSrc/plugin 脚本按 Gradle 支持方式引用目录或复制必要版本声明。
- 两边解析同一组坐标。
- 版本升级时集中改目录并回归两边构建。
代码或图示
// 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 类即改变该哈希,缓存条目整体作废。
原理流程
- 修改 buildSrc 源码。
- buildSrc 任务重新编译,产物哈希变化。
- 脚本编译缓存输入失配,脚本重编译。
- 依赖脚本 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 表达。
原理流程
- plugin 应用基础插件并解析版本目录中的 BOM。
- 给公共 configuration 添加平台依赖与公共库。
- 配置编译参数与测试约定。
- 业务模块应用 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 连接,配置顺序更健壮。
原理流程
- plugin apply 时只调用
register登记任务。 - 配置块内用 Provider 绑定 extension 值。
- 任务被选中执行时才实例化并读取最终配置。
- 未被选中的任务不产生实例化成本。
代码或图示
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 分支。
原理流程
- 基础 plugin 封装 Kotlin 编译与测试约定。
- library plugin 应用基础 plugin 并配置 API 可见性。
- application plugin 应用基础 plugin 并配置归档与主类。
- 各模块按需声明对应 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。两类代码的生命周期、依赖与产物边界不同,必须分离。
原理流程
- buildSrc 产物只进入脚本 classpath。
- 业务编译 classpath 来自模块 dependencies 解析。
- 两者不互相传递。
- 业务类迁移到库模块后由应用模块依赖引入。
代码或图示
错误做法: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 与实现坐标解耦,便于重打包与内部镜像。
原理流程
- 插件工程用
gradlePlugin插件生成 marker 与主 jar。 - 发布时两个构件进入仓库。
- 主工程按 id 拉取 marker。
- 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),脚本中按别名引用;别名拼错在脚本编译期即可发现。
原理流程
- 在
gradle/libs.versions.toml定义版本、库坐标、捆绑包与插件。 - Gradle 解析目录生成类型安全访问器。
- 模块脚本用
libs.xxx引用,展开为坐标与版本。 - 升级时只改目录一处,全工程同步。
代码或图示
[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 是别名到多个库的映射,便于一次性添加一组相关依赖。
原理流程
- 版本段声明具名版本。
- 库段引用版本段或直接写
version。 - bundle 段列出库别名列表。
- 插件段独立维护插件 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 把别名单词分隔符拆开,首段后其余段作为属性层级。含连字符的词合并为驼峰。访问器在脚本编译期生成,重命名别名会同步改变访问器路径。
原理流程
- 解析别名分段。
- 每段转驼峰命名。
- 库访问器挂在
libs下,插件挂在libs.plugins下。 - 脚本按层级链访问,拼错即编译错误。
代码或图示
[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 管任务类型。
原理流程
- 版本升级只改 TOML 数值。
- Gradle 重新解析目录生成访问器。
- 模块脚本无需改动。
- 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 + 运行器)。成组引入避免漏配其中某一个库。
原理流程
- 目录
[bundles]列出库别名数组。 - Gradle 生成 bundle 访问器。
- 脚本把 bundle 加入 configuration。
- 解析时逐个展开为独立依赖条目。
代码或图示
[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 建立条目与版本名的关联,避免在每个库条目重复写版本字符串。版本段缺失或引用名拼错会在目录解析阶段报错。版本段也可只被插件引用。
原理流程
[versions]定义name = "x.y.z"。- 条目写
version.ref = "name"。 - 解析时按名查版本段替换。
- 生成坐标进入依赖集合。
代码或图示
[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。
原理流程
[plugins]条目含 id 与版本。alias(...)在 plugins 块解析插件 marker。- 库条目在 dependencies 块解析模块构件。
- 两套 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 内只维护插件工具版本。
原理流程
- 确认 Gradle 版本对 buildSrc 引用目录的支持。
- 在 buildSrc 构建脚本中关联主目录文件或复制必要声明。
- 解析生成 buildSrc 侧访问器。
- 两边版本保持人工或脚本对齐。
代码或图示
# 待确认:buildSrc 引用主工程 libs.versions.toml 的精确语法随 Gradle 版本变化;
# 落地前核对当前 Gradle 版本文档中 dependencyResolutionManagement 与 versionCatalogs 配置。
常见误区
- 直接在 buildSrc 脚本写
libs.xxx不报错才怪:未关联目录时访问器不存在。 - 两边版本各写一份不核对:升级时容易漏改导致工具链不一致。
追问
- 工具链插件版本放哪最不容易漂移?答:集中到主目录,buildSrc 按文档方式引用;无法引用时在评审中强制核对。
- 关联后升级目录需要重新同步吗?答:下次构建解析目录即可,脚本缓存按输入哈希更新。
04.8.3.1-044 目录别名冲突或重复会怎样?
一句话结论
同一文件内别名重复定义会在目录解析时报错;不同库生成相同访问器路径也会冲突,需要调整别名分段避免碰撞。
概念解释
访问器由别名生成,别名设计要保证段路径唯一。冲突在目录加载阶段暴露,不会静默选其一。插件 id 与库别名是不同命名空间,但库之间、插件之间各自不能撞名。
原理流程
- 解析 TOML 构建别名索引。
- 检测重复键与重复访问器路径。
- 冲突即终止配置并报错。
- 修正别名后重新解析。
代码或图示
# 冲突示例:两个别名生成同一访问器,需改名区分
[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 条目与普通库写法相同。
原理流程
- 目录声明 BOM 坐标与版本。
- 脚本
implementation(platform(libs.bom))。 - 解析器应用 BOM 约束到成员依赖。
- 成员库不显式写版本时跟随 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)。目录条目区分主构件与附加构件,脚本按别名分别引入。附加构件通常用于测试编译或源码审计,不进运行时。
原理流程
- 仓库中模块按
group:artifact:version:classifier发布构件。 - 目录条目记录 classifier。
- 解析时拉取对应附加 jar。
- 加入指定 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(...) 依赖不属于模块坐标,也不进目录。实验库确认保留后再迁入目录。
原理流程
- 判断依赖是否多模块复用或需版本对齐。
- 正式复用条目迁入目录并起别名。
- 临时依赖留在模块脚本并标注用途。
- 实验转正式后补登目录。
代码或图示
dependencies {
// 临时本地文件,不进目录
implementation(files("libs/local-tool.jar"))
}
常见误区
- 目录堆积大量只被引用一次的别名:可读性下降,升级时评审面变大。
- 把插件快照调试坐标固化进目录:污染统一版本基线。
追问
- 本地 Maven 仓库依赖能进目录吗?答:坐标可声明,但仓库来源由 repositories 配置决定。
- 如何清理目录冗余条目?答:检索别名引用次数,无引用且无保留计划的删除。
04.8.3.1-048 版本目录与旧版 ext 共享版本方式相比有什么实质变化?
一句话结论
ext 共享的是无类型字符串常量,目录共享的是结构化坐标声明并带类型安全访问器与解析校验;前者靠约定维护,后者在脚本编译期与目录解析期双重检查。
概念解释
早期多模块用根项目 ext { versions = [...] } 或 buildSrc 常量传版本号,坐标字符串仍手写。目录把 group/artifact/version 结构化,别名访问器在编译期校验存在性,目录错误更早暴露。
原理流程
- 旧方式:脚本拼坐标字符串,版本来自 ext 常量。
- 新方式:目录条目结构化为模块描述符。
- Gradle 生成访问器并校验目录完整性。
- 脚本只引用别名,不手写坐标片段。
代码或图示
// 旧 Groovy 风格:版本与坐标分散
implementation "com.fasterxml.jackson.core:jackson-databind:$jacksonVersion"
常见误区
- 以为目录只是把 ext 换个文件存:它还带来访问器生成与条目校验,能力不止常量托管。
- 迁移时保留手写坐标双轨:长期应逐步收敛到别名。
追问
- 目录支持版本锁定文件吗?答:Gradle 依赖锁定是独立机制,目录负责声明,锁定文件记录解析结果(以当前版本功能为准)。
- 老脚本能否逐步迁移到目录?答:可以,按模块分批替换坐标为别名,目录先行建立。
04.8.3.1-049 版本目录在哪个阶段被校验?
一句话结论
目录在 settings 解析后的配置早期被加载校验:别名、坐标格式、版本引用、plugin id 完整性在此阶段检查,错误先于任务执行暴露。
概念解释
目录解析早于各 build 脚本配置,因此条目拼写错误、缺失版本段、坏模块坐标会在配置期失败,不会拖到编译任务。访问器生成也基于校验通过的目录。
原理流程
- settings 脚本加载目录定义。
- 解析器校验 TOML 结构与引用闭合。
- 生成访问器元信息供脚本编译。
- 模块脚本引用别名时再做存在性检查。
代码或图示
settings 解析 → 目录校验 → 脚本编译(访问器检查)→ 模块配置 → 任务执行
常见误区
- 以为目录错误要等编译任务才报:实际配置早期即失败。
- 运行期才新增目录条目却不同步脚本:访问器缺失在脚本编译期暴露。
追问
- 目录校验能否跳过坏条目继续?答:错误条目阻断构建,需修复后再同步;不提供静默忽略。
- 如何在 CI 上提前验证目录?答:执行配置阶段任务(如 help 或依赖解析任务)即可触发校验。
04.8.3.1-050 如何升级目录中一组互相兼容的版本?
一句话结论
用同一版本段管理配套库与插件版本,升级时改版本段一处;BOM 管理的成员库只升 BOM 版本,成员不显式锁定版本,由平台对齐。
概念解释
配套版本(如 Kotlin 插件与标准库、Jackson 全家桶)必须兼容。版本段复用保证同步修改;BOM 则在解析期约束成员版本。升级后回归编译、测试与生成代码链路。
原理流程
- 确认上游兼容版本范围与发布说明。
- 修改版本段或 BOM 版本号。
- 重新解析依赖,检查冲突报告。
- 跑构建与测试验证生成代码与二进制兼容。
代码或图示
[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 的目录不参与构建,其脚本也不被加载。
原理流程
- settings 脚本列出 include 条目。
- Gradle 为每个条目创建工程节点并定位目录。
- 加载各工程 build 脚本。
- 模块间依赖通过工程坐标声明。
代码或图示
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)同样决定向下游的传递可见性。
原理流程
- 脚本
add工程依赖到 configuration。 - Gradle 把对应模块输出纳入 classpath。
- 任务图按依赖排序执行上游编译。
- 形成环依赖时报配置错误。
代码或图示
dependencies {
implementation(project(":domain"))
api(project(":common-model"))
}
常见误区
- 模块间循环依赖:编译顺序无法确定,应调整边界拆分模块。
- 下游直接依赖上游的内部实现类:说明 api 边界没守住。
追问
- 工程依赖与外部坐标依赖能互相替换吗?答:复合构建中可做 substitute 替换;普通多模块直接用 project 依赖。
- 测试源码能否被下游依赖?答:测试类默认不对外,需要测试 jar 配置单独发布。
04.8.3.1-053 复合构建 includeBuild 解决什么问题?
一句话结论
includeBuild 把一个独立 Gradle 工程纳入当前构建,用于本地联调尚未发布的库或插件,按替换规则让主工程解析到本地工程产物而非仓库坐标。
概念解释
单仓多模块用 project 依赖即可;跨仓库联调时,源码在另一个目录,复合构建提供不发布即可替换坐标的能力。被纳入工程按独立构建运行,产物回供给主构建解析。
原理流程
- settings 中
includeBuild("../other")。 - 可选声明 dependencySubstitution 映射坐标到本地工程。
- 主构建解析依赖时命中替换规则。
- 使用本地工程输出构件。
代码或图示
includeBuild("../shared-lib")
常见误区
- 把 includeBuild 当多模块 include 用:二者结构与替换语义不同,混用会让工程树混乱。
- 纳入工程自身还有未提交改动导致联调不可复现:联调环境需记录纳入工程版本。
追问
- 被纳入工程需要安装到本地仓库吗?答:不需要,复合构建直接消费其构建产物。
- 复合构建能传递依赖给下一层纳入工程吗?答:解析规则逐层独立,复杂嵌套以 Gradle 文档为准。
04.8.3.1-054 复合构建中的 substitute 替换规则如何写?
一句话结论
在 includeBuild 块内用 substitute(module("group:name")).using(project(":子工程")) 把外部坐标映射到被纳入工程的指定子工程产物。
概念解释
替换规则只在当前复合构建解析期生效,不改动发布仓库坐标。未命中替换的坐标仍从仓库解析。规则可按模块名精确替换,避免整仓重定向。
原理流程
- includeBuild 引入外部工程。
- 配置 substitution 映射坐标到工程路径。
- 主构建解析该坐标时查表命中。
- 改用本地工程产物,仓库构件被跳过。
代码或图示
includeBuild("../shared-lib") {
dependencySubstitution {
substitute(module("com.example:shared-lib")).using(project(":core"))
}
}
常见误区
- 替换坐标与本地工程产物不一致:编译/打包出现类缺失或版本不符。
- 在 CI 上保留本地路径替换:会导致构建找不到相对路径,应按环境分离配置。
追问
- 如何确认替换已生效?答:查看依赖解析结果,对应模块来源显示为本地纳入工程。
- 替换规则能按变体区分吗?答:替换针对模块坐标;变体选择仍由 configuration 规则处理。
04.8.3.1-055 本地依赖的库源码改动但不想重新发布,怎么联调?
一句话结论
用复合构建 includeBuild + substitute 把该库坐标指向本地源码工程,主构建直接消费本地编译产物;修改库源码后随主构建增量重编,无需安装到本地仓库。
概念解释
传统方式要先 publishToMavenLocal 再让主工程解析 mavenLocal,步骤多且容易残留旧快照。复合构建在同一构建会话内联动两边任务,源码改动即时反映。
原理流程
- 本地检出待联调库源码。
- settings 纳入并配置坐标替换。
- 主构建解析时使用本地库工程输出。
- 改动库源码触发其编译任务,主工程重新链接。
代码或图示
主工程 ──解析 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 由模块主动声明,边界清晰。
原理流程
- 旧写法:根脚本 subprojects 块内统一加仓库、依赖、编译参数。
- 所有子工程被无条件配置。
- 新写法:公共能力封装为 plugin,模块
plugins{}选择应用。 - 配置来源显式可追溯到模块脚本。
代码或图示
// 不推荐:隐式覆盖所有子工程
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 或由运行环境提供。
原理流程
- 明确模块是库还是应用。
- 按可见性声明依赖配置。
- 归档任务解析 runtime classpath 打包。
- 检查产物内容,剔除误打包的编译期/测试库。
代码或图示
tasks.jar {
duplicatesStrategy = DuplicatesStrategy.EXCLUDE
}
// 应用模块 fat jar 配置按所用打包插件为准
常见误区
- 测试依赖漏配到 testImplementation:被打进运行产物。
- 库模块把实现细节库标 api:下游被动接收一堆传递依赖。
追问
- 如何查看打包内容?答:解压产物或运行依赖/归档分析任务,核对条目列表。
- 多模块共享资源如何打包?答:资源随模块 jar 进入 classpath,不重复拷贝到应用产物。
04.8.3.1-058 模块分组与输出目录如何组织?
一句话结论
工程路径按领域分层(如 :order:api、:order:domain),构建输出默认落在各模块 build/ 下;归档产物通过发布任务或根聚合任务收集,不手工挪动 _site 之外的生成物。
概念解释
目录分组影响 include 路径与依赖可读性,不改变 Gradle 解析规则。输出目录由布局约定决定,自定义输出应通过任务输出属性声明,而不是脚本里硬编码拷贝路径。
原理流程
- 目录与工程路径按领域命名。
- 编译/打包任务写入模块 build 目录。
- 聚合任务读取各模块输出 Provider。
- 最终产物由发布或归档任务统一产出。
代码或图示
app/
order-api/
order-domain/
order-infra/
常见误区
- 任务动作里写死输出绝对路径:机器迁移后失效,应用
layout.buildDirectory。 - 手工清理模块 build 目录后不更新任务状态:下次构建按增量规则重算。
追问
- 如何统一改输出根目录?答:通过
layout.buildDirectory属性配置,不要在脚本拼字符串路径。 - 聚合所有 jar 的任务怎么写?答:注册任务收集各模块 jar 输出 Provider,执行阶段拷贝或归档。
04.8.3.1-059 单模块构建与全量构建命令如何选择?
一句话结论
命令行指定模块路径与任务名可只构建该模块及其依赖;不带模块限定则执行全工程任务图。按需构建减少反馈时间,CI 全量构建保证整体一致。
概念解释
Gradle 按任务依赖决定是否需要先构建上游模块。单模块构建会自动编译其依赖的工程模块,跳过无关分支。全量构建在合并前或 CI 上运行,覆盖所有模块。
原理流程
- 命令行解析目标任务与模块路径。
- 构建任务图,纳入必要上游模块。
- 无关模块不进入执行图。
- CI 上执行根工程全量任务。
代码或图示
# 仅构建 app 模块及其上游(命令以项目脚本封装为准)
gradle :app:build
# 全量
gradle build
常见误区
- 单模块通过测试后就提交:未跑全量集成与跨模块编译,合并前需补全量。
- 认为跳过的模块没有风险:接口变更可能影响未构建的下游。
追问
- 如何只跑某个模块测试?答:
:模块:test,上游依赖按图构建。 - 并行构建如何开启?答:在配置中开启并行执行,任务独立时各模块并行编译。
04.8.3.1-060 复合构建与发布到本地 Maven 仓库联调相比优劣如何?
一句话结论
复合构建直接链接源码产物、免安装、改动联动;本地 Maven 仓库方式兼容只认坐标的消费方,但需要手动发布快照、易残留旧包。
概念解释
mavenLocal 依赖解析把本地仓库当普通仓库,发布动作独立于主构建;复合构建在一次会话内完成源码到产物的替换。消费方无法改造时(如外部工程只读坐标)才需要本地仓库发布。
原理流程
- 库工程发布快照到 mavenLocal。
- 主工程仓库列表包含 mavenLocal 并解析快照。
- 改动库需重新发布才生效。
- 复合构建则跳过发布步骤,直接消费工程输出。
代码或图示
方式 A:lib publishToMavenLocal → 主工程解析 mavenLocal
方式 B:includeBuild 源码产物 → 主工程直接替换坐标
常见误区
- 本地仓库残留旧快照被优先解析:出现"改了没生效",需清理或调整仓库顺序。
- 把 mavenLocal 放仓库列表首位污染 CI:CI 环境不应依赖开发者本地仓库。
追问
- 快照版本刷新策略怎么配?答:按 Gradle 缓存规则控制快照过期,生产构建应锁定发布版本。
- 两种方式能否并存?答:可切换,但同一构建内避免替换规则与本地快照互相干扰。
04.8.3.1-061 included build 的依赖可见性有什么限制?
一句话结论
被纳入构建有自己的依赖图与配置隔离,其实现依赖不自动暴露给主工程;主工程只消费纳入工程对外产物,跨构建共享平台或插件需显式声明。
概念解释
复合构建是多个独立 Gradle 运行单元的组合,各自解析依赖。纳入工程的 implementation 依赖不会传递到主工程编译 classpath。平台 BOM 等共享约束需在两边分别配置。
原理流程
- 纳入工程独立解析自身依赖。
- 产物作为构件回供主构建。
- 主工程按自己的依赖规则再解析。
- 两侧 classpath 不自动合并。
代码或图示
included lib:compile classpath ──▶ lib jar ──▶ 主工程 runtime/compile classpath
(lib 的传递依赖仍按其发布元数据参与主工程解析)
常见误区
- 以为纳入工程加过的库主工程可直接 import:需主工程显式声明。
- 在纳入工程与主工程放不同版本同一库:解析时按冲突规则裁决,可能出现不一致。
追问
- 纳入工程的插件会应用到主工程吗?答:不会,主工程插件解析独立;插件联调需按插件复合构建方式纳入。
- 如何核对跨构建依赖版本?答:分别查看两边依赖报告,确认对齐。
04.8.3.1-062 多模块版本对齐与依赖收敛怎么做?
一句话结论
用平台 BOM 约束成员版本,版本目录统一登记坐标,convention plugin 收口公共依赖;定期分析依赖树,移除重复与过时传递依赖。
概念解释
对齐目标是同一库在全工程只有一个解析版本。BOM 提供约束,目录提供声明,插件提供默认引入。依赖收敛还要排除不需要的传递依赖,缩小 classpath 体积与冲突面。
原理流程
- 目录登记公共库与 BOM 版本。
- plugin 给模块加平台依赖与公共库。
- 解析阶段按冲突规则选版本。
- 定期审查依赖树,排除冗余传递项。
代码或图示
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 性能优化的基础原则之一。
原理流程
- 脚本与插件调用 register 登记任务类型与名称。
- 配置阶段不实例化未被选中任务。
- 任务图根据命令行与依赖关系确定目标任务集合。
- 仅目标集合内任务被实例化并执行配置块。
代码或图示
// 懒注册:配置阶段只登记
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()。
原理流程
- register:保存类型、名称、配置 lambda。
- 任务被选中后实例化,配置 lambda 执行。
- create:调用即实例化并配置。
- 配置阶段任务数量越大,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 懒规则。
原理流程
- 命令行确定目标任务。
- 懒规则按类型/名称登记待配置条件。
- 实例化发生在任务图确定后。
- 立即遍历会把未选中任务也拉入配置阶段。
代码或图示
// 不推荐:立即遍历
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 连接值来源。
原理流程
- 脚本正常配置阶段执行。
- afterEvaluate 动作排入队列。
- 工程评估完成后批量执行队列。
- 此时再读任务/属性可能已绕过懒解析。
代码或图示
// 脆弱写法
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 无法感知这些变量,缓存复用时仍按旧输入判定命中。
原理流程
- 任务输入属性声明为
@Input/@InputFiles等。 - 执行前快照输入哈希计算缓存键。
- 命中缓存则下载历史输出,跳过动作。
- 未声明的读取项变化不会进键,造成错误复用。
代码或图示
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 表示无论主任务成功失败都执行收尾任务。
原理流程
- 注册主任务与收尾任务,各持 Provider。
- 主任务声明
finalizedBy(provider)。 - 任务图解析时建立节点边。
- 执行阶段按拓扑顺序运行。
代码或图示
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 操作都会计入配置耗时。任务动作内的打印只在任务被执行时输出。
原理流程
- 脚本配置阶段执行顶层语句。
- 顶层 println 立即输出。
- 任务图确定后才执行动作块。
- 无关目标任务不会触发动作打印。
代码或图示
// 配置阶段每次都打印(不推荐)
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 等懒类型,配合注解使用。
原理流程
- 任务类属性标注输入/输出注解。
- 执行前快照输入值与文件哈希。
- 与上次运行记录对比:一致且输出存在则 UP_TO_DATE。
- 开启缓存时按输入哈希查远程/本地缓存命中历史输出。
代码或图示
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。文件内容哈希比时间戳更可靠,避免触碰时间造成误重跑。
原理流程
- 任务图确定后逐个检查可增量任务。
- 快照当前输入值与文件哈希。
- 与历史记录对比并检查产物完整性。
- 未变化跳过,变化则执行动作并更新记录。
代码或图示
任务执行记录:输入哈希 + 输出文件清单 + 执行元数据
下次构建:当前快照 ──对比──▶ 一致 → UP_TO_DATE;不一致 → 执行
常见误区
- 改动注释就全量重编:注释变化同样改变源码哈希,属预期;Kotlin 增量编译可在类粒度缩小影响面。
- 手工改 build 目录产物:记录与产物不一致,下次可能重跑或报错。
追问
- 增量记录存哪里?答:Gradle 在构建目录维护任务历史记录,清理 build 目录后首次全量重跑。
- 如何强制重跑某任务?答:可强制刷新该任务(命令参数以当前 Gradle 版本为准),或清理对应输出。
04.8.3.1-072 本地构建缓存与远程构建缓存有什么区别?
一句话结论
本地缓存只在本机 Gradle 缓存目录复用历史任务输出;远程缓存是团队共享的服务端缓存,不同机器、不同流水线之间可互相复用任务产物。
概念解释
两类缓存键计算规则相同,区别在存储位置与共享范围。本地缓存加速重复构建与切换分支;远程缓存让 CI 构建产物被开发机命中,或流水线之间复用。缓存条目按输入哈希寻址。
原理流程
- 任务可缓存且输入哈希计算完成。
- 先查本地缓存,未命中再查远程缓存。
- 命中则下载/复用历史输出,跳过动作。
- 未命中执行任务,产物写入本地并上传远程(按配置)。
代码或图示
// 目录或 gradle.properties 中开启缓存(具体属性名以当前 Gradle 文档为准)
// org.gradle.caching=true
常见误区
- 以为开启缓存就一定复用:任务必须声明输入输出且无隐式状态,才具备可缓存性。
- 远程缓存长期不清理:旧条目占用空间,需按策略过期清理。
追问
- 远程缓存服务怎么部署?答:使用兼容 Gradle 缓存协议的 HTTP 服务端;团队内选型与部署以基础设施方案为准。
- 缓存条目包含源码吗?答:缓存的是任务输出产物与元数据,不直接缓存源码;输入哈希引用源文件内容。
04.8.3.1-073 构建缓存键由什么构成?
一句话结论
缓存键由任务类自身、输入属性值与文件哈希、构建环境属性(如 Gradle 版本、操作系统、JVM 版本相关声明)等共同哈希生成;输出不参与键计算。
概念解释
相同输入在不同环境若产出不同结果,环境差异必须进入键,否则跨环境复用会出错。Gradle 对部分内置环境维度自动纳入;自定义任务需把影响结果的配置显式声明。
原理流程
- 收集任务类型与实现类哈希。
- 快照所有标注输入的属性与文件。
- 合并已声明的环境维度。
- 计算哈希作为缓存键查找条目。
代码或图示
缓存键 = hash(任务实现类, 输入属性, 输入文件哈希, 环境维度)
常见误区
- 任务依赖未声明的 JDK 版本:跨 JDK 复用缓存可能产出不兼容字节码。
- 生成代码包含绝对路径:环境差异被写进产物,导致缓存命中率下降甚至错误复用。
追问
- 如何让任务忽略某些环境差异?答:只在产物确实不受影响时排除对应维度,需谨慎验证。
- 缓存键冲突如何排查?答:对比两次构建的任务输入快照,找出未声明的差异项。
04.8.3.1-074 Kotlin 增量编译机制是怎样的?
一句话结论
Kotlin 编译在 KGP 配合下做类粒度的增量分析:比较上次编译的类快照与当前源码,只重编受影响的类及其依赖,而非整模块全量编译。
概念解释
编译器记录类之间的依赖关系(源码类、元数据)。修改一个类后,分析哪些类的公共/内部 API 受影响,缩小重编集合。增量效果受改动类型影响:修改 public 签名影响面大于修改方法体。
原理流程
- 上次编译生成类快照与依赖信息。
- 本次扫描变更源码文件。
- 分析受影响类集合(直接变更 + 依赖传递)。
- 只编译集合内类,合并进输出。
代码或图示
修改 A.kt 方法体 → 仅 A 及其直接依赖重编
修改 A.kt public 签名 → 引用 A 的类一并纳入重编
常见误区
- 以为改一行永远只编一个文件:签名变更会沿引用链扩散。
- 关闭增量编译后误判性能:编译参数与配置会影响增量是否启用。
追问
- 增量编译与 Gradle 任务增量是一回事吗?答:前者是 Kotlin 编译器内部类粒度分析,后者是 Gradle 任务级 UP_TO_DATE 判定,两层配合。
- 增量状态损坏怎么办?答:清理模块 build 目录后全量重建一次。
04.8.3.1-075 为什么改一行源码有时触发全量重编译?
一句话结论
当改动触及 public 签名、注解、序列化/生成代码元数据,或增量快照失效、类被广泛引用时,受影响集合扩大到近乎全模块;K2 编译器下增量行为也可能随版本调整(待确认具体边界)。
概念解释
方法体内部改动影响面小;改函数签名、类层次、属性可见性会让所有引用方的类型检查失效。此外增量数据缺失、构建脚本/插件变更、classpath 大改也会使编译器退化为全量。
原理流程
- 识别变更文件与变更类型。
- 沿依赖图扩散受影响类。
- 扩散范围超过阈值或快照不可用时全量编译。
- 输出新快照供下次增量使用。
代码或图示
方法体改动:小范围重编
签名/父类/注解改动:引用链扩散 → 大范围重编
快照缺失或 classpath 变更:全量编译
常见误区
- 把全量重编归咎于机器性能:先分析改动类型与增量状态。
- 频繁切换分支清空 build 目录:丢失增量快照,下次冷构建全量。
追问
- 如何查看本次编译是增量还是全量?答:观察编译任务日志与 KGP 报告(具体输出以版本为准)。
- K2 下增量有何变化?答:K2 重写前端,增量策略随版本演进;行为细节标待确认,以 Kotlin 发布说明为准。
04.8.3.1-076 构建缓存命中后任务如何被跳过?
一句话结论
缓存命中时 Gradle 直接把历史输出产物恢复到任务声明的输出位置,跳过任务动作执行,任务状态标记为 FROM_CACHE。
概念解释
缓存条目保存上次成功执行的输出文件集合。命中后 Gradle 按输出声明还原文件,无需重新编译/生成。前提是任务可缓存、输入哈希一致、输出位置可被覆盖还原。
原理流程
- 计算缓存键并查询本地/远程缓存。
- 命中条目后校验产物清单。
- 还原输出文件到任务输出目录。
- 动作不执行,下游任务按新输出继续。
代码或图示
缓存查询命中 → 还原产物 → 任务状态 FROM_CACHE → 下游消费输出
常见误区
- 缓存命中但产物含本机绝对路径:还原后路径不一致,需在生成阶段规避绝对路径。
- 任务有副作用(写外部服务)却标可缓存:命中后副作用被跳过,外部状态与产物不一致。
追问
- 可缓存任务如何显式开关?答:任务配置
cacheIf/outputs.cacheIf声明命中条件,具体 API 以版本为准。 - 下游任务缓存是否独立命中?答:下游按自身输入快照判定,上游产物哈希是其输入的一部分。
04.8.3.1-077 远程缓存在 CI 上的价值是什么?
一句话结论
远程缓存让流水线各次运行、各模块之间复用历史任务产物,减少重复编译与生成工作;开发机也可拉取 CI 已构建产物,缩短冷构建时间。
概念解释
CI 环境每次通常是干净工作区,本地增量快照不可用;远程缓存跨机器共享输出,命中后跳过编译。收益最大的是编译、打包、代码生成等耗时任务。命中率依赖输入稳定与缓存键可复现。
原理流程
- CI 构建任务执行前查远程缓存。
- 未命中则执行并上传产物条目。
- 后续流水线或开发机按同一输入命中。
- 缓存按策略过期清理。
代码或图示
CI run A 编译产物上传 remote cache
CI run B / 开发机 同输入命中 → 跳过编译
常见误区
- CI 上任务仍读取机器特定路径/端口:缓存键不稳定,命中率低。
- 把含环境密钥的产物上传远程缓存:安全风险,敏感内容不得进缓存条目。
追问
- 并行流水线共享缓存会互相污染吗?答:缓存按只读复用 + 新条目写入,产物不可变;并发写入同键内容应一致。
- 缓存命中率如何度量?答:查看构建扫描中任务 FROM_CACHE 比例,定位未命中任务类型。
04.8.3.1-078 如何让自定义任务具备可缓存性?
一句话结论
完整声明输入输出注解、动作内只读输入并只写输出目录、不访问未声明环境状态,并通过缓存条件允许命中复用;之后两次相同输入构建应命中缓存。
概念解释
可缓存性是任务设计属性,不是开关一打的结果。隐式输入、外部副作用、输出目录混入杂项都会破坏缓存。任务类型抽象属性化后更易满足条件。
原理流程
- 定义任务类,属性用
Property/DirectoryProperty。 - 标注全部输入与输出。
- 动作只消费输入、生成输出。
- 配置缓存条件并实测命中。
代码或图示
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。排查顺序:先看任务是否可缓存,再核对输入声明是否完整,最后检查环境与产物内容。构建扫描可对比两次运行的输入差异。
原理流程
- 确认任务类型支持缓存且未被禁用。
- 对比两次构建输入快照差异。
- 检查产物是否写入路径、时间戳、机器名。
- 核对 Gradle、JDK、插件版本是否变化。
代码或图示
未命中排查:可缓存性 → 输入完整性 → 产物杂质 → 环境维度 → 版本变化
常见误区
- 把未命中当作缓存服务故障:多数情况是任务输入设计问题,先查任务本身。
- 反复清理缓存目录试图解决:治标不治本,输入不稳定依旧未命中。
追问
- 产物里的时间戳如何去掉?答:生成阶段固定可复现输出,避免写入构建时刻。
- 如何对比两次输入?答:用构建扫描或任务输入报告定位差异属性。
04.8.3.1-080 clean 与构建缓存是什么关系?
一句话结论
clean 删除模块 build 目录下的任务输出,但不删除 Gradle 缓存记录;下次构建若无缓存命中会重新生成,命中缓存则从本地/远程还原产物。
概念解释
clean 清的是工作区产物,缓存记录存于 Gradle 缓存目录。删除输出后任务历史记录可能仍在,但产物缺失;增量判定结合缓存,可从缓存还原。两者存储位置与作用不同。
原理流程
- clean 删除 build 目录产物。
- 任务历史记录与缓存条目保留。
- 下次构建输入对比,产物缺失但缓存命中则还原。
- 未命中则重新执行动作。
代码或图示
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 版本。
原理流程
- 确认生产运行 JVM 版本。
- 在 Kotlin 编译选项设置对应 jvmTarget。
- 编译器按目标版本生成 class。
- 运行时加载校验 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 统一配置,避免模块各写一份。
原理流程
- 在编译任务 compilerOptions 中追加参数。
- KGP 把参数传给编译器进程。
- 编译器按参数开启实验特性或调整行为。
- 不兼容参数在编译期报错。
代码或图示
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 版本应一起对齐,第三方库兼容范围以其说明为准。
原理流程
- 目录登记 Kotlin 版本段。
- 插件与 stdlib 条目引用同一版本。
- 编译使用该版本编译器,运行 classpath 含同版本 stdlib。
- 版本错位时检查编译与运行期 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 版本兼容。两者通常配合设置。
原理流程
- 编译参数设置语言版本与 API 版本。
- 解析源码时按 languageVersion 检查语法。
- 生成代码按 apiVersion 选择可用 API 调用。
- 版本过低时新特性/新 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 直接指向本机安装目录,不可移植,团队协作易不一致。
原理流程
- 在 java extension 声明 toolchain 版本。
- Gradle 检测本机匹配 JDK 或按配置下载。
- 编译任务使用该 JDK 工具链。
- 运行/测试任务按同一工具链执行。
代码或图示
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、隐式签名等警告都会中断编译。团队可选择全量开启,或在门禁中单独统计警告数。
原理流程
- 编译选项设置警告升级错误。
- 编译器产生的每条警告按错误处理。
- 存在警告即编译任务失败。
- 修复或显式抑制后才能通过。
代码或图示
compilerOptions {
allWarningsAsErrors.set(true)
}
常见误区
- 升级 Kotlin 后新增警告导致全量阻断:先梳理存量警告再开启门禁。
- 用抑制注解掩盖真问题:抑制需写明原因并评审。
追问
- 只对部分警告报错可行吗?答:按编译器支持的警告级别配置,细粒度规则以版本文档为准。
- 测试代码也要开启吗?答:可按 sourceSet 分别配置,测试代码警告可适当放宽。
04.8.3.1-087 反射与序列化场景需要哪些编译器参数或插件?
一句话结论
kotlinx-serialization 由编译器插件在编译期生成序列化器,无需反射;反射式框架才依赖运行期反射能力。编译器参数层面注意保留元数据与 -opt-in 声明,具体插件按官方文档接入。
概念解释
序列化插件为 @Serializable 类生成 serializer() 实现,避免运行期扫描字段。反射框架读取类元数据时,需确保编译未剥离元数据;Kotlin 默认保留必要元数据,混淆/裁剪场景另需配置。
原理流程
- 应用序列化编译器插件。
- 编译期为标注类生成序列化代码。
- 运行期直接调用生成器,不反射字段。
- 反射框架则在运行期读取类结构。
代码或图示
@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 即不兼容。模块单独编译通过不代表链接运行正常。统一目标版本可避免部署时才暴露问题。
原理流程
- 各模块编译产出对应版本 class。
- 下游 classpath 引用上游产物。
- JVM 加载时校验 class 主版本。
- 版本高于运行时支持则启动/加载失败。
代码或图示
模块 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。
原理流程
- 首次启动 fork 一个 JVM daemon。
- 客户端把构建请求发给 daemon。
- daemon 在进程内完成配置与执行。
- 空闲等待下次调用,超过闲置期回收。
代码或图示
客户端 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 编译守护进程控制。
原理流程
- 查看构建耗时与 GC 占用。
- 调整 jvmargs 堆大小与 GC 参数。
- 重启 daemon 使参数生效。
- 对比多次构建配置与执行耗时。
代码或图示
# 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 时需分别检查两个进程的内存配置。
原理流程
- Gradle daemon 调度编译任务。
- KGP 向 Kotlin 编译守护进程提交编译请求。
- 守护进程复用编译器实例处理增量编译。
- 空闲后按策略回收。
代码或图示
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 并行度与缓存收益抵消。
原理流程
- CI 脚本以无 daemon 模式调用 Gradle。
- 单次构建 JVM 启动后完成配置与执行。
- 构建结束进程退出,不保留状态。
- 下次流水线重新启动,配合远程缓存复用产物。
代码或图示
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。
原理流程
- 一次构建结束后 daemon 进入待命。
- 计时器累计闲置时间。
- 超过阈值触发退出。
- 新构建请求时按需拉起。
代码或图示
构建完成 → 闲置计时 → 超时退出 → 下次请求重新 fork
常见误区
- 长时间不构建仍占内存:确认闲置回收配置与机器进程状态。
- 手动停止 daemon 后担心构建异常:下次自动拉起,不影响增量记录。
追问
- 如何手动停止全部 daemon?答:执行 stop 命令(以当前 Gradle 命令为准)。
- 多版本 Gradle 会起多个 daemon 吗?答:不同版本/参数各有对应 daemon,互不混用。
04.8.3.1-094 平台 BOM 的版本对齐机制是什么?
一句话结论
BOM 在配置中作为平台依赖加入,解析器读取其声明的成员版本约束,为未显式指定版本的成员库选择 BOM 给定版本,实现一组库版本一致。
概念解释
BOM 自身是元数据模块,列出兼容的成员坐标与版本。平台约束优先级高于传递依赖自带版本,但低于模块显式声明的版本。对齐只覆盖 BOM 管理范围内的成员。
原理流程
- 脚本添加
platform(bom)到 configuration。 - 解析器加载 BOM 版本清单。
- 成员库无显式版本时取 BOM 版本。
- 冲突时按平台优先级规则裁决。
代码或图示
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 提供期望版本,强制规则可覆盖选择。
原理流程
- 合并直接与传递依赖图。
- 按模块坐标分组多版本候选。
- 应用冲突策略(默认最高版本)与平台/强制规则。
- 选定版本进入解析结果。
代码或图示
候选:lib 1.2.0、lib 1.5.0(传递)
默认裁决:选择 1.5.0
常见误区
- 以为选最低兼容版本:默认策略是最高,需要固定版本要显式约束。
- 忽略传递依赖版本:冲突常由间接引入,需看全树。
追问
- 想强制锁定某版本怎么做?答:平台约束或 resolutionStrategy 强制版本,记录原因。
- 仲裁结果与预期不符看什么?答:依赖报告展示候选来源与选择理由。
04.8.3.1-096 传递依赖被意外升级或降级如何排查?
一句话结论
通过依赖树定位引入路径与最终版本,区分直接声明、传递引入与平台约束;异常版本通常来自某上游库的元数据或冲突裁决,按路径排除或显式对齐。
概念解释
本地 classpath 的版本是解析结果,不是任一声明点的版本。排查从最终版本反查哪些路径声明了哪些候选,再决定排除、显式版本或升级上游。
原理流程
- 输出目标模块依赖报告。
- 列出所有引入路径与候选版本。
- 确认裁决规则与平台约束来源。
- 针对性排除传递项或显式对齐版本。
代码或图示
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 报编译器版本不匹配。矩阵细节随版本演进,不确定处标待确认并以官方发布说明为准。
原理流程
- 确定目标 Kotlin 版本。
- 查对应兼容的 KSP 版本与 Gradle 最低版本。
- 同步升级目录中的插件、stdlib、KSP 条目。
- 构建验证注解处理与编译链路。
代码或图示
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 配置需区分可缓存目录与生成物目录,并行任务之间隔离工作区。
原理流程
- 流水线拉取代码后恢复 Gradle 缓存目录。
- 构建使用缓存的 wrapper 与任务产物。
- 结束后回写本地缓存并上传远程条目。
- 按策略过期清理缓存体积。
代码或图示
CI 阶段:restore cache → build(命中远程/本地缓存)→ save cache → 上传远程条目
常见误区
- 把模块 build 目录当缓存持久化:生成物应重建,持久化会带来状态污染。
- 缓存键不含分支/版本维度:跨分支错误复用产物。
追问
- wrapper 版本升级后缓存如何失效?答:不同 Gradle 版本发行版目录隔离,自然分开缓存。
- 缓存与并行流水线冲突吗?答:产物不可变、按哈希寻址;写入按条目追加,工作区各自隔离。
04.8.3.1-099 如何用构建扫描或 profile 定位构建慢的环节?
一句话结论
通过构建 profile/扫描报告拆分配置阶段、任务执行、依赖解析与各任务耗时,定位最长任务与配置瓶颈,再针对性优化增量、缓存与并行。
概念解释
慢构建要先量化再优化:配置慢查任务创建与脚本逻辑;执行慢查编译、测试、打包任务;解析慢查仓库与网络。凭感觉加大内存往往无效。
原理流程
- 生成 profile 报告或构建扫描链接。
- 拆分配置、依赖解析、任务执行时间。
- 列出耗时 Top 任务及其状态(重跑/UP_TO_DATE/FROM_CACHE)。
- 按瓶颈类型选择优化手段。
代码或图示
耗时拆解:脚本配置 → 依赖解析 → 任务执行(编译/测试/打包)→ 收尾
常见误区
- 只看总构建时长:不拆分阶段无法判断瓶颈在配置还是执行。
- 优化未命中缓存的任务却不查输入声明:缓存命中率低才是根因。
追问
- 配置阶段耗时高怎么优化?答:减少 create/遍历、下沉 convention plugin、启用配置缓存。
- 执行阶段编译占比高怎么优化?答:核对增量是否生效、编译守护进程内存与模块拆分。
04.8.3.1-100 一次 Kotlin/Gradle 版本升级在工程上应按什么流程落地?
一句话结论
先查兼容矩阵确定配套版本组合,在版本目录统一升级,单模块试点编译与测试,再全量回归构建、生成代码链路与 CI 缓存策略,最后观察警告与性能。
概念解释
升级涉及编译器、标准库、KSP/编译器插件、Gradle 与静态分析工具的配套。直接全量跳版本容易在生成代码、字节码兼容处出问题。分步升级可回滚、定位影响面。
原理流程
- 查 Kotlin/Gradle/KSP/插件兼容矩阵,确定目标组合。
- 目录升级版本段,本地试点模块编译。
- 修复新警告与 API 迁移点。
- 全量构建 + 测试 + 打包,验证 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)
- [ ] 补充团队内部仓库镜像与插件门户代理的实际配置示例
- [ ] 收集本工程多模块依赖树样本,用于版本对齐与冲突排查题的落地对照