第 5 章 工具链与工程骨架:把实验环境固化成基础设施
本章目标
- 搭一个能撑住全书 45 章实验的 Gradle 9 多模块工程;
- 彻底搞清楚
jvmToolchain/jvmTarget/--release三者的区别(90% 的人搞混);- 建立四套工作流:反编译对照、字节码检查、JMH 基准、静态检查;
- 掌握 Gradle 构建性能优化的正确姿势(增量、并行、配置缓存、KSP 替代 kapt)。
本章偏工程实操,如果你已经熟悉 Gradle,可以只读 5.2、5.5、5.8、5.12 四节。
5.1 Gradle 9 + Kotlin DSL:为什么必须用 .kts
Gradle 9.0(2025)的重大变化:
| 变化 | 影响 |
|---|---|
| 最低运行版本 Java 17 | 守护进程需 JDK 17+;构建目标仍可以是 8/11/17/21/25/27 |
| Kotlin DSL 内嵌 Kotlin 2.2.x 运行时 | build.gradle.kts 里可以用 Kotlin 2.2 的语法特性 |
| 移除大量 8.x 中已废弃的 API | 老的 build.gradle(Groovy)脚本可能需要改 |
| 配置缓存成为推荐默认路径 | 大幅缩短重复构建时间 |
provider API 全面化 | 避免在配置期求值(配置缓存的前提) |
| Isolated Projects(孵化中) | 多模块并行配置的下一代方案 |
📌 Gradle 9.8.1(2026-10-07) 是本书基线版本。Kotlin Gradle Plugin(KGP)2.4.0 官方兼容到 Gradle 9.5.0,2.3.0 兼容 Gradle 9.0。
🚀 为什么坚持 Kotlin DSL:
- 类型安全:IDE 能补全、能报错;Groovy DSL 的拼写错误要到运行时才炸;
- 重构友好:改名、提取变量、跨模块复用逻辑都是普通 Kotlin 代码;
- 一致性:团队既写 Kotlin 又写构建脚本,认知负担小;
- 本书要用它做实验:第 47 章会演示如何用 Gradle 的
precompiled script plugins把构建约定收敛成一个模块。
⚠️ 代价:.kts 的首次配置比 Groovy 慢(要编译脚本);用配置缓存可以基本消除。
5.2 jvmToolchain vs jvmTarget vs --release:必须搞清的三件事
这是 Kotlin/Java 混编工程最高频的构建错误来源。三者含义完全不同:
| 概念 | 管什么 | 配置位置 | 错误配置的症状 |
|---|---|---|---|
| Toolchain(工具链) | 用哪个 JDK 来执行编译 | kotlin { jvmToolchain(27) } | 用了本机 JDK 8,编译不了 27 的 API |
jvmTarget | 生成什么版本的字节码(class major version) | compilerOptions { jvmTarget = JVM_27 } | 生成 71 的 class,但运行环境是 JDK 21 → UnsupportedClassVersionError |
--release | javac 编译时能引用哪个版本的 API | options.release = 27 | 编译时用了 JDK 28 的 API,运行时在 27 上 NoSuchMethodError |
正确的完整配置
// build.gradle.kts(模块级)
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
kotlin {
// ① 用 JDK 27 编译(Gradle 会自动下载/定位,见下方 Foojay 配置)
jvmToolchain(27)
compilerOptions {
// ② 生成 JDK 27 的字节码
jvmTarget.set(JvmTarget.JVM_27)
// ③ 语言/API 版本控制(可选但推荐)
languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4)
apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4)
freeCompilerArgs.addAll(
"-Xjsr305=strict",
"-progressive",
"-Xreturn-value-checker=check", // Kotlin 2.3+,实验
)
allWarningsAsErrors.set(false)
}
}
// ④ Java 侧同步:release 同时约束字节码版本和 API
java {
toolchain { languageVersion = JavaLanguageVersion.of(27) }
}
tasks.withType<JavaCompile>().configureEach {
options.release.set(27)
options.encoding = "UTF-8"
}
让 Gradle 自动下载 JDK(Foojay Resolver)
// settings.gradle.kts
plugins {
id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}
这样在任何机器上(包括 CI)执行 ./gradlew build,Gradle 会自动获取所需的 JDK,不依赖 JAVA_HOME。
交叉编译场景(生产常见)
目标运行环境是 JDK 21,但开发机装的是 JDK 27:
kotlin {
jvmToolchain(27) // 用 27 编译(能享受新编译器的 bug 修复)
compilerOptions { jvmTarget.set(JvmTarget.JVM_21) } // 但产出 21 的字节码
}
tasks.withType<JavaCompile>().configureEach {
options.release.set(21) // ⚠️ 关键:只允许用 JDK 21 的 API
}
⚠️ 如果只改 jvmTarget 不改 release,你的代码可能引用 JDK 27 才有的 API(如 java.util.UUID.randomUUID() 的某个新重载),编译通过但在 JDK 21 上运行时 NoSuchMethodError。这是最隐蔽的一类构建错误。
📌 Kotlin 2.4.0 起,Maven 构建会自动对齐 Java 与 JVM target 版本(并支持 Maven Toolchains)。Gradle 目前仍需手动保证一致。
🧪 实验 5-1:验证字节码版本
./gradlew :ch01-illusions:compileKotlin
xxd ch01-illusions/build/classes/kotlin/main/book/ch01/IllusionsKt.class | head -1
# cafe babe 0000 0045 → 0x45 = 69 = JDK 25
# cafe babe 0000 0047 → 0x47 = 71 = JDK 27
5.3 Version Catalog:告别硬编码版本号
gradle/libs.versions.toml(前面 02-setup 已给过,这里补充最佳实践):
[versions]
kotlin = "2.4.21"
coroutines = "1.11.0"
ktor = "3.6.0"
springBoot = "4.0.7"
junit = "5.13.0"
mockk = "1.14.5"
kotest = "6.0.0"
jmh = "1.37"
detekt = "1.23.8"
ksp = "2.4.21-2.0.4" # 📌 KSP 版本号 = Kotlin 版本 + "-" + KSP 版本
[libraries]
# 分组命名,IDE 补全友好
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }
kotlin-reflect = { module = "org.jetbrains.kotlin:kotlin-reflect", version.ref = "kotlin" }
kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
coroutines-jdk8 = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-jdk8", version.ref = "coroutines" }
coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "coroutines" }
coroutines-slf4j = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-slf4j", version.ref = "coroutines" }
atomicfu = { module = "org.jetbrains.kotlinx:atomicfu", version = "0.29.0" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
junit-launcher = { module = "org.junit.platform:junit-platform-launcher", version = "1.13.0" }
mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
kotest-runner = { module = "io.kotest:kotest-runner-junit5", version.ref = "kotest" }
kotest-assertions = { module = "io.kotest:kotest-assertions-core", version.ref = "kotest" }
turbine = { module = "app.cash.turbine:turbine", version = "1.2.0" }
jmh-core = { module = "org.openjdk.jmh:jmh-core", version.ref = "jmh" }
jmh-generator = { module = "org.openjdk.jmh:jmh-generator-annprocess", version.ref = "jmh" }
logback = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
jol-core = { module = "org.openjdk.jol:jol-core", version = "0.17" } # 对象布局分析,第 27 章用
[bundles]
test = ["junit-jupiter", "kotlin-test", "mockk", "kotest-assertions"]
coroutines = ["coroutines-core", "coroutines-jdk8"]
bench = ["jmh-core", "jmh-generator"]
[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
kotlin-allopen = { id = "org.jetbrains.kotlin.plugin.allopen", version.ref = "kotlin" }
kotlin-noarg = { id = "org.jetbrains.kotlin.plugin.noarg", version.ref = "kotlin" }
detekt = { id = "io.gitlab.arturbosch.detekt", version.ref = "detekt" }
jmh = { id = "me.champeau.jmh", version = "0.7.3" }
binaryCompat = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version = "0.18.0" }
使用:
dependencies {
implementation(libs.bundles.coroutines) // 一次引入一组
testImplementation(libs.bundles.test)
testRuntimeOnly(libs.junit.launcher)
}
🚀 [bundles] 是多模块工程的救星:所有模块的测试依赖一行搞定,升级只改 toml。
5.4 全书工程骨架(可直接复制)
kotlin-jvm-book/
├── settings.gradle.kts
├── gradle.properties
├── build.gradle.kts
├── gradle/libs.versions.toml
├── build-logic/ ← 构建约定(precompiled script plugins)
│ ├── settings.gradle.kts
│ └── src/main/kotlin/
│ ├── book.kotlin-common.gradle.kts
│ └── book.jvm-experiment.gradle.kts
├── sandbox/ ← 随手实验模块
├── bench/ ← JMH 基准模块
├── ch01-illusions/
├── ch04-journey/
├── ch07-nullsafety/
├── ch20-bytecode/
├── ch27-memory/
├── ch37-coroutines/
└── ...(每章一个模块)
gradle.properties
# ── 性能 ─────────────────────────────────────────
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g -XX:+UseParallelGC \
-Dfile.encoding=UTF-8
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true
org.gradle.configuration-cache.problems=warn
org.gradle.daemon=true
org.gradle.vfs.watch=true
# ── Kotlin ───────────────────────────────────────
kotlin.code.style=official
kotlin.incremental=true
kotlin.incremental.useClasspathSnapshot=true
kotlin.build.report.output=file
kotlin.build.report.file=build/kotlin-build-report
# ── KSP(替代 kapt)──────────────────────────────
ksp.incremental=true
ksp.useKSP2=true
# 📌 kapt 已不推荐;若必须使用,务必开启 worker 与增量:
# kapt.use.worker.api=true
# kapt.incremental.apt=true
# kapt.include.compile.classpath=false
build-logic/src/main/kotlin/book.kotlin-common.gradle.kts
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
plugins {
id("org.jetbrains.kotlin.jvm")
}
kotlin {
jvmToolchain(27)
compilerOptions {
jvmTarget.set(JvmTarget.JVM_27)
languageVersion.set(KotlinVersion.KOTLIN_2_4)
apiVersion.set(KotlinVersion.KOTLIN_2_4)
freeCompilerArgs.addAll("-Xjsr305=strict", "-progressive")
javaParameters.set(true) // 保留参数名(反射/Spring/序列化需要)
}
}
tasks.withType<JavaCompile>().configureEach {
options.release.set(27)
options.encoding = "UTF-8"
}
tasks.withType<Test>().configureEach {
useJUnitPlatform()
// 反射类库在 JDK 17+ 需要开放内部包
jvmArgs(
"--add-opens=java.base/java.lang=ALL-UNNAMED",
"--add-opens=java.base/java.util=ALL-UNNAMED",
"--add-opens=java.base/java.lang.reflect=ALL-UNNAMED",
)
testLogging {
events("passed", "skipped", "failed")
showStandardStreams = true
exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
}
}
dependencies {
val libs = the<org.gradle.accessors.dm.LibrariesForLibs>()
"implementation"(libs.kotlin.stdlib)
"testImplementation"(libs.bundles.test)
"testRuntimeOnly"(libs.junit.launcher)
}
一个章节模块
// ch20-bytecode/build.gradle.kts
plugins {
id("book.kotlin-common")
application
}
dependencies {
implementation(libs.kotlin.reflect) // 第 19/20 章需要
implementation(libs.jol.core) // 第 27 章对象布局
}
application {
mainClass.set(provider {
// 用 -Pmain=xxx 指定入口,方便反复跑不同实验
project.findProperty("main")?.toString() ?: "book.ch20.BytecodeDemoKt"
})
applicationDefaultJvmArgs = listOf(
"-XX:+UnlockDiagnosticVMOptions",
// "-XX:+PrintCompilation",
// "-XX:+PrintInlining",
)
}
./gradlew :ch20-bytecode:run -Pmain=book.ch20.DataClassDemoKt
./gradlew :ch20-bytecode:run -Pmain=book.ch20.InlineDemoKt
🚀 这个 -Pmain 技巧贯穿全书:每章的每个实验都是一个独立的 main 函数,用属性切换,无需改构建脚本。
5.5 KSP vs kapt:2026 年必须完成的一次迁移
kapt 的工作原理(为什么慢)
Kotlin 源码 ──► 生成 Java stub(.java 骨架,只有签名没有实现)
│
▼
javac 运行注解处理器(APT)
│
▼
生成 Java/Kotlin 源码
│
▼
再编译一遍 Kotlin + Java
慢的根源:需要把整个 Kotlin 代码库"翻译"成 Java stub,然后跑完整的 javac。大型项目上 kapt 可占构建时间的 30–50%。
KSP 的工作原理
Kotlin 源码 ──► K2 前端分析 ──► KSP 处理器直接读 Kotlin 符号(KSClass/KSFunction/KSProperty)
│
▼
生成源码(增量!只处理变化的文件)
快的原因:不生成 stub、不跑 javac、直接工作在 Kotlin 的符号模型上、支持增量处理。官方数据:比 kapt 快最多 2 倍(实际项目常见 3–5 倍)。
📌 KSP2(ksp.useKSP2=true)基于 K2 编译器重写,2024 年起可用,2026 年已是主流。它进一步提升了增量精度与多平台支持。
迁移步骤
plugins {
alias(libs.plugins.kotlin.jvm)
alias(libs.plugins.kotlin.ksp) // 替换 kotlin-kapt
}
dependencies {
// kapt("com.squareup.moshi:moshi-kotlin-codegen:1.15.x") ← 删掉
ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.x") ← 改成 ksp
}
ksp {
arg("moshi.generated", "javax.annotation.Generated")
// 增量与日志
arg("room.schemaLocation", "$projectDir/schemas")
}
📌 2026 年主流库的 KSP 支持状况:Room ✅、Moshi ✅、Hilt/Dagger ✅(有 KSP 支持但部分场景仍建议 kapt)、Koin ✅、kotlinx.serialization ✅、MapStruct ✅(mapstruct-kotlin)、AutoValue ✅、Glide ✅、Micronaut ✅、Quarkus ✅。
⚠️ 如果某个库只有 kapt 版本:可以 kapt 和 KSP 共存,但会失去大部分性能收益。此时应评估是否值得替换该库。
5.6 静态检查:Detekt + Spotless
Detekt
plugins {
alias(libs.plugins.detekt)
}
detekt {
buildUponDefaultConfig = true
allRules = true
config.setFrom("$rootDir/config/detekt/detekt.yml")
baseline = file("$rootDir/config/detekt/baseline.xml") // 存量代码豁免
parallel = true
}
dependencies {
detektPlugins("io.gitlab.arturbosch.detekt:detekt-formatting:1.23.8")
}
config/detekt/detekt.yml(本书采用的关键规则):
complexity:
LongMethod: { active: true, threshold: 80 }
LongParameterList: { active: true, functionThreshold: 6, constructorThreshold: 8 }
CyclomaticComplexMethod: { active: true, threshold: 15 }
TooManyFunctions: { active: true, thresholdInClasses: 20 }
style:
MagicNumber: { active: true, ignoreNamedArgument: true, ignoreEnums: true }
ReturnCount: { active: true, max: 3 }
MaxLineLength: { active: true, maxLineLength: 120 }
UnusedPrivateMember: { active: true }
WildcardImport: { active: true }
# 本书强调的 JVM 相关规则:
ForbiddenMethodCall:
active: true
methods:
- reason: "禁止 !! 之外的强制非空;用 requireNotNull/checkNotNull 表达意图"
value: ['kotlin.io.println'] # 示例:生产代码禁止 println
- reason: "协程中禁止 runBlocking(会阻塞线程,可能死锁)"
value: ['kotlinx.coroutines.runBlocking']
potential-bugs:
UnsafeCallOnNullableType: { active: true } # ← 禁止 !!
LateinitUsage: { active: true } # ← 警告 lateinit
CastToNullableType: { active: true }
coroutines:
GlobalCoroutineUsage: { active: true } # ← 禁止 GlobalScope
RedundantSuspendModifier: { active: true }
SleepInsteadOfDelay: { active: true }
SuspendFunWithCoroutineScopeReceiver: { active: true }
🚀 GlobalCoroutineUsage 与 UnsafeCallOnNullableType 这两条规则值得所有 Kotlin 项目开启——它们分别拦截了协程泄漏和 NPE 两大生产事故源(第 38/42 章)。
Spotless(格式化)
plugins { id("com.diffplug.spotless") version "7.0.0" }
spotless {
kotlin {
target("**/*.kt")
ktlint("1.5.0").editorConfigPath("$rootDir/.editorconfig")
licenseHeaderFile("$rootDir/config/license-header.txt")
trimTrailingWhitespace()
endWithNewline()
}
kotlinGradle {
target("**/*.gradle.kts")
ktlint("1.5.0")
}
}
5.7 二进制兼容性验证(库项目必配)
📌 Kotlin 2.2.0 起,KGP 内置了二进制兼容验证能力;也可以继续用独立插件:
plugins {
id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.18.0"
}
apiValidation {
ignoredPackages.add("book.internal")
// Kotlin Multiplatform 项目:
// targets.addAll("jvm", "js")
}
./gradlew apiDump # 生成 api/*.api 文件(公共 API 快照)
./gradlew apiCheck # CI 中校验:公共 API 是否被意外破坏
生成的 .api 文件长这样:
public final class book/ch20/Point {
public fun <init> (II)V
public final fun component1 ()I
public final fun component2 ()I
public final fun copy (II)Lbook/ch20/Point;
public static fun copy$default (Lbook/ch20/Point;IIILjava/lang/Object;)Lbook/ch20/Point;
public fun equals (Ljava/lang/Object;)Z
public final fun getX ()I
public final fun getY ()I
public fun hashCode ()I
public final fun norm ()D
public fun toString ()Ljava/lang/String;
}
⚠️ 为什么这对 Kotlin 尤其重要:
inline函数体是公开 API 的一部分——改函数体,调用方不重编译就不生效。apiCheck能捕捉签名变化,但捕捉不到 inline 函数体的语义变化,需要额外的评审规则;internal编译成 public + 名称混淆,模块名变化会破坏兼容;- 默认参数:加一个默认参数看似兼容,实际会改变
$default合成方法的签名(位掩码参数个数变化)→ 二进制不兼容!这是 Kotlin 库最隐蔽的破坏性变更。
🔬 默认参数的二进制陷阱演示:
// v1
fun greet(name: String, greeting: String = "Hi") {}
// 生成:greet(Ljava/lang/String;Ljava/lang/String;)V
// greet$default(Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)V
// v2:加一个默认参数
fun greet(name: String, greeting: String = "Hi", punct: String = "!") {}
// 生成:greet(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V ← 签名变了!
// greet$default(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)V
老版本编译的调用方调用 greet(String, String) → NoSuchMethodError。
📌 Kotlin 2.4.0 的 @IntroducedAt 注解(实验) 正是为了解决这类问题:它能生成基于版本的重载,让新参数不破坏旧签名。这是库作者应该关注的新特性。
5.8 JMH 基准测试模块(全书性能实验的基础)
// bench/build.gradle.kts
plugins {
id("book.kotlin-common")
id("me.champeau.jmh") version "0.7.3"
}
dependencies {
jmh(libs.bundles.bench)
}
jmh {
jmhVersion.set("1.37")
warmupIterations.set(3)
iterations.set(5)
fork.set(2)
profilers.set(listOf("gc")) // 同时输出 GC 指标
resultFormat.set("TEXT")
includes.set(listOf(".*"))
// 关键:JMH 用的 JVM 参数
jvmArgs.set(listOf(
"-Xms2g", "-Xmx2g",
"-XX:+UseG1GC",
// 对比实验时切换:
// "-XX:+UseZGC",
// "-XX:-UseCompactObjectHeaders",
))
}
// bench/src/jmh/kotlin/book/bench/BoxingBench.kt
package book.bench
import org.openjdk.jmh.annotations.*
import java.util.concurrent.TimeUnit
@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.NANOSECONDS)
@State(Scope.Thread)
@Warmup(iterations = 3, time = 1)
@Measurement(iterations = 5, time = 1)
@Fork(2)
open class BoxingBench {
private val size = 1_000_000
private lateinit var boxed: List<Int>
private lateinit var primitive: IntArray
@Setup
fun setup() {
boxed = (0 until size).toList()
primitive = IntArray(size) { it }
}
@Benchmark
fun sumBoxed(): Long {
var s = 0L
for (v in boxed) s += v
return s
}
@Benchmark
fun sumPrimitive(): Long {
var s = 0L
for (v in primitive) s += v
return s
}
@Benchmark
fun sumSequence(): Long = boxed.asSequence().sumOf { it.toLong() }
}
./gradlew :bench:jmh
⚠️ JMH 的三个必知陷阱:
- 死代码消除(DCE):如果基准方法的结果没被使用,JIT 会把整个计算删掉。JMH 用
Blackhole或返回值消费来解决——必须return结果或用@State保存。 - 常量折叠:如果输入是编译期常量,计算会在编译期完成。用
@Setup准备数据 +@State字段。 - 预热不足:JIT 需要时间。
fork=2, warmup=3, iterations=5是最低配置;重要结论要用fork=5+。
🚀 额外工具:-prof gc(分配率)、-prof async(async-profiler 集成)、-prof perfasm(机器码级热点)、-prof stack。第 35 章会系统讲。
5.9 反编译 / 字节码工作流(本书最常用的三招)
招式一:IDEA 的 Kotlin Bytecode + Decompile
Tools → Kotlin → Show Kotlin Bytecode → [Decompile]
左边是 Kotlin 源码,中间是字节码(javap 风格),右边是反编译回 Java。
🔬 这是理解 Kotlin 语义的最快路径。当你不确定"data class 的 equals 到底比了什么"、"internal 编译成什么"、"扩展函数的接收者放哪"时,Decompile 一下就有答案。
招式二:命令行 javap
# 快速看签名
./gradlew :ch20-bytecode:compileKotlin
javap -p ch20-bytecode/build/classes/kotlin/main/book/ch20/*.class
# 完整信息(含常量池、属性、行号表)
javap -v -p -c ch20-bytecode/build/classes/kotlin/main/book/ch20/Point.class > point.txt
# 反汇编 JDK 自己的类
javap -c -p --module java.base java.util.concurrent.ConcurrentHashMap | less
# 只看方法签名(描述符)
javap -s -p ch20-bytecode/build/classes/kotlin/main/book/ch20/JourneyKt.class
🚀 写个别名,节省大量时间:
# ~/.bashrc
alias jdc='f(){ javap -c -p -v "$1" | less -R; }; f'
alias jds='f(){ javap -p "$1"; }; f'
招式三:Gradle 任务自动化
// ch20-bytecode/build.gradle.kts
tasks.register<Exec>("disassemble") {
group = "book"
description = "反汇编本章所有 class 到 build/disasm/"
dependsOn("compileKotlin")
doFirst {
val outDir = layout.buildDirectory.dir("disasm").get().asFile.apply { mkdirs() }
fileTree(layout.buildDirectory.dir("classes/kotlin/main"))
.matching { include("**/*.class") }
.forEach { f ->
val target = outDir.resolve(f.nameWithoutExtension + ".javap.txt")
exec {
commandLine("javap", "-c", "-p", "-v", f.absolutePath)
standardOutput = target.outputStream()
}
}
}
}
./gradlew :ch20-bytecode:disassemble
ls ch20-bytecode/build/disasm/
5.10 构建性能优化清单
按投入产出比排序:
| # | 措施 | 预期收益 | 备注 |
|---|---|---|---|
| 1 | 配置缓存 org.gradle.configuration-cache=true | 配置阶段 -70%~-95% | Gradle 9 推荐;需插件兼容 |
| 2 | 构建缓存 org.gradle.caching=true(+ 远端缓存) | 重复构建 -80% | CI 上收益最大 |
| 3 | 并行 org.gradle.parallel=true | 多模块 -30%~-60% | 需模块间无隐式依赖 |
| 4 | kapt → KSP | 注解处理 -50%~-80% | 见 5.5 |
| 5 | Kotlin 增量编译(默认开启)+ classpath snapshot | 增量构建 -60% | kotlin.incremental.useClasspathSnapshot=true |
| 6 | 文件系统监视 org.gradle.vfs.watch=true | 增量 -10%~-30% | |
| 7 | 给 Gradle 守护进程足够内存 -Xmx4g -XX:MaxMetaspaceSize=1g | 避免频繁 GC/OOM | Kotlin 编译很吃内存 |
| 8 | 守护进程用 Parallel GC(而非默认 G1) | 编译吞吐略升 | 短生命周期、吞吐优先场景 |
| 9 | 减少模块数量 / 合并小模块 | 配置与调度开销下降 | 与增量编译收益权衡 |
| 10 | 避免在配置期做重活(读文件、跑命令) | 配置阶段大幅下降 | 用 Provider 惰性求值 |
| 11 | kotlin.compiler.execution.strategy=in-process | 小项目 -20% | 大项目反而可能 OOM,需实测 |
| 12 | JDK 21+ 跑 Gradle | 编译器本身更快 | 与 jvmTarget 无关 |
🧪 实验 5-2:量化你的构建
# 生成构建报告
./gradlew build --profile --scan
# Kotlin 编译报告(gradle.properties 已配 kotlin.build.report.output=file)
cat build/kotlin-build-report/*.txt
# 找出最慢的任务
./gradlew build --dry-run
🚀 --scan(Develocity Build Scan) 是定位构建瓶颈的终极工具,免费版够用。看 "Performance" 标签页里的任务耗时瀑布图。
5.11 Maven 对照(简要)
如果你必须用 Maven:
<properties>
<kotlin.version>2.4.21</kotlin.version>
<java.version>27</java.version>
<!-- 📌 Kotlin 2.4.0 起会自动对齐 maven.compiler.release 与 kotlin jvmTarget -->
<maven.compiler.release>27</maven.compiler.release>
</properties>
<build>
<sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory>
<testSourceDirectory>${project.basedir}/src/test/kotlin</testSourceDirectory>
<plugins>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${kotlin.version}</version>
<configuration>
<args>
<arg>-Xjsr305=strict</arg>
<arg>-progressive</arg>
</args>
<compilerPlugins>
<plugin>spring</plugin>
<plugin>jpa</plugin>
</compilerPlugins>
</configuration>
<executions>
<!-- ⚠️ 关键:Kotlin 必须先于 Java 编译 -->
<execution><id>compile</id> <phase>compile</phase> <goals><goal>compile</goal></goals></execution>
<execution><id>test-compile</id><phase>test-compile</phase> <goals><goal>test-compile</goal></goals></execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<!-- Java 编译放在 Kotlin 之后 -->
<execution><id>default-compile</id> <phase>none</phase></execution>
<execution><id>default-testCompile</id><phase>none</phase></execution>
<execution><id>java-compile</id> <phase>compile</phase> <goals><goal>compile</goal></goals></execution>
<execution><id>java-test-compile</id><phase>test-compile</phase><goals><goal>testCompile</goal></goals></execution>
</executions>
</plugin>
</plugins>
</build>
📌 Kotlin 2.3.20 简化了 Maven 配置(自动配置 source roots),2.4.0 增加了 Maven Toolchains 支持。新项目仍强烈推荐 Gradle:KSP、Compose、KMP 的支持都以 Gradle 为一等公民。
5.12 本书的代码组织约定
为了让 45 章的实验互不干扰且随时可跑,全书遵循:
// 每个实验是一个独立的顶层 main,放在 chNN-xxx 模块的对应包里
package book.ch20
/** 实验 20-3:data class 的 equals 只比较主构造器属性 */
fun main() {
// ... 实验代码
// 期望输出写在注释里,方便对照
}
# 运行任意实验
./gradlew :ch20-bytecode:run -Pmain=book.ch20.Experiment20_3Kt
# 带 JVM 参数运行(对比实验)
./gradlew :ch27-memory:run -Pmain=book.ch27.ObjectHeaderKt \
-PjvmArgs="-XX:+UseCompactObjectHeaders"
对应的 run 任务配置:
tasks.named<JavaExec>("run") {
(project.findProperty("jvmArgs") as? String)?.let { jvmArgs = it.split(" ") }
}
🚀 建议你自己也这么组织:一个 experiments/ 模块,每个"我以为我懂"的知识点都写成一个可运行的 main。能跑起来的认知才是你的认知。
5.13 本章小结
jvmToolchain(用哪个 JDK 编译)、jvmTarget(产出什么版本字节码)、options.release(能引用什么 API)是三件不同的事,必须同时配置正确。这是混编工程头号构建错误源。- Version Catalog + build-logic(precompiled script plugins) 是多模块工程的标准答案:版本集中管理、构建约定复用。
- kapt → KSP 是 2026 年必须完成的迁移,收益 2–5 倍构建速度。KSP2 基于 K2,增量更准。
- Detekt 的两条规则值得强制开启:
GlobalCoroutineUsage(协程泄漏)与UnsafeCallOnNullableType(!!)。 - 二进制兼容验证对 Kotlin 库尤其关键,因为加默认参数会破坏二进制兼容(
$default签名变化),这是 Java 没有的陷阱。 - JMH 是性能结论的唯一可信来源。手写
System.nanoTime()循环测出来的数字基本没有参考价值(DCE、常量折叠、预热不足)。 - 反编译工作流(IDEA Decompile + javap)是理解 Kotlin 语义的最快路径,全书都会用到。
5.14 练习题
5-1. 你的项目 jvmTarget = 21,jvmToolchain(27),没有配置 options.release。代码里用了 java.util.HexFormat.ofDelimiter()(JDK 22 引入的方法)。构建成功了吗?运行时会怎样?
答案要点
构建成功(用 JDK 27 的类库编译,能看到 JDK 22 的 API),产出 JDK 21 版本字节码。
运行时:
- 在 JDK 27 上跑 → 正常;
- 在 JDK 21 上跑 →
NoSuchMethodError(方法不存在于 21 的HexFormat)。
修复:加 options.release.set(21),让编译期就只能看到 JDK 21 的 API,构建阶段就会报错。
延伸:Kotlin 侧可用 Animal Sniffer 插件做类似的 API 签名检查(ru.vyarus.animalsniffer),或使用 --release 等价的 Kotlin 支持。
5-2. 为什么给一个已有的 public 函数新增一个带默认值的参数是二进制不兼容的变更?如何缓解?
答案要点
原因:Kotlin 的默认参数不生成重载。fun f(a: Int, b: Int = 1) 编译为:
f(II)V(真实方法,签名随参数列表变化)f$default(IILjava/lang/Object;)V(合成方法,含位掩码参数)
新增参数 c: Int = 2 后:
f(III)V← 原f(II)V消失了f$default(IIILjava/lang/Object;)V← 签名也变了
老版本编译的调用方在链接时找不到 f(II)V → NoSuchMethodError。
缓解方案:
- 保留旧签名:新增重载而非修改原函数(手动写
fun f(a: Int, b: Int) = f(a, b, 2)); - 📌 Kotlin 2.4.0 的
@IntroducedAt(实验):自动生成基于版本的重载; @JvmOverloads:生成 Java 风格的重载(对 Java 调用方友好,但对 Kotlin 调用方仍有问题);- 库层面:用二进制兼容验证器在 CI 拦截,遵循语义化版本(这类变更应升 minor/major)。
5-3.(🧪 动手)配置一个 JMH 基准,测量 List<Int> 与 IntArray 在求和场景下的差异,并用 -prof gc 输出分配率。解释你观察到的结果。
答案要点
预期结果(量级):
IntArray求和:约 0.3–0.5 ms / 百万元素;分配率接近 0;List<Int>求和:约 2–5 ms / 百万元素;分配来自装箱(如果列表是运行期构建的)与迭代器。
原因:
- 内存布局:
int[]连续存储 4 字节/元素;List<Integer>是Object[](4 或 8 字节引用)+ 每个Integer对象(📌 JDK 27 紧凑头下 16 字节)→ 缓存局部性差 3–5 倍; - 解引用:
List每次访问需要两次内存访问(数组 → 对象 → 字段); - 向量化:
int[]的循环 C2 可以做 SIMD 自动向量化;List<Integer>不行; - 边界检查:
Object[]每次访问都有 null/边界检查(虽然通常被优化掉)。
结论:数值密集场景必须用原生数组。这也是 Valhalla(value class)要解决的问题——让 List<int> 也能扁平化存储。
5-4. 配置缓存(configuration cache)和构建缓存(build cache)有什么区别?
答案要点
- 配置缓存:缓存 Gradle 配置阶段的结果(项目模型、任务图)。跳过
settings.gradle.kts/build.gradle.kts的求值。对多模块大项目收益巨大(配置阶段可能占数十秒)。要求构建脚本不在配置期做 I/O、不使用Task.project等。 - 构建缓存:缓存 任务执行的输出(以任务输入哈希为 key)。命中时直接从缓存恢复输出,跳过执行。可以是本地目录或远端 HTTP 缓存(CI 共享)。
两者正交,应同时开启。
5.15 面试题精选
Q1:Gradle 的 implementation 和 api 有什么区别?为什么要区分?
答题框架:
api:依赖暴露给消费者(编译期传递)。修改该依赖会导致下游重新编译。implementation:依赖仅在本模块内部可见(运行期传递,编译期不传递)。- 收益:减少不必要的重编译(
implementation的变更不会触发下游模块重新编译),加快增量构建;更好的封装。 - 准则:默认用
implementation;只有当你的 public API 签名中出现了该依赖的类型时,才用api。 - 加分:提到
compileOnly(编译期可见,运行期不提供,如注解处理器、Lombok)、runtimeOnly(如 JDBC 驱动)、testImplementation。
Q2:Kotlin 项目的构建为什么比 Java 慢?你会怎么优化?
答题框架:
- 原因:Kotlin 编译器本身更复杂(FIR 前端 + IR 后端 + 多趟降低);kapt 需要生成 Java stub 并跑 javac;增量编译的粒度与快照机制开销;stdlib 依赖解析。
- 优化清单(按 ROI):kapt→KSP;配置缓存;构建缓存(本地+远端);并行;增量编译 + classpath snapshot;守护进程内存调优;文件系统监视;合理拆分模块(增量友好但配置开销增加,需权衡);
in-process编译策略(小项目);用更高版本 JDK 跑 Gradle。 - 度量:
--scan/--profile/kotlin.build.report。先度量再优化。
Q3:你怎么保证一个 Kotlin 库的向后兼容?
答题框架:
- 工具:
binary-compatibility-validator(📌 KGP 2.2+ 内置能力)+apiDump/apiCheck进 CI; explicitApi()模式:强制 public 声明显式可见性与返回类型;- 规则清单:
- 不给已有 public 函数加参数(即使有默认值)→ 破坏
$default签名; - 不改
internal成员所在的模块名 → 名称混淆变化; inline函数体变更视为 API 变更(调用方需重编译);data class加参数会改变copy/componentN签名;sealed层级新增子类对下游when是源码兼容但可能触发穷尽性错误;enum新增条目同理(且entries顺序变化影响序列化);
- 不给已有 public 函数加参数(即使有默认值)→ 破坏
- 流程:语义化版本 + 变更日志 +
@Deprecated(level=WARNING)→ERROR→HIDDEN的三阶段移除。
第一篇完。
下一篇预告:第二篇《Kotlin 语言核心》(第 6–19 章)。我们从类型系统开始——Int 到底是什么?为什么 Int? 会装箱?为什么 IntArray 不会?为什么 Kotlin 说"一切皆对象"却又提供 IntArray?这些问题的答案,会把 Kotlin 语言设计与 JVM 内存模型第一次真正连起来。