KAPT 与 KSP 的底层工作原理与符号处理在工程中的演进迭代
KAPT 和 KSP 都服务于“编译期生成代码”，但它们站在 Kotlin 编译管线中的位置完全不同。
KAPT 是 Kotlin 为兼容 Java Annotation Processing API 做的桥接层。它需要先为 Kotlin 源码生成 Java stub，让传统 javac annotation processor 以为自己面对的是 Java 源码。KSP 则直接接入 Kotlin 编译器符号模型，让处理器读取 Kotlin 语义，不再绕一圈 Java stub。
可以把 KAPT 想象成翻译官：先把 Kotlin 粗略翻译成 Java 草稿，再交给只懂 Java 的处理器。KSP 则像让处理器直接坐进 Kotlin 编译器的符号阅览室，读取更接近真实 Kotlin 的结构。
Java 注解处理的原始模型
传统 annotation processing 发生在 javac 编译期：
Java source
|
v
javac rounds
|
+-- processors read elements
+-- processors generate source
+-- javac compiles generated source
v
.class
处理器看到的是 Element、TypeMirror、AnnotationMirror。Dagger、Room、AutoService 等大量生态最初都基于这套 API。
问题在于 Kotlin 不是 Java。Kotlin 有属性、顶层函数、扩展函数、默认参数、挂起函数、nullable 类型、data class、internal 可见性等语义。把它们映射到 Java element，会丢失或扭曲一部分信息。
KAPT 的工作链路
KAPT 大致流程：
Kotlin source
|
v
KAPT stub generation
|
v
Java-like stubs
|
v
javac annotation processors
|
v
generated Java/Kotlin source
|
v
Kotlin/Javac compile
Stub generation 是 KAPT 成本的核心之一。它必须让 Java processor 能解析符号，但又不真正完整编译 Kotlin。复杂 Kotlin 语义在 stub 里可能只能近似表达。
例如 Kotlin 属性：
class User(
val id: String,
var name: String?
)
在 Java processor 眼中更接近 getter/setter/field 的组合。处理器如果按 Java 习惯理解 nullable 或默认参数，很容易需要额外规则。
KAPT 为什么慢
KAPT 慢通常来自几层叠加：
- 需要生成 stub。
- javac processor 多轮处理。
- 处理器可能不是增量的。
- Kotlin 编译和 Java 处理之间存在额外同步点。
- 聚合型处理器会让一个小改动影响全局生成结果。
增量注解处理器通常分为 isolating 和 aggregating：
| 类型 | 特征 | 影响范围 |
|---|---|---|
| isolating | 一个输入生成对应输出 | 改动影响局部 |
| aggregating | 多个输入汇总生成少量输出 | 改动可能影响全局 |
Dagger/Hilt、Room、导航生成等工具若处于聚合路径，会显著放大编译成本。
KSP 的符号模型
KSP 提供 KSClassDeclaration、KSFunctionDeclaration、KSPropertyDeclaration 等 Kotlin 符号 API。处理器不再通过 Java stub 读取 Kotlin，而是读取 Kotlin 编译器暴露的语义结构。
Kotlin source
|
v
Kotlin symbol model
|
v
KSP processors
|
v
generated source
|
v
Kotlin compile
KSP 的优势：
- 避免 KAPT stub generation。
- 更准确表达 Kotlin 语义。
- 更容易做增量处理。
- 对 Kotlin-only 项目更自然。
但 KSP 不是“自动更快”的魔法。如果处理器本身做全局扫描、读取未声明文件、生成不稳定输出，仍然会慢。
迁移时要看处理器生态
迁移策略：
// KAPT
plugins {
id("kotlin-kapt")
}
dependencies {
kapt("androidx.room:room-compiler:...")
}
// KSP
plugins {
id("com.google.devtools.ksp")
}
dependencies {
ksp("androidx.room:room-compiler:...")
}
能迁移的前提是对应库提供 KSP processor。Room、Moshi、Glide、部分 DI/序列化生态已经支持 KSP，但具体版本需要按官方文档确认。
迁移后要验证：
- 生成代码包名和路径是否变化。
- kapt arguments 是否有对应 ksp arguments。
- 增量编译是否真的改善。
- IDE、CI、release 构建是否一致。
工程边界
大型 Android 工程中，注解处理应遵守：
- 能用 KSP 的库优先用 KSP。
- 避免在所有模块默认引入 KAPT。
- 把处理器参数集中在 convention plugin。
- 对生成代码目录保持稳定，不把生成代码提交到业务源码目录。
- 用 Build Scan 观察 kapt/ksp 任务耗时。
KAPT/KSP 的本质是编译器扩展点。它们可以大幅提升开发效率，也会成为构建性能黑洞。理解它们在编译管线中的位置，才能判断某个生成器该放在哪个模块、该不该迁移、慢在哪里。
工程风险与观测清单
KAPT 与 KSP 的底层工作原理与符号处理在工程中的演进迭代 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。
因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。
关键风险矩阵
| 风险点 | 触发条件 | 直接后果 | 观测方式 | 缓解策略 |
|---|---|---|---|---|
| 输入声明缺失 | 构建逻辑读取未声明文件或环境变量 | UP-TO-DATE 或缓存结果错误 | 使用 --info 和 Build Scan 查看输入变化 |
把所有影响输出的状态建模为 @Input 或 Provider |
| 绝对路径泄漏 | 任务 key 包含本机路径 | CI 与本地缓存无法复用 | 对比不同机器的 cache key 变化 | 使用相对路径敏感性和路径归一化 |
| 配置期副作用 | build script 执行 I/O、Git、网络请求 | 任意命令都变慢，configuration cache 失效 | 执行 help --scan 观察配置期耗时 |
把副作用移动到任务动作并声明输入输出 |
| Variant 污染 | 对所有 variant 注册重型任务 | debug 构建被 release 逻辑拖慢 | 查看 realized tasks 和 task timeline | 使用 selector 精确匹配目标 variant |
| 权限外溢 | 插件或脚本读取 CI secret、用户目录 | 构建不可复现，存在供应链风险 | 审计构建日志和环境变量访问 | 使用最小权限和显式 secret 注入 |
| 并发竞争 | 多个任务写同一输出目录 | 产物互相覆盖或偶发失败 | 检查 overlapping outputs 报告 | 每个任务拥有独立输出目录 |
| 缓存污染 | 不可信分支向远程缓存 push | 全团队复用错误产物 | 统计 remote cache push 来源 | 只允许受信任 CI 写入远程缓存 |
| 回滚困难 | 构建逻辑与业务变更混在一起 | 发布失败时无法快速定位 | 变更审计和构建 scan 对比 | 构建逻辑独立提交、独立验证 |
| 降级缺口 | 新 Gradle/AGP API 无兜底策略 | 升级失败后阻塞全线开发 | 记录兼容矩阵和失败任务 | 保留可回滚版本和迁移开关 |
| 资源释放遗漏 | 自定义任务打开文件句柄或进程未关闭 | Windows/CI 上清理失败或锁文件 | 观察 daemon 日志和文件锁错误 | 使用 Worker API 或 try/finally 释放资源 |
需要持续观测的指标
- 配置阶段耗时是否随模块数量线性或超线性增长。
- 单次本地 debug 构建的关键路径任务是谁。
- CI clean build 与 incremental build 的耗时差距。
- 远程 Build Cache 的 hit rate、miss 原因和下载耗时。
- Configuration Cache 的命中率和失效原因。
- Kotlin/Java 编译任务是否被不相关资源或依赖变化触发。
- 资源合并、DEX、R8、打包任务是否在小改动后全量重跑。
- 自定义插件是否提前实现了无关任务。
- 构建日志中是否出现未声明输入、重叠输出、deprecated API。
- 发布产物是否能追溯到唯一的源码提交、依赖锁和构建扫描。
- 失败是否可稳定复现，还是只在特定机器、特定并发下出现。
- 变更是否影响开发构建、测试构建和发布构建三条路径。
回滚与降级策略
- 构建逻辑变更与业务代码变更分开提交，便于二分定位。
- Gradle、AGP、Kotlin、JDK 升级必须保留兼容矩阵和回滚版本。
- 新插件能力先只接入一个低风险模块，再扩大到全工程。
- 远程缓存先 pull 后 push，确认产物稳定后再允许 CI 写入。
- 新增插桩、生成代码、资源处理逻辑必须提供开关。
- 发布构建失败时，优先回滚构建逻辑版本，而不是清空所有缓存碰运气。
- 对 CI 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
- 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。
最小验证矩阵
| 验证场景 | 命令或动作 | 期望信号 |
|---|---|---|
| 空任务配置成本 | ./gradlew help --scan |
配置期没有无关重任务 |
| 本地增量构建 | 连续执行同一 assemble 任务 | 第二次大量任务 UP-TO-DATE |
| 缓存复用 | 清理输出后启用 build cache | 可缓存任务出现 FROM-CACHE |
| Variant 隔离 | 分别构建 debug/release | 只出现目标 variant 相关任务 |
| CI 可复现 | 干净工作区执行 release 构建 | 不依赖本机隐藏文件 |
| 依赖稳定 | 执行 dependencyInsight | 版本选择可解释，无动态漂移 |
| 配置缓存 | --configuration-cache 连跑两次 |
第二次复用配置缓存 |
| 发布审计 | 记录 scan、mapping、签名信息 | 产物可追溯、可回滚 |
审计问题
- 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
- 它是否读取了没有声明为输入的文件、环境变量或系统属性。
- 它是否在配置阶段执行了本应放到任务动作里的工作。
- 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
- 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
- 它是否把权限、密钥、签名文件路径写进了仓库。
- 它是否破坏了并发执行，例如多个任务写同一个目录。
- 它是否能在失败时输出足够日志，帮助定位根因。
- 它是否能通过一个开关降级，避免阻塞全工程构建。
- 它是否有最小复现样例或 TestKit/集成测试覆盖。
- 它是否会让下游模块承担不必要的依赖或任务成本。
- 它是否能在升级 Gradle/AGP 后继续工作，还是依赖内部 API。
反模式清单
- 用
clean掩盖输入输出声明错误。 - 用
afterEvaluate修补本可以用 Provider 表达的依赖关系。 - 用动态版本解决依赖冲突，却让构建不可复现。
- 把所有公共配置塞进一个巨型 convention plugin。
- 在 debug 构建默认开启 release 级别的重型优化。
- 在任务动作里读取
project或全局 configuration。 - 在多个任务中共享同一个临时目录。
- 缓存命中率异常时只重启 CI，不分析 miss reason。
- 把构建扫描链接当作可选附件，而不是性能回归证据。
- 用本地 IDE 成功运行证明 CI 发布链路安全。
最小实操脚本
./gradlew help --scan
./gradlew :app:assembleDebug --scan --info
./gradlew :app:assembleDebug --build-cache --info
./gradlew :app:assembleDebug --configuration-cache
./gradlew :app:dependencies --configuration debugRuntimeClasspath
./gradlew :app:dependencyInsight --dependency <module> --configuration debugRuntimeClasspath
这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 KAPT 与 KSP 的底层工作原理与符号处理在工程中的演进迭代 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。