Kotlin与Java虚拟机五:工具链

48 阅读9分钟

第 5 章 工具链与工程骨架:把实验环境固化成基础设施

本章目标

  1. 搭一个能撑住全书 45 章实验的 Gradle 9 多模块工程;
  2. 彻底搞清楚 jvmToolchain / jvmTarget / --release 三者的区别(90% 的人搞混);
  3. 建立四套工作流:反编译对照、字节码检查、JMH 基准、静态检查;
  4. 掌握 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:

  1. 类型安全:IDE 能补全、能报错;Groovy DSL 的拼写错误要到运行时才炸;
  2. 重构友好:改名、提取变量、跨模块复用逻辑都是普通 Kotlin 代码;
  3. 一致性:团队既写 Kotlin 又写构建脚本,认知负担小;
  4. 本书要用它做实验:第 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
--releasejavac 编译时能引用哪个版本的 APIoptions.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 尤其重要:

  1. inline 函数体是公开 API 的一部分——改函数体,调用方不重编译就不生效。apiCheck 能捕捉签名变化,但捕捉不到 inline 函数体的语义变化,需要额外的评审规则;
  2. internal 编译成 public + 名称混淆,模块名变化会破坏兼容;
  3. 默认参数:加一个默认参数看似兼容,实际会改变 $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 的三个必知陷阱:

  1. 死代码消除(DCE):如果基准方法的结果没被使用,JIT 会把整个计算删掉。JMH 用 Blackhole 或返回值消费来解决——必须 return 结果或用 @State 保存。
  2. 常量折叠:如果输入是编译期常量,计算会在编译期完成。用 @Setup 准备数据 + @State 字段。
  3. 预热不足: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%需模块间无隐式依赖
4kapt → KSP注解处理 -50%~-80%见 5.5
5Kotlin 增量编译(默认开启)+ classpath snapshot增量构建 -60%kotlin.incremental.useClasspathSnapshot=true
6文件系统监视 org.gradle.vfs.watch=true增量 -10%~-30%
7给 Gradle 守护进程足够内存 -Xmx4g -XX:MaxMetaspaceSize=1g避免频繁 GC/OOMKotlin 编译很吃内存
8守护进程用 Parallel GC(而非默认 G1)编译吞吐略升短生命周期、吞吐优先场景
9减少模块数量 / 合并小模块配置与调度开销下降与增量编译收益权衡
10避免在配置期做重活(读文件、跑命令)配置阶段大幅下降用 Provider 惰性求值
11kotlin.compiler.execution.strategy=in-process小项目 -20%大项目反而可能 OOM,需实测
12JDK 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 本章小结

  1. jvmToolchain(用哪个 JDK 编译)、jvmTarget(产出什么版本字节码)、options.release(能引用什么 API)是三件不同的事,必须同时配置正确。这是混编工程头号构建错误源。
  2. Version Catalog + build-logic(precompiled script plugins) 是多模块工程的标准答案:版本集中管理、构建约定复用。
  3. kapt → KSP 是 2026 年必须完成的迁移,收益 2–5 倍构建速度。KSP2 基于 K2,增量更准。
  4. Detekt 的两条规则值得强制开启:GlobalCoroutineUsage(协程泄漏)与 UnsafeCallOnNullableType(!!)。
  5. 二进制兼容验证对 Kotlin 库尤其关键,因为加默认参数会破坏二进制兼容($default 签名变化),这是 Java 没有的陷阱。
  6. JMH 是性能结论的唯一可信来源。手写 System.nanoTime() 循环测出来的数字基本没有参考价值(DCE、常量折叠、预热不足)。
  7. 反编译工作流(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。

缓解方案:

  1. 保留旧签名:新增重载而非修改原函数(手动写 fun f(a: Int, b: Int) = f(a, b, 2));
  2. 📌 Kotlin 2.4.0 的 @IntroducedAt(实验):自动生成基于版本的重载;
  3. @JvmOverloads:生成 Java 风格的重载(对 Java 调用方友好,但对 Kotlin 调用方仍有问题);
  4. 库层面:用二进制兼容验证器在 CI 拦截,遵循语义化版本(这类变更应升 minor/major)。

5-3.(🧪 动手)配置一个 JMH 基准,测量 List<Int> 与 IntArray 在求和场景下的差异,并用 -prof gc 输出分配率。解释你观察到的结果。

答案要点

预期结果(量级):

  • IntArray 求和:约 0.3–0.5 ms / 百万元素;分配率接近 0;
  • List<Int> 求和:约 2–5 ms / 百万元素;分配来自装箱(如果列表是运行期构建的)与迭代器。

原因:

  1. 内存布局:int[] 连续存储 4 字节/元素;List<Integer> 是 Object[](4 或 8 字节引用)+ 每个 Integer 对象(📌 JDK 27 紧凑头下 16 字节)→ 缓存局部性差 3–5 倍;
  2. 解引用:List 每次访问需要两次内存访问(数组 → 对象 → 字段);
  3. 向量化:int[] 的循环 C2 可以做 SIMD 自动向量化;List<Integer> 不行;
  4. 边界检查: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 慢?你会怎么优化?

答题框架:

  1. 原因:Kotlin 编译器本身更复杂(FIR 前端 + IR 后端 + 多趟降低);kapt 需要生成 Java stub 并跑 javac;增量编译的粒度与快照机制开销;stdlib 依赖解析。
  2. 优化清单(按 ROI):kapt→KSP;配置缓存;构建缓存(本地+远端);并行;增量编译 + classpath snapshot;守护进程内存调优;文件系统监视;合理拆分模块(增量友好但配置开销增加,需权衡);in-process 编译策略(小项目);用更高版本 JDK 跑 Gradle。
  3. 度量:--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 顺序变化影响序列化);
  • 流程:语义化版本 + 变更日志 + @Deprecated(level=WARNING) → ERROR → HIDDEN 的三阶段移除。

第一篇完。

下一篇预告:第二篇《Kotlin 语言核心》(第 6–19 章)。我们从类型系统开始——Int 到底是什么?为什么 Int? 会装箱?为什么 IntArray 不会?为什么 Kotlin 说"一切皆对象"却又提供 IntArray?这些问题的答案,会把 Kotlin 语言设计与 JVM 内存模型第一次真正连起来。