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

04.8.3.2 KSP、kapt 与编译器插件

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

本节要解决的问题

本节聚焦 JVM 后端与通用构建视角下的 Kotlin 元数据处理与编译期扩展:KSP 符号处理与 kapt 注解处理桩的差异、KSP 处理器开发要点、kapt 的 stub 开销与增量限制、编译器插件(序列化、allopen、noarg 等)的注册与 IR 层、主流库的生成链路,以及 KSP 与 K2 编译器的兼容现状。版本基线为 Kotlin 2.x、KSP 2.x;具体处理器 API 与插件坐标以官方文档当前版本为准。

04.8.3.2-001 KSP 是什么?

一句话结论

KSP(Kotlin Symbol Processing)是 Kotlin 官方提供的轻量级符号处理框架:处理器直接在 Kotlin 符号模型上读取类、函数、属性与注解信息并生成代码,不必把 Kotlin 源码翻译成 Java 桩。

概念解释

KSP 定位替代 kapt 做注解式代码生成。它暴露 Kotlin 感知的符号模型(可空性、类型参数、声明来源),处理器运行在编译期处理源符号。典型使用者包括 Room、Moshi 等生成 DAO/序列化实现的库。

原理流程

  1. 编译流程中 KSP 收集源码与依赖中的符号声明。
  2. 处理器实现 SymbolProcessor,按注解或规则筛选符号。
  3. 通过代码生成器写出 Kotlin/Java 源文件或资源。
  4. 生成代码参与后续 Kotlin 编译。

代码或图示

// 处理器入口骨架(API 细节以 KSP 当前版本为准)
class MyProcessor : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> {
        // 读取符号、生成代码
        return emptyList()
    }
}

常见误区

  • 以为 KSP 是编译器插件:KSP 是符号处理 + 代码生成框架,不改写已有类的字节码;IR 插件才在编译器中间层改写。
  • 以为 KSP 只能处理主源集:测试源集是否参与由配置决定,需按构建脚本核对。

追问

  • KSP 产物放在哪里?答:生成源码进入编译任务的生成源目录,随模块编译打包。
  • KSP 处理器用什么语言写?答:通常用 Kotlin/JVM 编写,作为构建期依赖接入。

04.8.3.2-002 KSP 与 kapt 的核心差异是什么?

一句话结论

KSP 基于 Kotlin 原生符号模型直接处理;kapt 先把 Kotlin 源码生成 Java 桩(stub),再走 JSR-269 Java 注解处理流程,因此丢失部分 Kotlin 信息且开销更大。

概念解释

kapt 为兼容 Java 注解处理器生态而设计:它必须把 Kotlin 类签名翻译成 Java 可见的桩类,处理器在桩上工作。KSP 绕过 Java 桩,直接暴露 Kotlin 类型系统。两者产物都参与后续编译,但处理路径与信息保真度不同。

原理流程

  1. kapt:Kotlin 源码 → stub 生成 → Java 注解处理器读桩 → 生成代码 → Kotlin 编译合并。
  2. KSP:Kotlin 源码 → 符号模型 → 处理器直接读取 → 生成代码 → Kotlin 编译合并。
  3. KSP 省去桩生成环节,类型信息保留更完整。
  4. kapt 可复用存量 Java 处理器,KSP 需要处理器按 KSP API 实现。

代码或图示

kapt:Kotlin → Java stub → javac 注解处理 → 生成代码
KSP :Kotlin → KSP 符号模型 → KSP 处理器 → 生成代码

常见误区

  • 以为 KSP 处理器与 Java 注解处理器可直接互换:API 不同,处理器需迁移实现。
  • 以为 kapt 只在编译期多一步翻译无成本:桩生成与解析是 kapt 主要耗时来源之一。

追问

  • 现有 Java 注解处理器能否在 KSP 下运行?答:不能直接运行,需要改写成 KSP 处理器或继续保留 kapt。
  • 生成代码质量两者有差别吗?答:KSP 可感知 Kotlin 可空性与类型参数,生成代码更贴合 Kotlin 类型系统。

04.8.3.2-003 为什么 KSP 通常比 kapt 快?

一句话结论

KSP 省去 kapt 的 stub 生成与 Java 注解处理两轮解析,直接在轻量符号模型上工作,进程与模型构建开销更小;增量粒度也更贴近 Kotlin 源码变更。

概念解释

kapt 需要完整翻译签名到 Java 桩并启动 javac 处理链;KSP 只构建处理器所需的符号视图。实际提速幅度受处理器遍历范围、生成代码量影响,但缺少桩生成环节是结构性优势。

原理流程

  1. kapt 阶段:解析 Kotlin → 生成桩 → javac 读取桩 → 处理器执行。
  2. KSP 阶段:构建符号模型 → 处理器查询符号 → 生成代码。
  3. 少一轮跨语言模型转换。
  4. 增量场景下 KSP 可按符号变更缩小处理范围。

代码或图示

耗时对比:kapt = Kotlin 解析 + stub 生成 + javac 处理
KSP  = Kotlin 解析 + 符号模型查询 + 处理器执行

常见误区

  • 以为换 KSP 就一定显著提速:处理器自身遍历全量符号、生成大量代码时仍可能成为瓶颈。
  • 以为 KSP 不占内存:符号模型与生成代码仍需内存,大模块需关注进程内存。

追问

  • 如何量化迁移收益?答:对比迁移前后注解处理阶段耗时与冷/热构建时间。
  • KSP 增量粒度如何?答:按源码变更与符号依赖分析,具体隔离策略以 KSP 版本文档为准。

04.8.3.2-004 KSP 能处理 Java 源文件吗?

一句话结论

KSP 主要面向 Kotlin 符号模型;对同一编译单元中的 Java 类,可通过符号模型读取其声明信息,但处理能力与保真度不等同于完整 Java 注解处理生态。

概念解释

混合工程中 Kotlin 与 Java 互引用,KSP 解析依赖类型时能看到 Java 类的签名。纯 Java 注解处理(读 Java 注解、生成 Java 代码)的成熟场景仍由 kapt/javac 链承担。跨语言可见性细节随 KSP 版本演进,不确定处标待确认。

原理流程

  1. 编译模块含 Kotlin 与 Java 源码。
  2. KSP 构建符号模型时纳入可解析的 Java 声明。
  3. 处理器读取 Java 类签名用于类型推导。
  4. 生成代码仍进入 Kotlin/Java 编译单元。

代码或图示

Kotlin 源码 ──▶ KSP 符号模型 ◀── Java 签名(可读)

常见误区

  • 以为 KSP 完全替代 javac 处理所有 Java 注解:存量 Java 处理器仍需 kapt。
  • 以为 Java 私有成员在 KSP 中可见:可见性规则在符号模型中保留。

追问

  • 混合模块处理器以哪类源码为主?答:按生成目标设计;处理 Kotlin 标注类用 KSP,纯 Java 生态保留 kapt。
  • KSP 读取 Java 泛型有何限制?答:类型映射边界以 KSP 文档为准,复杂签名需实测。

04.8.3.2-005 KSP 处理器运行在编译的哪个阶段?

一句话结论

KSP 在 Kotlin 编译前的符号处理阶段运行:先处理源码符号并生成代码,生成的源码再交给 Kotlin 编译器编译;处理器不参与字节码生成阶段。

概念解释

处理阶段位于源码解析之后、最终编译之前。处理器本轮生成的新符号可在后续轮次被读取(多轮处理模型)。KSP 任务与 Kotlin 编译任务在任务图中按顺序连接。

原理流程

  1. KSP 任务收集当前轮次符号。
  2. 处理器执行并输出生成文件。
  3. 若产生新符号,进入下一轮处理。
  4. 轮次结束后生成源码并入 Kotlin 编译任务。

代码或图示

源码解析 → KSP 多轮处理 → 生成源码 → Kotlin 编译 → 字节码

常见误区

  • 以为 KSP 能在编译后修改字节码:那是 IR 编译器插件的职责。
  • 以为处理器可读取 classpath 上所有类的完整实现:可读符号签名,不读方法体实现。

追问

  • 生成代码能否引用本轮其他处理器产物?答:通过多轮处理模型协调顺序,处理器间依赖需明确声明。
  • KSP 失败会中断编译吗?答:处理器报错按日志级别中断或告警,错误通常阻断 KSP 任务。

04.8.3.2-006 kapt 是什么,历史由来是什么?

一句话结论

kapt(Kotlin annotation processing tool)是 Kotlin 早期为复用 JVM Java 注解处理器生态而提供的桥接工具:把 Kotlin 签名翻译成 Java 桩,让 javac 注解处理器在桩上运行。

概念解释

在 KSP 出现前,Dagger、Auto 系列等 Java 注解处理器需要 Java 类型视图,kapt 承担 Kotlin 到 Java 的签名翻译。它不是 Kotlin 原生处理框架,而是兼容层。新项目优先评估 KSP,存量 kapt 按生态支持情况迁移。

原理流程

  1. KGP 配置 kapt 插件后注册 kapt 任务。
  2. 编译器为 Kotlin 类生成 Java 桩签名。
  3. javac 启动注解处理,处理器在桩上执行。
  4. 生成源码交回 Kotlin 编译合并。

代码或图示

plugins {
    kotlin("jvm")
    id("kotlin-kapt")
}

常见误区

  • 以为 kapt 是 Kotlin 官方长期主推方向:官方趋势是 KSP 承接 Kotlin 侧生成链路。
  • 以为 kapt 处理器能拿到 Kotlin 方法体:桩只含签名,不含实现体。

追问

  • kapt 插件 id 是什么?答:kotlin-kapt,由 Kotlin Gradle Plugin 提供;版本随 Kotlin 对齐。
  • kapt 生成代码放在哪个源集?答:进入 kapt 生成源码目录,参与主编译。

04.8.3.2-007 kapt 为什么要生成 Java stub?

一句话结论

Java 注解处理器基于 javac 的符号 API 工作,只认 Java 类型视图;kapt 必须把 Kotlin 类签名(类名、方法、字段、泛型)翻译成桩类,处理器才能按 Java 模型读取。

概念解释

桩是只含签名、不含方法体的 Java 源/类视图。Kotlin 特有语法(挂起函数、可空性、内联类)需要映射到 Java 可见形式,映射过程存在信息损失。桩生成是 kapt 架构的必要代价。

原理流程

  1. 解析 Kotlin 类声明与签名。
  2. 映射为 Java 兼容签名生成桩。
  3. javac 注解处理读取桩类型。
  4. 处理器生成代码后桩被丢弃,不进最终产物。

代码或图示

Kotlin: fun greet(name: String?): String
桩(Java 视图):String greet(@Nullable String name)

常见误区

  • 以为桩会打包进 jar:桩是中间产物,不进入运行产物。
  • 以为可空性在桩中完整保留:映射为平台类型或注解,保真度受 javac 模型限制。

追问

  • 挂起函数在桩中如何表达?答:映射为带 Continuation 参数的回调签名,具体形式以 kapt 实现为准。
  • 桩生成失败常见原因?答:复杂 Kotlin 类型无法映射为 Java 签名,编译器报错指向对应类。

04.8.3.2-008 kapt 对 Kotlin 类型的表达有哪些局限?

一句话结论

桩基于 Java 类型系统,可空性、类型参数细节、内联声明、挂起函数等 Kotlin 特性只能近似映射;处理器看到的是 Java 视图,部分 Kotlin 语义不可见或被弱化。

概念解释

Java 没有可空类型系统,Kotlin 平台类型与注解约定替代;内联函数、value class、密封层次等在桩中表达受限。处理器若依赖 Kotlin 特有语义,在 kapt 下可能读到不完整信息。

原理流程

  1. Kotlin 类型进入映射层。
  2. 可空性转为注解或平台类型。
  3. 特有语法折叠为 Java 兼容签名。
  4. 处理器基于近似视图工作,细节丢失。

代码或图示

Kotlin 语义 ──映射──▶ Java 桩视图(可空性/泛型/内联信息有损)

常见误区

  • 在 kapt 处理器中断言 Kotlin 可空性精确可见:实际需依赖映射注解,边界以实测为准。
  • 以为 kapt 能处理 Kotlin 源码中的声明位置注解全部细节:源码注解可见,类型语义受桩限制。

追问

  • 哪些框架已迁到 KSP?答:Room、Moshi 等提供 KSP 支持;Dagger 等生态状态以官方公告为准,不确定标待确认。
  • kapt 下如何验证类型信息?答:在处理器中打印桩签名,对照 Kotlin 源码核对映射结果。

04.8.3.2-009 KSP 与 K2 编译器兼容现状如何?

一句话结论

KSP 提供面向 K2 编译器的支持版本线(KSP2),Kotlin 2.x 工程应选择与编译器配套的 KSP 版本;具体兼容范围与仍有限制的场景以官方发布说明为准,标待确认项需在升级前核对。

概念解释

K2 重写了 Kotlin 前端,符号解析模型变化。KSP1 基于旧前端,KSP2 适配新前端。工程升级到 Kotlin 2.x 时需同步选择支持 K2 的 KSP 版本;个别处理器在迁移期可能存在行为差异。

原理流程

  1. 确认 Kotlin 编译器版本与前端模式。
  2. 选择配套 KSP 版本线。
  3. 接入处理器并跑生成代码链路。
  4. 对照发布说明核对未覆盖场景。

代码或图示

Kotlin 2.x(K2)──配套──▶ KSP2(版本见官方矩阵)

常见误区

  • 升级 Kotlin 后沿用旧 KSP:报编译器版本不匹配或符号解析异常。
  • 假设所有 KSP 处理器在 KSP2 下行为一致:处理器实现依赖的 API 可能有迁移差异。

追问

  • 如何确认当前用的是 KSP1 还是 KSP2?答:查 KSP 版本与发布说明中的前端适配标识;构建日志也可能显示处理后端。
  • K2 下 kapt 支持范围?答:kapt 对 K2 的支持有限制,复杂场景以官方文档为准,新项目优先 KSP。

04.8.3.2-010 KSP 版本与 Kotlin 编译器版本是什么绑定关系?

一句话结论

KSP 版本按 Kotlin 编译器版本配套发布,每个 KSP 版本对应特定 Kotlin 版本区间;混用不配套版本会在处理阶段报编译器版本不匹配。

概念解释

KSP 依赖编译器内部 API 暴露符号模型,编译器升级会改变这些 API,因此 KSP 必须随 Kotlin 联动升级。版本目录中应让 Kotlin 版本段同时约束 KGP、stdlib 与 KSP 插件条目。

原理流程

  1. 查 KSP 官方兼容表确定 Kotlin 版本对应 KSP 版本。
  2. 目录登记配套版本。
  3. 构建期 KSP 校验编译器版本。
  4. 不匹配即报错中断。

代码或图示

[versions]
kotlin = "2.0.20"
ksp = "2.0.20-1.0.25"   # 与 kotlin 配套,具体编号以官方当前版本为准

常见误区

  • 只升 Kotlin 不升 KSP:符号处理任务失败。
  • 给 KSP 写跨多个 Kotlin 大版本的宽泛版本:兼容窗口有限,按矩阵锁定。

追问

  • 处理器自身依赖 KSP API 版本吗?答:处理器编译期引用 KSP API 构件,API 版本与运行期 KSP 需兼容。
  • 升级 Kotlin 后 KSP 报版本不匹配怎么处理?答:先在兼容表找到配套 KSP 版本升级,再评估处理器是否支持。

04.8.3.2-011 KSP 处理器可以产出哪些类型的产物?

一句话结论

处理器可生成 Kotlin 或 Java 源文件、资源文件,也可读取符号信息用于校验;产物进入对应生成源码目录或资源目录参与后续编译。

概念解释

代码生成是主要用途:为注解标注类生成实现类、代理类、序列化器等。资源产物用于生成配置文件、服务注册清单。处理器不直接修改被标注类的字节码。

原理流程

  1. 处理器通过代码生成 API 创建文件。
  2. 指定包名、文件名与内容。
  3. 生成源码加入编译源集。
  4. 资源产物加入对应资源目录。

代码或图示

处理器输出:*.kt / *.java 源码、资源文件
后续:源码进 Kotlin/Java 编译,资源进打包

常见误区

  • 以为处理器能直接改写原类:生成新类是主要模式,改写既有逻辑归编译器插件。
  • 生成文件命名与原类冲突:需按规则加后缀并检查重名。

追问

  • 生成 Kotlin 代码还是 Java 代码优先?答:KSP 面向 Kotlin 模型,生成 Kotlin 更自然;需被 Java 消费时再评估 Java 产物。
  • 生成代码能否含注解?答:可以,生成源码同样可被后续轮次或编译器插件处理。

04.8.3.2-012 KSP 与 JSR-269 注解处理是什么关系?

一句话结论

JSR-269 是 javac 的注解处理 SPI,kapt 桥接复用它;KSP 是 Kotlin 自有的替代处理框架,API 模型独立于 JSR-269,两者不共用处理器接口。

概念解释

Java 生态的 Processor 接口、Filer、RoundEnvironment 属于 javac 处理链。KSP 用 SymbolProcessor、Resolver、CodeGenerator 对应角色,概念相似但类型与调用方式不同。

原理流程

  1. JSR-269:javac 在编译期回调 Java Processor。
  2. kapt 把 Kotlin 桩喂给该链。
  3. KSP:KGP 在编译前回调 Kotlin SymbolProcessor。
  4. 两套 SPI 各自注册处理器。

代码或图示

JSR-269:javac ──▶ Processor(RoundEnvironment, Filer)
KSP :KGP ──▶ SymbolProcessor(Resolver, CodeGenerator)

常见误区

  • 把 Java Processor 类直接注册进 KSP:接口不匹配,无法加载。
  • 以为 KSP 未来会兼容 JSR-269 接口:路线以官方文档为准,当前需独立实现。

追问

  • 迁移一个 Java 处理器到 KSP 要改什么?答:符号查询 API、生成文件 API、日志与轮次模型全部按 KSP 重写。
  • 两套处理器能在同一模块共存吗?答:可分别配置 kapt 与 KSP,但增加构建复杂度,应评估是否必须。

04.8.3.2-013 什么场景下仍必须使用 kapt?

一句话结论

当依赖的注解处理库只提供 Java 处理器、尚无 KSP 版本,或处理器深度依赖 javac 模型与 Java 生态工具链时,短期内仍需保留 kapt;有 KSP 支持的库应优先迁移。

概念解释

选型取决于第三方库生态而非个人偏好。后端通用库中,部分 Dagger/自动生成类框架可能仅提供 kapt;需逐项核对官方支持矩阵。新写的内部处理器直接基于 KSP,不再投资 kapt 实现。

原理流程

  1. 列出工程用到的生成类库。
  2. 核对各库 KSP/kapt 支持状态。
  3. 有 KSP 的迁移,无 KSP 的保留 kapt。
  4. 跟踪库发版,支持 KSP 后切换。

代码或图示

库 A:KSP 支持 → 用 KSP
库 B:仅 Java 处理器 → 保留 kapt(待生态更新)

常见误区

  • 为统一构建把仅 kapt 的库强行套 KSP:处理器不存在对应实现。
  • 长期把新内部注解处理器写成 kapt:应直接选 KSP。

追问

  • 同一模块能同时配 kapt 与 KSP 吗?答:技术上可并存,但两套处理链都会增加编译时间,需评估必要性。
  • 如何查某库支持哪种处理方式?答:查库官方文档与发布说明;版本能力不确定处标待确认。

04.8.3.2-014 KSP 能否读取 Java 类携带的 Kotlin 元数据?

一句话结论

KSP 处理 Kotlin 符号时可解析 Kotlin 元数据以还原类型语义;对纯 Java 类则按 Java 签名读取,不包含 Kotlin 特有声明信息。

概念解释

编译后的 Kotlin 类携带元数据注解,记录类型参数与可空性等信息。源码处理阶段 KSP 直接基于 AST 符号;读取依赖类时通过其元数据或签名还原。Java 类无此元数据,按 Java 模型呈现。

原理流程

  1. 读取 Kotlin 声明:直接使用符号模型。
  2. 读取 Kotlin 依赖类:解析元数据补全类型语义。
  3. 读取 Java 依赖类:使用 Java 签名视图。
  4. 处理器按可见信息做生成决策。

代码或图示

Kotlin 类:AST 符号 + 元数据
Java 类:Java 签名视图

常见误区

  • 假设跨语言依赖的可空性始终精确:Java 平台类型需按约定处理。
  • 在 KSP 中反射读取 class 文件内容:处理期基于符号模型,不做运行期反射。

追问

  • 依赖是编译产物 jar 而非源码怎么办?答:KSP 读取 jar 中类签名与元数据,不可见方法体实现。
  • 元数据被剥离会怎样?答:类型语义信息缺失,处理器需降级处理并标注限制。

04.8.3.2-015 KSP 的多轮处理(round)模型是怎样的?

一句话结论

KSP 分轮处理:每轮处理器基于当前符号集合工作并生成新代码;新生成符号进入下一轮,直到某轮没有新符号产生才结束。

概念解释

多轮模型类似 javac 处理轮次,用于处理器之间生成与读取衔接。每轮结束 KSP 判断是否还有待处理注解/符号。处理器需正确返回未处理符号列表,避免无限轮次。

原理流程

  1. 第一轮:收集源码符号,处理器生成代码。
  2. 后续轮:上轮生成符号纳入集合,再次处理。
  3. 无新增待处理符号时结束。
  4. 全部生成源码交编译任务。

代码或图示

Round 1:源符号 → 处理器 → 生成 A
Round 2:A 纳入符号 → 处理器 → 生成 B
Round 3:无新符号 → 结束

常见误区

  • 处理器不返回未处理符号:可能导致轮次异常或符号遗漏。
  • 处理器在轮次间保留可变状态假设顺序:多轮执行顺序与隔离需按 API 约定处理。

追问

  • 生成的新类能否被下一轮 KSP 读取?答:可以,这正是多轮模型支持的衔接方式。
  • 如何避免处理轮次过多?答:处理器只处理目标注解,及时返回剩余未处理符号。

04.8.3.2-016 KSP 的增量支持粒度如何?

一句话结论

KSP 记录符号与生成文件的依赖关系,源码变更时按受影响符号缩小重处理范围;增量粒度与隔离策略随版本演进,实测以当前 KSP 文档为准。

概念解释

相比 kapt 增量受限,KSP 设计上支持更细的增量:变更类只重跑依赖它的处理器逻辑。处理器需正确声明读取范围,过度遍历全量符号会削弱增量收益。

原理流程

  1. 上轮记录符号到生成文件的映射。
  2. 本次检测变更源码。
  3. 分析受影响符号集合。
  4. 只重处理相关生成产物。

代码或图示

变更 A.kt → 受影响符号 → 重跑对应处理器逻辑 → 更新生成文件

常见误区

  • 处理器遍历整个模块符号集:变更波及面被放大,增量退化。
  • 假设生成文件自动随源码更新:处理器需按依赖关系正确产出。

追问

  • kapt 增量为何受限?答:桩生成与 javac 处理链按较粗粒度失效,细节见后续 kapt 专题题。
  • 如何验证 KSP 增量生效?答:对比改动单文件前后 KSP 任务执行范围与耗时。

04.8.3.2-017 如何调试 KSP 处理器?

一句话结论

处理器作为 JVM 代码可单测其符号查询逻辑,构建期可附加调试器到运行 KSP 的进程;日志通过处理器日志 API 输出符号与生成决策。

概念解释

处理器开发分两层:符号映射与代码生成逻辑可脱离完整构建做单元测试;与编译器/任务图衔接的部分需在构建进程中调试。先在测试夹具上构造符号输入,再联调真实模块。

原理流程

  1. 编写处理器单测,构造模拟类/注解输入。
  2. 断言查询结果与生成文件内容。
  3. 构建期必要时远程附加调试器到 KSP 进程。
  4. 通过日志定位符号读取偏差。

代码或图示

单测:模拟符号 → 处理器 → 断言生成代码
联调:真实模块 → 调试器附加 → 断点观察 Resolver

常见误区

  • 只在大工程里改处理器看生成结果:反馈慢,应先隔离单测。
  • 把调试 print 留在处理器生产代码:改用日志 API 并控制级别。

追问

  • 处理器单测夹具怎么构造?答:使用 KSP 测试框架提供的编译/符号测试能力,具体 API 以当前版本为准。
  • 生成代码错误如何反查?答:从生成类反推被处理源类,核对符号读取与模板输出。

04.8.3.2-018 KSP 处理器依赖如何声明?

一句话结论

处理器通过 KSP 专用 configuration(如 ksp(...))加入构建,与业务运行依赖分离;处理器本身及其编译期依赖不进业务运行 classpath。

概念解释

KSP configuration 只在符号处理阶段使用,处理器类由 KSP 加载执行。业务模块声明 KSP 依赖后,处理器随编译任务运行,产物源码再参与编译。处理器实现库版本与 KSP API 兼容。

原理流程

  1. 应用 KSP 插件。
  2. dependencies 中以 KSP configuration 声明处理器坐标。
  3. 构建期 KSP 从该配置加载处理器。
  4. 处理器输出源码进入编译源集。

代码或图示

plugins {
    kotlin("jvm")
    id("com.google.devtools.ksp")
}

dependencies {
    ksp(libs.room.compiler)
}

常见误区

  • 把处理器加到 implementation:不会被 KSP 加载,生成链路不生效。
  • 处理器版本与 KSP/Kotlin 不配套:处理阶段报兼容错误。

追问

  • KSP 插件 id 与坐标?答:以官方当前版本文档为准;版本通过版本目录登记,不写死未经验证的编号。
  • 处理器的传递依赖会进业务产物吗?答:处理期依赖不进入运行产物;生成代码引用的库需业务另行声明。

04.8.3.2-019 KSP 生成代码放在哪个目录?

一句话结论

生成源码进入模块构建目录下的 KSP 生成源目录,编译任务把该目录加入源码集合;它是构建产物,不手工编辑,清理构建目录后重新生成。

概念解释

生成目录由 KGP/KSP 按约定管理,位于模块 build 输出区内。IDE 同步后可查看生成类便于调试,但源文件以处理器重新生成为准。该目录与手工编写源码分离。

原理流程

  1. KSP 任务执行时创建生成源目录。
  2. 处理器写入 .kt/.java 文件。
  3. Kotlin 编译任务把生成目录纳入 sourceSet。
  4. 产物随 jar 打包,生成目录本身不入库。

代码或图示

模块 build 目录下:generated/ksp/...(具体路径以 KGP 版本为准)

常见误区

  • 直接修改生成目录中的类:下次构建被覆盖,改动丢失。
  • 把生成目录纳入版本管理:生成物应忽略,重新构建生成。

追问

  • 生成类在 IDE 中找不到?答:执行同步/构建让生成目录加入源集;检查 KSP 任务是否成功。
  • 多 sourceSet 生成目录如何区分?答:按 sourceSet 分别生成,路径约定以插件文档为准。

04.8.3.2-020 KSP 与编译守护进程有什么关系?

一句话结论

KSP 任务在构建编排下运行,处理器类加载与执行可复用编译相关守护进程环境;处理器重、模块大时需关注处理阶段内存与进程复用配置。

概念解释

KSP 不是独立编译器前端,但其处理任务与 Kotlin 编译任务顺序衔接。构建守护进程复用影响启动开销,处理器本身的内存占用随符号规模增长。

原理流程

  1. Gradle daemon 调度 KSP 任务。
  2. 加载处理器实现与符号模型。
  3. 处理器执行生成逻辑。
  4. 交接给 Kotlin 编译任务。

代码或图示

Gradle daemon → KSP 任务(处理器 + 符号模型)→ Kotlin 编译任务

常见误区

  • 把 KSP 耗时全部算作编译耗时:应在任务报告中区分 KSP 任务与编译任务。
  • 处理器内存问题只调 Gradle daemon 堆:处理进程内存配置需按 KSP/KGP 文档核对。

追问

  • KSP 任务失败是否阻断编译?答:是,处理阶段错误先于编译暴露。
  • 如何定位 KSP 慢任务?答:构建报告查看 KSP 任务耗时,区分模型构建与处理器执行。

04.8.3.2-021 SymbolProcessor 接口的核心方法是什么?

一句话结论

核心是 process(resolver: Resolver):每轮被回调,通过 resolver 查询符号,返回本轮未能处理的注解/符号列表;处理器工厂负责实例化并声明参数。

概念解释

处理器接口还包括初始化、依赖声明等生命周期方法(具体签名以当前 KSP 版本为准)。process 是主入口,Resolver 提供符号查询,CodeGenerator 提供文件写入。返回未处理列表供多轮调度判断。

原理流程

  1. 框架实例化处理器并注入环境。
  2. 每轮调用 process(resolver)。
  3. 处理器按注解过滤声明并生成代码。
  4. 返回剩余未处理符号,结束条件由框架判定。

代码或图示

class MyProcessor : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> {
        val symbols = resolver.getSymbolsWithAnnotation("com.example.Gen")
        // 生成代码
        return emptyList()
    }
}

常见误区

  • 把所有符号都当作已处理返回:未处理项丢失,后续轮次不再出现。
  • 在 process 外持有跨轮可变全局状态:轮次隔离与增量下行为不可靠。

追问

  • 处理器如何注册到 KSP?答:通过处理器工厂与服务注册机制,具体注册文件格式以 KSP 文档为准。
  • 处理器需要读取命令行参数怎么办?答:从处理器环境/选项中获取,API 形式按版本核对。

04.8.3.2-022 ProcessorEnvironment 能拿到什么信息?

一句话结论

处理器环境提供日志器、处理器选项、模块/源集信息等上下文;具体可读能力随 KSP 版本扩展,处理器不应假设能拿到完整 Project 模型。

概念解释

与 Gradle Project 不同,KSP 环境面向符号处理:记录告警/错误、读取构建传入选项、了解处理范围。处理器通过环境输出诊断,不直接操作 Gradle 任务图。

原理流程

  1. 框架初始化处理器时注入环境。
  2. 处理器通过 logger 报告信息与错误。
  3. 选项读取构建脚本传入的配置。
  4. 环境信息辅助判断处理范围。

代码或图示

override fun process(resolver: Resolver): List<KSAnnotated> {
    // environment.logger.warn("processing round")
    return emptyList()
}

常见误区

  • 在处理器里访问 Gradle Project 属性:KSP 环境不暴露完整构建模型,需通过选项显式传入。
  • 把错误打到标准输出:应走处理器日志 API,纳入构建诊断。

追问

  • 构建参数如何传给处理器?答:通过 KSP 处理器选项配置(脚本键值对),处理器从环境读取。
  • 日志错误级别如何中断构建?答:错误级别诊断通常阻断 KSP 任务,具体行为以框架实现为准。

04.8.3.2-023 KSClassDeclaration 提供哪些类型信息访问?

一句话结论

KSClassDeclaration 表示类/接口声明,可读取类名、包名、类型参数、父类型、注解声明、内部属性与函数等符号信息。

概念解释

它是 KSP 符号模型中类节点的抽象,对应源码或依赖类。访问方法返回子符号声明列表,可进一步递归遍历。可空性与类型引用通过 KSType 表达,而不是直接挂在类声明上。

原理流程

  1. Resolver 按注解或名字取到类声明。
  2. 读取 packageName、simpleName。
  3. 访问 superTypes、declaredFunctions、declaredProperties。
  4. 结合注解参数决定生成逻辑。

代码或图示

val cls: KSClassDeclaration = symbols.first()
val name = cls.simpleName.asString()
val parents = cls.superTypes.map { it.resolve() }

常见误区

  • 把类声明与类型引用混淆:声明是节点,KSType 是含可空性与参数的类型视图。
  • 遍历父类链不做环检测:层次异常时可能无限递归。

追问

  • 如何判断类是 data class/sealed class?答:通过声明的修饰符/类型信息 API 判断,具体属性名以 KSP 版本为准。
  • 泛型参数如何读取?答:类声明的 typeParameters 列表,逐个访问约束与方差。

04.8.3.2-024 KSFunctionDeclaration 与 KSPropertyDeclaration 分别读取什么?

一句话结论

前者表示函数声明,可读函数名、参数列表、返回类型、类型参数与是否挂起;后者表示属性声明,可读属性类型、可空性、可变性与注解。

概念解释

二者都是可注解的符号节点。函数签名用于生成代理/实现方法;属性信息用于生成字段、序列化映射。读取时需解析类型引用得到 KSType,并区分声明来源。

原理流程

  1. 从类声明取出函数/属性列表。
  2. 读取名称、类型与修饰符。
  3. 解析返回值/属性类型的可空性与参数。
  4. 按模板生成对应代码。

代码或图示

for (fn in cls.declaredFunctions) {
    val params = fn.parameters.map { it.name?.asString() }
    val ret = fn.returnType?.resolve()
}

常见误区

  • 忽略挂起函数标记:生成代理方法时漏改签名会导致调用不匹配。
  • 把属性 getter/setter 当普通函数重复处理:按属性声明读取即可。

追问

  • 扩展函数如何识别?答:通过函数声明的扩展属性判断,具体 API 以版本为准。
  • 私有成员是否在列表中?答:可见性修饰符保留,按声明规则读取。

04.8.3.2-025 如何按注解查找被标注的类声明?

一句话结论

通过 Resolver 按全限定注解名获取带该注解的符号列表,再过滤出 KSClassDeclaration;注解参数随后从声明的注解视图读取。

概念解释

注解可以标在类、函数、属性上。查询返回 KSAnnotated 列表,需按类型判断目标节点。注解全限定名必须与源码一致,包名写错会查不到结果。

原理流程

  1. 构造注解全限定名。
  2. resolver.getSymbolsWithAnnotation(...) 获取符号。
  3. 过滤目标声明类型。
  4. 读取注解参数并生成代码。

代码或图示

val annotated = resolver
    .getSymbolsWithAnnotation("com.example.Gen")
    .filterIsInstance<KSClassDeclaration>()

常见误区

  • 用简单类名匹配注解:必须用全限定名,避免同名注解混淆。
  • 未过滤类型直接当类声明访问:函数/属性标注会导致类型转换错误。

追问

  • 重复标注同一类多个注解怎么办?答:遍历注解视图逐个匹配目标注解。
  • 元注解(作用于注解类本身)如何处理?答:按注解声明节点查询,规则同上。

04.8.3.2-026 KSType 如何表达类型引用与可空性?

一句话结论

KSType 描述解析后的类型:含类型声明、类型参数与可空标记;可空性通过类型的 nullable 视图判断,原始类型引用与解析后类型区分使用。

概念解释

声明节点回答"是什么类",类型引用回答"变量/返回值的类型与可空性"。泛型实参挂在 KSType 上。未解析类型可能返回错误类型,处理器需做空值与错误判断。

原理流程

  1. 从函数/属性取得类型引用。
  2. resolve() 解析为 KSType。
  3. 读取可空性、类型参数与声明。
  4. 生成代码时按类型拼写对应 Kotlin 类型。

代码或图示

val type: KSType = prop.type.resolve()
val nullable = type.nullability == Nullability.NULLABLE
val args = type.arguments

常见误区

  • 未 resolve 直接读可空性:原始引用与解析类型含义不同。
  • 忽略错误类型:解析失败时类型视图不可用,应记录诊断并跳过。

追问

  • 平台类型如何表示?答:按 KSP 可空性分类处理,平台类型不等同于非空,生成代码需保守。
  • 泛型通配符怎么读?答:类型参数的 variance 与实参类型组合判断。

04.8.3.2-027 如何解析父类型与实现接口?

一句话结论

类声明的 superTypes 给出父类型引用列表,逐条 resolve 后读取其声明与泛型实参;沿层次向上遍历需做访问与环检测。

概念解释

生成代理/适配器时常需知道类实现了哪些接口、继承哪个抽象类。父类型列表包含超类与接口;解析后可继续访问父类声明的成员。跨模块父类信息来自依赖符号模型。

原理流程

  1. 读取 cls.superTypes。
  2. 逐条 resolve 为 KSType 与 KSClassDeclaration。
  3. 判断是类还是接口,收集需要的方法签名。
  4. 必要时向上遍历父类链。

代码或图示

val interfaces = cls.superTypes.map { it.resolve().declaration }
    .filterIsInstance<KSClassDeclaration>()

常见误区

  • 只看直接父类忽略继承链:父类方法可能是生成目标。
  • 遍历父类不防环:异常层次下递归不终止。

追问

  • 如何判断某个接口被实现?答:解析父类型声明的全限定名做匹配。
  • 泛型父类实参如何保留?答:从父类型 KSType 的 arguments 读取并映射到生成代码。

04.8.3.2-028 处理器如何生成文件(CodeGenerator)?

一句话结论

通过代码生成器按包名与文件名创建源文件或资源,写入生成内容;生成器处理目录归属与重名登记,处理器只提供内容文本或生成模型。

概念解释

生成 API 区分 Kotlin/Java 源码与资源。文件内容通常由模板字符串拼接,复杂模型可借助生成器的类型辅助。生成文件在后续轮次/编译中可见。

原理流程

  1. 处理器确定包名、类名与内容。
  2. 调用生成器创建对应类型文件。
  3. 写入源码/资源内容。
  4. 框架登记产物供编译任务纳入。

代码或图示

// 生成调用骨架(API 名称以当前 KSP 版本为准)
codeGenerator.createNewFile(
    dependencies = Dependencies(aggregating = true),
    packageName = "com.example.gen",
    fileName = "UserMapper"
).bufferedWriter().use { it.write(generatedSource) }

常见误区

  • 生成内容不做转义/模板校验:类名、字符串拼接出错导致生成源码编译失败。
  • 不声明生成依赖:增量下生成文件可能未随源变更更新。

追问

  • 生成类命名冲突如何避免?答:约定后缀(如 Impl、Mapper),并检查同包同类名。
  • 生成资源文件走哪个 API?答:代码生成器区分源码与资源入口,具体以文档为准。

04.8.3.2-029 处理器应生成 Kotlin 还是 Java 代码?

一句话结论

面向 Kotlin 消费方优先生成 Kotlin 代码,可保留可空性与协程类型;只有当产物需被纯 Java 模块或旧框架消费时,才评估生成 Java 代码。

概念解释

KSP 模型是 Kotlin 感知的,生成 Kotlin 最直接。生成 Java 需处理 Kotlin 类型到 Java 签名的映射,可空性与挂起函数表达受限。生成物语言应与消费方技术栈一致。

原理流程

  1. 确认生成代码被谁消费。
  2. Kotlin 消费:按 Kotlin 语法模板生成。
  3. Java 消费:映射签名为 Java 兼容形式。
  4. 编译期验证生成代码可编译。

代码或图示

// Kotlin 生成目标示例
class UserMapperImpl : UserMapper {
    override fun toDomain(row: Row): User = TODO()
}

常见误区

  • 生成 Kotlin 类却用 Java 平台类型假设:可空性处理不严谨。
  • 在 Java 产物中暴露挂起函数:需映射为回调签名,复杂度高。

追问

  • 混合消费方怎么选?答:以主要调用方语言为准,必要时生成两层适配。
  • 生成代码风格由谁保证?答:处理器模板负责命名与格式,静态分析可对生成目录做豁免配置。

04.8.3.2-030 处理器之间的依赖与执行顺序如何确定?

一句话结论

多个处理器在同一 KSP 运行中按注册顺序依次处理,多轮模型衔接生成与读取;处理器间需要显式产物依赖时,应通过生成文件与轮次约定,避免依赖隐式顺序。

概念解释

处理器 A 生成的类可被处理器 B 在下一轮读取。执行顺序由注册/加载顺序决定,但跨处理器契约应显式化:B 不应假设 A 的内部实现,只依赖其生成产物命名约定。

原理流程

  1. 框架按注册顺序加载处理器。
  2. 每轮各处理器依次处理当前符号集合。
  3. 生成产物进入后续轮次。
  4. 依赖关系通过生成文件声明记录。

代码或图示

Processor A 生成 X.kt ──▶ Round 2 ──▶ Processor B 读取 X

常见误区

  • 处理器间靠静态可变对象传递数据:轮次隔离下不可靠。
  • 未登记生成依赖:增量构建时 A 的产物可能未及时更新给 B。

追问

  • 如何强制两个处理器先后执行?答:按注册顺序配置,并通过多轮产物衔接;框架级排序能力以 KSP 文档为准。
  • 处理器冲突重复生成同名类怎么办?答:命名规则区分职责,构建期检测重名。

04.8.3.2-031 如何判断一轮处理是否结束(rounding)?

一句话结论

每轮处理器返回未处理的符号集合;当一轮没有新生成符号、也没有待处理注解时,KSP 结束处理流程,进入编译阶段。

概念解释

结束判定由框架根据本轮新增产物与剩余待处理符号综合判断。处理器正确返回未处理项,避免框架误判还有工作。无限生成循环会被框架按轮次限制终止并报错。

原理流程

  1. 本轮处理器执行并生成文件。
  2. 返回剩余未处理符号。
  3. 框架检查是否存在新增符号/待处理注解。
  4. 无新增则结束,否则进入下一轮。

代码或图示

override fun process(resolver: Resolver): List<KSAnnotated> {
    val (matched, rest) = symbols.partition { it is KSClassDeclaration }
    // 处理 matched
    return rest // 未处理项交还框架
}

常见误区

  • 总是返回空列表:实际未处理符号被丢弃,后续不再出现。
  • 每轮生成等价新文件:触发多余轮次,拖慢处理。

追问

  • 出现处理轮次过多告警怎么排查?答:检查处理器是否每轮重复生成同类文件,收敛生成条件。
  • 最后一轮生成的代码谁来编译?答:KSP 结束后全部生成源码交 Kotlin 编译任务。

04.8.3.2-032 KSPLogger 如何报告错误与告警?

一句话结论

处理器通过日志 API 输出 info/warn/error 诊断;error 级别通常中断 KSP 任务,告警进入构建报告。日志应包含被处理符号定位信息便于回溯。

概念解释

日志替代直接打印标准输出,纳入 Gradle 构建诊断。报告错误时带上类名/位置,帮助定位源码。处理器不应把可恢复的类型不确定打成致命错误,需分级处理。

原理流程

  1. 处理器在读取/生成过程中发现问题。
  2. 按严重级别调用 logger 方法。
  3. warn 进入报告继续流程,error 阻断任务。
  4. 构建输出展示诊断与符号位置。

代码或图示

logger.error("@Gen 只能标注在类上:${cls.simpleName.asString()}")

常见误区

  • 用 println 输出诊断:不走构建日志体系,CI 中难以聚合。
  • 类型读取失败只告警不跳过:后续生成可能产出非法源码。

追问

  • 日志能否关联源码位置?答:符号通常携带位置信息,logger 支持位置参数的 API 以版本为准。
  • 处理器告警如何在 CI 门禁统计?答:纳入构建输出分析,具体规则按团队 CI 配置。

04.8.3.2-033 处理器读取源文件内容有哪些限制?

一句话结论

处理器基于符号模型读取声明与签名,不解析方法体实现逻辑;需要源码文本时能力受限,应避免把生成决策建立在方法体语句上。

概念解释

KSP 暴露结构信息(声明、类型、注解),不提供语句级 AST 遍历。方法体内的局部逻辑不可见。生成框架通常基于签名约定(接口、注解、属性)工作,不读实现体。

原理流程

  1. 符号模型提供声明节点。
  2. 节点暴露签名、类型、注解。
  3. 方法体语句不进入模型。
  4. 处理器按结构信息生成代码。

代码或图示

可读:类/函数/属性签名、注解、类型参数
不可读:函数体内的语句与局部变量实现

常见误区

  • 想在处理器里分析方法体做代码改写:应考虑编译器插件而非 KSP。
  • 依赖私有局部命名生成代码:局部信息不可见,生成不稳定。

追问

  • 注解参数里的字符串常量可读吗?答:可读注解元素值,这属于声明级信息。
  • 需要读取完整源码文件怎么办?答:符号模型不提供时,评估其他工具链;KSP 定位是结构处理。

04.8.3.2-034 泛型类型参数在 KSP 中如何解析?

一句话结论

类与函数声明持有类型参数列表,每个参数含名字、方差与上界;使用处的 KSType 携带实参类型,处理器需把声明参数与实参对应起来映射到生成代码。

概念解释

泛型声明(如 class Repository<T : Entity>)与泛型使用(Repository<User>)分别建模。生成实现类时要保留类型参数或填充实参。上界约束决定类型可调用的成员。

原理流程

  1. 读取声明的 typeParameters。
  2. 读取使用处 KSType.arguments 实参。
  3. 映射参数名到生成模板。
  4. 校验上界约束满足情况。

代码或图示

for (typeParam in cls.typeParameters) {
    val bounds = typeParam.bounds.map { it.resolve() }
}

常见误区

  • 生成代码丢掉类型参数:实现类签名与原接口不一致,编译报错。
  • 实参为通配符时按具体类型处理:需区分 variance 与星投影。

追问

  • 星投影在类型视图中如何表示?答:按类型参数实参的占位标识判断,具体 API 以版本为准。
  • 递归泛型(自引用上界)如何处理?答:沿类型解析链读取,注意环与边界。

04.8.3.2-035 注解参数如何读取?

一句话结论

从声明的注解视图取得参数值,按类型读取字符串、布尔、枚举、类引用与嵌套数组;类引用进一步解析为符号类型。

概念解释

注解元素在 KSP 中以类型化视图提供,默认值与未显式设置需区分。类类型参数解析后可得 KSClassDeclaration;数组参数遍历逐项读取。读取失败要降级处理并记录诊断。

原理流程

  1. 找到目标注解视图。
  2. 按元素名取值并转换类型。
  3. 类引用参数 resolve 为声明。
  4. 参数值参与生成模板。

代码或图示

val annotation = cls.annotations.first {
    it.shortName.asString() == "Gen"
}
val mode = annotation.arguments
    .first { it.name?.asString() == "mode" }
    .value

常见误区

  • 直接把注解值当字符串拼接:类引用、数组类型需按对应 API 读取。
  • 忽略参数默认值:未显式设置时取声明默认值而非 null。

追问

  • 重复值注解(数组元素)怎么读?答:参数值为列表,逐项遍历类型化读取。
  • 注解类本身在依赖 jar 中可见吗?答:注解类型来自编译 classpath,需保证注解定义库在依赖中。

04.8.3.2-036 处理器对 sealed、inline、value class 的可见性如何?

一句话结论

这些声明在符号模型中以对应修饰符/种类标记可见,处理器可识别其类型特征;但生成代码需遵守其语言约束(如 value class 包装规则、sealed 子类层次),否则生成源码编译失败。

概念解释

KSP 保留声明种类与修饰符:sealed 标记、inline/value 标识等。处理器读取这些信息决定生成策略。部分特殊声明在 Java 桩(kapt)下映射受限,KSP 下保真度更高,但具体 API 字段名以版本为准。

原理流程

  1. 读取类声明的种类与修饰符。
  2. 识别 sealed/inline/value 等特征。
  3. 按对应语言约束生成适配代码。
  4. 生成代码通过编译期类型检查。

代码或图示

sealed class 层次:可读取直接子类声明
value class:读取包装值属性,生成时遵守内联类约束

常见误区

  • 给 value class 生成普通包装字段:违反内联类规则,编译报错。
  • 忽略 sealed 子类封闭性:生成跨越层次的引用需谨慎。

追问

  • sealed 子类在同一模块其他文件中可见吗?答:同一编译单元内符号模型可见,跨模块受可见性限制。
  • 遇到不支持的声明类型如何处理?答:记录错误诊断并跳过生成,不要强行套用模板。

04.8.3.2-037 生成类的包名与命名冲突如何避免?

一句话结论

生成类包名通常基于被标注类包名加约定后缀(如 .gen),类名加固定后缀;同包重名由框架登记检测,处理器应在生成前做命名约定检查。

概念解释

稳定的命名规则让业务代码可引用生成类,也避免与手写类冲突。后缀选择应表达生成职责(Impl、Mapper、Serializer 等)。处理器不应随机命名或依赖源码顺序决定类名。

原理流程

  1. 取被标注类包名与简单名。
  2. 按约定拼接生成包名与类名。
  3. 生成器登记文件名,重名时报冲突。
  4. 业务代码按约定名字引用。

代码或图示

com.example.User  →  com.example.gen.UserMapperImpl

常见误区

  • 生成类与手写类同名同包:编译期类冲突,需改后缀约定。
  • 包名随处理器配置漂移:跨模块引用生成类时代码耦合路径不稳定。

追问

  • 多个注解生成同一类怎么办?答:按职责区分后缀,或一个处理器聚合生成。
  • 生成内部类还是顶层类?答:按框架约定选择;顶层类更易被其他文件引用。

04.8.3.2-038 KSP 处理器如何做单元测试?

一句话结论

用 KSP 测试框架构造最小编译工程与样例源码,运行处理器后断言生成文件内容、符号查询结果与日志诊断;不依赖完整业务工程即可回归。

概念解释

处理器逻辑分为符号读取与代码模板两部分。测试框架提供模拟编译环境,输入样例类/注解,收集 KSP 产物。测试覆盖正常生成、缺注解、类型不匹配等分支。

原理流程

  1. 准备样例源码与注解定义。
  2. 在测试环境运行处理器。
  3. 收集生成文件与诊断信息。
  4. 断言类名、字段、方法签名与错误输出。

代码或图示

测试输入:@Gen class Sample(...)
运行处理器 → 断言 SampleGen.kt 内容符合模板

常见误区

  • 只测模板字符串不测符号读取:类型解析分支未覆盖。
  • 测试依赖磁盘上的真实工程:环境迁移后不稳定。

追问

  • 测试框架提供哪些能力?答:编译样例源码、调用处理器、读取生成产物;具体 API 以 KSP 测试库文档为准。
  • 生成代码编译正确性如何验证?答:测试中对生成源码再做一次编译校验,避免产出非法 Kotlin。

04.8.3.2-039 KSP 处理器如何声明增量隔离?

一句话结论

处理器通过生成依赖声明记录读取的符号与产出文件关系,使增量分析能判断哪些产物需随源码变更更新;声明方式按 KSP 当前 API(聚合型/隔离型依赖)为准。

概念解释

KSP 增量依赖模型区分"聚合全部符号"与"按符号隔离"。处理器只读取局部符号时应声明细粒度依赖;遍历全量则退化为聚合型,变更波及整个处理器产物。

原理流程

  1. 生成文件时声明依赖的符号集合。
  2. 变更分析按映射判断受影响产物。
  3. 隔离良好的处理器只更新对应生成文件。
  4. 聚合声明下相关产物整体重生成。

代码或图示

// 生成文件时附带依赖声明(API 形态以当前版本为准)
Dependencies(aggregating = false, sources = listOf(cls))

常见误区

  • 读取了符号却不声明依赖:增量下产物过期不更新。
  • 处理器整体聚合却期待细粒度增量:能力与声明不匹配。

追问

  • 如何检查处理器增量行为?答:改单个样例类,观察只更新对应生成文件。
  • 隔离型处理器有何限制?答:不能跨符号全局汇总信息,需按框架模型设计。

04.8.3.2-040 处理器性能上有哪些注意点?

一句话结论

避免遍历全量符号做重复查询,缓存可复用的符号解析结果,控制生成代码量与字符串拼接;大模块下处理器自身遍历往往是 KSP 阶段主要耗时。

概念解释

Resolver 查询有成本,重复按名查找、反复 resolve 类型会放大开销。处理器应在一轮内组织好符号集合,减少重复遍历。生成大量文件时模板与 IO 也是开销来源。

原理流程

  1. 一轮内一次性取出目标注解符号。
  2. 类型解析结果按需缓存。
  3. 模板按模型批量生成。
  4. 构建报告核对处理器耗时分布。

代码或图示

优化:单次查询 → 分组处理 → 批量生成
避免:循环内反复按名查找、重复 resolve 同一类型

常见误区

  • 在每个函数/属性处理时重新查询全局符号集:复杂度随规模上升。
  • 生成未使用的辅助代码:产物膨胀,编译与打包变慢。

追问

  • 如何定位处理器慢在哪一步?答:在处理器内分段计时或看构建报告,区分查询、解析与生成。
  • 符号模型占用内存过大怎么办?答:缩小处理范围,避免保留无关符号引用。

04.8.3.2-041 kapt 的 stub 生成完整流程是怎样的?

一句话结论

kapt 先解析 Kotlin 源码编译出类签名模型,再为每个 Kotlin 类生成 Java 桩源(含包名、方法签名、字段与注解),交给 javac 启动注解处理,桩不进入最终产物。

概念解释

桩生成要把 Kotlin 签名翻译为 Java 兼容形式:挂起函数加 Continuation 参数、可空性转注解/平台类型、泛型映射为 Java 泛型。翻译完成后 javac 处理器在桩上按 JSR-269 工作。

原理流程

  1. KGP 注册 kapt 任务,输入 Kotlin 源码。
  2. 解析签名并生成桩视图。
  3. javac 加载桩并运行注册的注解处理器。
  4. 处理器生成源码,桩丢弃,交回 Kotlin 编译。

代码或图示

Kotlin 源码 → 签名解析 → Java stub → javac 注解处理 → 生成源码 → Kotlin 编译

常见误区

  • 以为桩是手写或缓存的源码:桩由编译器按签名动态生成。
  • 桩生成慢只归因于处理器:翻译阶段本身就有解析成本。

追问

  • 桩生成产物落盘吗?答:在构建目录的 kapt 中间目录中,属于生成物,不入库。
  • 桩包含方法体吗?答:不包含,只有签名供处理器读取。

04.8.3.2-042 kapt 的增量编译有哪些限制?

一句话结论

kapt 的增量粒度较粗:桩生成与 javac 处理链常按较大范围失效,单文件改动可能触发相关包甚至模块重新走 kapt 流程;增量能力不及 KSP。

概念解释

跨语言桩模型使变更分析难以精确到符号级。KGP 提供的 kapt 增量优化受桩映射与 javac 处理限制。工程实践中 kapt 阶段在热构建下仍明显耗时,这是迁移 KSP 的主要动因之一。

原理流程

  1. 检测源码变更。
  2. kapt 判断受影响桩集合(粒度较粗)。
  3. 重新生成桩并跑 javac 处理。
  4. 生成源码并入编译。

代码或图示

KSP:符号级增量
kapt:桩级/包级粗粒度增量

常见误区

  • 期待 kapt 达到 KSP 的增量速度:架构限制下收益有限。
  • 把 kapt 慢当作机器问题:先确认增量是否生效与处理器遍历范围。

追问

  • kapt 增量开关有哪些配置?答:以 KGP 文档中的 kapt 增量选项为准,不确定处标待确认。
  • 大模块 kapt 优化手段?答:迁移 KSP、减少处理器扫描范围、隔离生成类库。

04.8.3.2-043 kapt 如何处理挂起函数?

一句话结论

挂起函数在桩中映射为普通 Java 方法,末尾追加 Continuation 参数并返回 Object 风格签名;注解处理器看到的是回调形式,无法直接识别 suspend 语义。

概念解释

Java 没有挂起概念,kapt 按字节码签名规则映射:suspend 函数编译后本就带 Continuation 参数,桩沿用该视图。处理器若要区分挂起函数,需依赖 Kotlin 元数据或签名特征,稳定性有限。

原理流程

  1. 解析 Kotlin 挂起函数签名。
  2. 追加 Continuation 形参,返回类型映射为 Java 兼容类型。
  3. 桩方法暴露给 javac 处理器。
  4. 生成代码如需协程签名要额外适配。

代码或图示

// Kotlin
suspend fun load(id: Long): User

// 桩视图(示意)
Object load(long id, Continuation<User> cont);

常见误区

  • 在 kapt 处理器里可靠识别 suspend 标记:桩语义有损,识别结果需实测。
  • 生成 Java 代理直接调用挂起函数:需按 Continuation 回调写适配。

追问

  • KSP 下挂起函数识别如何?答:符号声明保留 suspend 修饰标记,处理器可直接读取。
  • 挂起函数生成代理类注意什么?答:代理方法签名需与原函数协程模型一致,避免阻塞调用方。

04.8.3.2-044 kapt 为什么内存占用通常更高?

一句话结论

kapt 同时维护 Kotlin 解析模型、Java 桩模型与 javac 处理环境,两套模型并存;加上处理器与生成代码加载,内存峰值高于纯 KSP 链路。

概念解释

桩生成阶段保留 Kotlin 签名信息,javac 阶段又构建 Java 符号表。处理器自身依赖也进入 kapt 类加载。大模块下堆不足会表现为 kapt 任务 OOM 或频繁 GC。

原理流程

  1. Kotlin 解析构建签名模型。
  2. 桩模型与 javac 符号表并存。
  3. 处理器及其依赖加载进处理进程。
  4. 生成代码占用额外内存。

代码或图示

kapt 内存 ≈ Kotlin 模型 + Java 桩模型 + javac 环境 + 处理器与生成代码

常见误区

  • 只加业务测试 JVM 内存:kapt 处理进程内存需单独评估配置。
  • 以为内存高是泄漏:多模型并存是结构性占用。

追问

  • kapt OOM 怎么调?答:按 KGP 文档调整 kapt 进程内存参数;长期方案仍是迁移 KSP。
  • 内存参数名随版本变化吗?答:以当前 KGP 文档为准,不写死未经验证的属性名。

04.8.3.2-045 kapt 处理器能否访问 Kotlin 私有成员?

一句话结论

桩按 Kotlin 可见性生成对应 Java 视图,私有成员不对外暴露;处理器不应假设能读取私有实现细节,访问受限成员在桩模型中不可见。

概念解释

可见性是声明级属性,kapt 在桩中保留访问修饰符。处理器处理的是类公开/受保护签名。需要读取内部结构的场景应重新评估注解位置与框架设计。

原理流程

  1. Kotlin 解析保留成员可见性。
  2. 桩按可见性映射 Java 修饰符。
  3. javac 处理器按 Java 可见性规则读取。
  4. 私有成员不在处理器可见范围。

代码或图示

private val secret: String  → 桩中 private,处理器不可见

常见误区

  • 用反射在处理器期访问私有成员:处理期无实例,反射不可行且违反可见性约定。
  • 把内部成员当生成依据:设计上应提升可见性或改用公开签名约定。

追问

  • 内部类/嵌套类可见性如何映射?答:按 Java 嵌套类修饰符规则映射,具体以桩输出为准。
  • 注解标在私有属性上能被处理吗?答:取决于注解目标与可见性规则,实测桩中是否出现。

04.8.3.2-046 kapt 与 Java 注解处理器如何互通?

一句话结论

kapt 直接复用 JSR-269 处理器:处理器 jar 加入 kapt configuration,javac 在桩模型上调用其 Processor 实现,处理器代码无需为 Kotlin 改造。

概念解释

这是 kapt 存在的核心价值:存量 Java 注解处理生态(Auto 系列、Dagger 等)可直接用于 Kotlin 工程。互通限制只来自桩模型的信息有损,处理器本身按 Java API 编写。

原理流程

  1. 处理器坐标加入 kapt(...) 配置。
  2. kapt 生成桩后启动 javac。
  3. javac 发现并加载注册的 Processor。
  4. 处理器读桩生成代码,流程与纯 Java 工程一致。

代码或图示

dependencies {
    kapt("com.google.dagger:dagger-compiler") // 坐标与版本以官方当前版本为准
}

常见误区

  • 把 Java 处理器加到 KSP configuration:加载链不同,不生效。
  • 期待 Java 处理器理解 Kotlin 语义:它只看到桩视图。

追问

  • 处理器服务注册文件需要保留吗?答:需要,javac 通过 SPI 清单发现处理器。
  • 多个 Java 处理器顺序如何?答:按 javac 处理轮次与注册规则,与纯 Java 工程一致。

04.8.3.2-047 kapt 有哪些运行模式?

一句话结论

kapt 可配置为完整运行注解处理,或仅生成桩供调试/排查;模式与增量、校验选项由 KGP 配置控制,具体开关名以当前版本文档为准。

概念解释

排查桩生成问题时可单独观察桩输出;完整模式下桩与处理器串联执行。部分选项控制是否校验桩类型、是否启用增量。模式选择影响 kapt 阶段耗时与产物范围。

原理流程

  1. 配置 kapt 运行选项。
  2. 按模式生成桩、调用处理器或仅输出桩。
  3. 产物进入后续编译。
  4. 调试时检查中间桩目录。

代码或图示

完整模式:桩生成 + 注解处理 + 生成源码
调试模式:观察桩内容与映射结果

常见误区

  • 把调试模式配置留在生产构建:可能跳过必要的处理步骤。
  • 依赖未文档化的内部开关:版本升级后行为可能变化。

追问

  • 如何查看生成的桩?答:检查构建目录下 kapt 中间输出;路径以 KGP 版本为准。
  • kapt 校验严格度可调吗?答:按 KGP 提供的选项调整,不确定项标待确认。

04.8.3.2-048 kapt 慢主要慢在哪些环节?

一句话结论

主要耗时在 Kotlin 签名解析与桩生成、javac 启动与符号表构建、处理器遍历与生成代码;相比 KSP 多出跨语言模型转换与两轮解析。

概念解释

定位 kapt 慢要拆分阶段:桩生成是固定成本,处理器扫描是可变成本。大模块、处理器多、生成代码量大时各环节叠加。优化先测量再决定迁移还是裁剪处理器。

原理流程

  1. 构建报告拆分 kapt 任务各阶段耗时。
  2. 桩生成占比高:架构性成本,考虑 KSP。
  3. 处理器扫描占比高:优化处理器遍历范围。
  4. 生成代码多:评估是否减少生成量。

代码或图示

kapt 耗时 = 桩生成 + javac 环境 + 处理器执行 + 代码生成

常见误区

  • 把 kapt 整体慢归为机器性能:结构性成本换机器无法消除。
  • 不测量就盲目加内存:GC 占比不高时加堆收益有限。

追问

  • 迁移 KSP 后桩生成环节还在吗?答:不在,KSP 直接读符号模型。
  • 如何对比两个链路耗时?答:同一模块分别跑 kapt 与 KSP,对比任务时间与冷/热构建。

04.8.3.2-049 从 kapt 迁移 KSP 的常见阻塞点是什么?

一句话结论

阻塞点主要是目标库没有 KSP 处理器版本、处理器依赖 javac 专有 API、桩中可映射的 Kotlin 语义在 KSP 模型中需重新适配,以及生成代码链路回归验证。

概念解释

迁移顺序通常是:有 KSP 支持的库先切,仅 kapt 的保留;内部处理器按 KSP API 重写。迁移后需回归生成类编译、运行行为与增量效果。兼容窗口内两套链路可能短期并存。

原理流程

  1. 盘点工程 kapt 依赖与处理器。
  2. 按官方支持状态分组:可迁移 / 待生态 / 自研。
  3. 切换配置并修复处理器 API 适配。
  4. 全量回归生成代码与测试。

代码或图示

盘点 → 切有 KSP 的库 → 重写自研处理器 → 回归编译/测试/增量 → 移除 kapt

常见误区

  • 一次性全部切换:生态不支持的库会阻断编译,应分批。
  • 迁移后不对比生成代码:行为差异可能到运行期才暴露。

追问

  • 迁移中两套配置并存有何风险?答:构建时间翻倍、产物可能重复,过渡期尽量短。
  • 如何判断库 KSP 支持是否就绪?答:查库发布说明与坐标;版本能力不确定标待确认。

04.8.3.2-050 K2 编译器下 kapt 的维护状态如何?

一句话结论

K2 前端重写后,kapt 对新编译器的支持范围有限制,官方方向是 KSP 承接 Kotlin 代码生成;具体哪些 kapt 场景在 K2 下可用需以官方文档为准,标待确认并实测。

概念解释

kapt 依赖编译器内部签名导出能力,K2 重构后该适配需要持续跟进。新项目不应再以 kapt 为主要处理链;存量 kapt 在升级 Kotlin 大版本前先核对官方兼容说明。

原理流程

  1. 升级 Kotlin 到 K2 前查 kapt 兼容说明。
  2. 评估现有 kapt 处理器是否在支持范围内。
  3. 可迁移的切 KSP,受限场景暂缓升级或保留兼容版本。
  4. 构建期观察 kapt 任务警告与错误。

代码或图示

K2 升级前:核对 kapt 支持范围 → 迁移 KSP / 暂缓升级

常见误区

  • 假设 kapt 在 K2 下行为与旧前端完全一致:签名导出与处理链可能有差异。
  • 长期锁定旧 Kotlin 版本保留 kapt:技术债随版本差距扩大。

追问

  • 哪里查 kapt 对 K2 的支持状态?答:Kotlin 官方兼容说明与 K2 迁移文档;本项标待确认,升级前复核。
  • KSP2 是否就是 K2 的配套方案?答:是面向新前端的 KSP 版本线,详见 KSP 发布说明。

04.8.3.2-051 Kotlin 编译器插件是什么,加载在哪一层?

一句话结论

编译器插件是挂接在 Kotlin 编译器内部阶段的扩展,可在解析、IR 构建或字节码生成环节参与处理;与注解处理不同,它能改写已有类的中间表示。

概念解释

典型插件包括序列化代码生成、Composable 转换、allopen/noarg 字节码/声明调整。插件由 KGP 在编译任务中按配置加载,作用于编译器内部管线。插件能力受编译器版本与前端(K1/K2)约束。

原理流程

  1. 编译任务按脚本配置加载插件。
  2. 插件挂接到编译器对应阶段。
  3. 在 IR 或声明层做生成/改写。
  4. 输出字节码合并到产物。

代码或图示

源码 → 前端解析 → [插件挂载点] → IR → 后端字节码 → class

常见误区

  • 把编译器插件与 KSP 处理器混为一谈:前者改写/参与编译内部,后者产出独立源文件。
  • 以为插件跨 Kotlin 版本随意升级:插件绑定编译器内部 API,需配套版本。

追问

  • 插件由谁提供?答:官方随 Kotlin 发布(序列化等)或第三方提供;坐标以官方文档当前版本为准。
  • 插件能访问运行期信息吗?答:插件在编译期工作,只基于编译可见的源码与元数据。

04.8.3.2-052 编译器插件与注解处理器的分工是什么?

一句话结论

注解处理(KSP/kapt)产出新源文件、不改写原类;编译器插件可在 IR 层改写已有类的方法实现、调整声明形态,两者解决不同问题。

概念解释

生成独立实现类适合代理/映射场景;需要给原类加默认构造、打开类继承、转换组合函数等场景由插件完成。实际框架常组合使用:插件调整编译形态,处理器生成辅助类。

原理流程

  1. 判断需求:新增类 → 注解处理;改写既有类/方法 → 编译器插件。
  2. 处理器生成源码并入编译。
  3. 插件在编译管线中作用于 IR。
  4. 最终字节码包含两者产物。

代码或图示

KSP/kapt:新增 *.kt 源文件
IR 插件:修改原类 IR / 字节码形态

常见误区

  • 想用 KSP 给原类加方法:KSP 只能生成新类,改写归插件。
  • 把所有生成需求都做成 IR 插件:开发与维护成本高,优先生成新类方案。

追问

  • 一个框架能同时用两种机制吗?答:可以,按职责组合,如插件调整开放度、处理器生成实现。
  • 插件改写如何在调试时观察?答:反编译最终字节码或查看插件报告,确认 IR 变换结果。

04.8.3.2-053 IR 插件工作在编译器的哪个阶段?

一句话结论

IR(中间表示)插件在前端生成 IR 之后、后端产出字节码之前介入,遍历并变换 IR 树,可替换方法体、新增指令或调整声明。

概念解释

Kotlin 编译器先把源码翻译为 IR,再由后端生成字节码/原生代码。IR 插件操作这棵中间树,比改 AST 更接近最终产物。IR 结构随编译器版本演进,插件 API 稳定性需关注。

原理流程

  1. 前端解析源码构建 IR。
  2. IR 插件按规则遍历节点。
  3. 变换方法体/声明/表达式。
  4. 后端基于变换后 IR 生成字节码。

代码或图示

源码 → AST → IR ──IR 插件变换──▶ 后端 → 字节码

常见误区

  • 以为 IR 插件直接写字节码:它改 IR 树,字节码由后端生成。
  • 忽略 K2 下 IR 变化:插件可能需要适配新前端的 IR 结构。

追问

  • 自定义 IR 插件开发门槛高吗?答:需要理解编译器 IR 结构与插件 API,成本高于 KSP 处理器。
  • 官方插件也是 IR 插件吗?答:序列化等通过编译器插件机制接入,具体实现层以官方文档为准。

04.8.3.2-054 编译器插件如何在 Gradle 构建中注册?

一句话结论

通过 KGP 提供的插件配置入口应用对应编译器插件,插件随编译任务加载;常见形式是 plugins{} 应用配套 Gradle 插件或在 kotlin 扩展中启用编译器选项。

概念解释

官方插件通常对应一个 Gradle 插件 id 或编译器选项开关。注册后编译任务把插件类加入编译器 classpath。插件版本与 Kotlin 编译器版本配套,不单独随意升级。

原理流程

  1. 构建脚本应用插件或开启选项。
  2. KGP 把插件加入编译配置。
  3. 编译进程加载插件并挂接阶段。
  4. 编译时执行变换。

代码或图示

plugins {
    kotlin("jvm")
    id("org.jetbrains.kotlin.plugin.serialization") // 插件 id 以官方当前版本为准
}

常见误区

  • 只加运行期序列化库依赖、不应用编译器插件:编译期生成器缺失,运行期报错。
  • 插件版本与 Kotlin 版本错位:编译期插件加载失败。

追问

  • 插件在多平台工程如何注册?答:按 KMP 插件机制在对应目标配置,具体以官方文档为准。
  • 如何确认插件已生效?答:编译产物中出现生成器/变换结果,或编译日志显示插件加载。

04.8.3.2-055 Compose 编译器插件做什么?

一句话结论

Compose 编译器插件把 @Composable 函数转换为带状态跟踪与重组调度信息的字节码,记录调用依赖、支持跳过与重组;本节从通用编译机制视角说明,Android/端侧场景见 07 分册。

概念解释

Compose 不是单纯库:编译器插件为组合函数插入分组、变更跟踪等元信息,运行期据此判断哪些函数需要重组。插件版本与 Kotlin 编译器版本严格配套。后端 JVM 场景一般不引入该插件。

原理流程

  1. 标注 @Composable 的函数进入插件处理范围。
  2. 插件在 IR 层插入分组与状态读取跟踪。
  3. 生成带重组元信息的字节码。
  4. 运行期组合调度器依据元信息执行。

代码或图示

@Composable fun Greeting(name: String)
  → 插件插入分组/依赖跟踪 → 可被重组调度

常见误区

  • 以为只靠 Compose 运行库就能工作:编译器转换是必要环节。
  • 后端服务引入 Compose 插件:无组合 UI 场景,增加构建与兼容负担。

追问

  • Compose 插件版本如何对齐?答:按官方配套表选择与 Kotlin 版本对应的编译器插件版本。
  • 插件报错常见于什么情况?答:Kotlin 与插件版本不配套、组合函数签名违反约束。

04.8.3.2-056 kotlinx-serialization 编译器插件的职责是什么?

一句话结论

序列化编译器插件为 @Serializable 类在编译期生成序列化器(KSerializer)实现,避免运行期反射扫描字段;运行期库负责编码解码。

概念解释

插件读取可序列化类的属性、类型与注解,生成对应的 serialize/deserialize 代码。运行期 kotlinx-serialization-json 库使用这些生成器。插件必须与编译器版本配套。

原理流程

  1. 类标注 @Serializable。
  2. 插件在编译期为其生成序列化器类。
  3. 运行期调用生成器读写结构。
  4. 嵌套类、泛型按生成器组合处理。

代码或图示

@Serializable
data class Order(val id: Long, val item: String)
// 编译期生成 Order.serializer() 对应的序列化器

常见误区

  • 只引运行期库不应用插件:编译期无生成器,运行期报序列化器缺失。
  • 把序列化生成当作反射:生成代码在编译期产出,运行期不扫描字段。

追问

  • 自定义类型如何参与序列化?答:为其提供序列化器(插件生成或手写),并在字段上引用。
  • 序列化插件与 KSP 是一回事吗?答:不是,它是编译器插件,在编译管线内生成代码。

04.8.3.2-057 allopen 插件的作用是什么?

一句话结论

allopen 插件让指定注解标注的类与成员在编译期变为 open(可继承/可覆写),解决 Kotlin 默认 final 类被框架代理继承的问题。

概念解释

Kotlin 类默认 final,依赖继承代理的框架(如部分 DI/AOP)需要类可开放。allopen 按注解标记在编译期调整类/成员开放性,源码仍写默认 final,字节码层面变为 open。

原理流程

  1. 配置 allopen 关联的注解。
  2. 编译期扫描标注类。
  3. 插件在 IR/字节码层把类与成员改为 open。
  4. 框架代理可继承该类。

代码或图示

// 配置示意(具体 DSL 以官方文档为准)
allOpen {
    annotation("com.example.OpenForProxy")
}

常见误区

  • 以为 allopen 改变源码可见性:只影响编译产物字节码形态,源码仍按 Kotlin 声明。
  • 给不需要代理的类开放:扩大继承面,按需按注解标记。

追问

  • allopen 与 Spring 代理关系?答:需要类被 CGLIB 子类化时,用 allopen 按框架注解开放;具体框架要求以其文档为准。
  • allopen 插件随哪个插件提供?答:Kotlin 官方 Gradle 插件生态提供,配置入口以当前文档为准。

04.8.3.2-058 noarg 插件的作用是什么?

一句话结论

noarg 插件为标注类生成无参构造函数,满足框架反射实例化时需要默认构造的要求,类源码不必手写空构造。

概念解释

很多 JVM 框架通过无参构造反射创建对象。Kotlin data class/普通类若无必填属性,默认没有无参构造。noarg 按注解在编译期合成该构造,字段在构造中取默认/零值,初始化逻辑需注意。

原理流程

  1. 配置 noarg 关联注解。
  2. 编译期为标注类生成无参构造。
  3. 构造内按类型默认值初始化字段。
  4. 框架反射调用无参构造实例化。

代码或图示

// 配置示意(DSL 以官方文档为准)
noArg {
    annotation("com.example.NoArg")
}

常见误区

  • 以为生成的无参构造会执行属性初始化逻辑:合成构造的字段状态需按插件实现确认,业务初始化应在后续方法完成。
  • 必填非空属性被无参构造绕过:可能产生未初始化状态,设计时核对。

追问

  • noarg 与 allopen 常一起用吗?答:常见于需要代理 + 反射实例化的框架场景,两者独立配置。
  • 生成构造在反编译中可见吗?答:可见,属于编译期合成的字节码成员。

04.8.3.2-059 parcelize 插件在本视角下如何定位?

一句话结论

parcelize 是面向 Android Parcelable 协议的编译器插件,生成序列化桥接代码;属于端侧框架能力,本节只说明其插件性质,具体用法见 07 端侧分册。

概念解释

它与序列化插件同属"编译期生成协议适配代码"的插件模式,目标平台是 Android。JVM 后端工程不引入该插件。了解其分类有助于区分编译器插件的不同目标场景。

原理流程

  1. 类实现对应接口并标注。
  2. 插件生成协议读写方法。
  3. 端侧框架调用生成方法完成对象序列化。

代码或图示

parcelize:端侧 Parcelable 适配(详见 07 分册)

常见误区

  • 在后端 JVM 模块引入端侧插件:目标平台不匹配,编译报错。
  • 混淆 JVM 序列化与端侧协议:两者生成机制与运行环境不同。

追问

  • 编译器插件都按平台隔离吗?答:插件按目标平台加载,跨平台插件需在 KMP 中按目标配置。
  • 后端对象序列化选什么?答:kotlinx-serialization 等 JVM 可用方案,见 04.8.4 分册。

04.8.3.2-060 编译器插件改写与 KSP 生成新类的本质区别是什么?

一句话结论

KSP 产物是独立新源文件,原类不动;编译器插件在既有类的 IR/字节码上做变换,原类结构被直接修改。

概念解释

生成新类便于调试与引用,边界清晰;改写原类能力更强但影响编译器内部模型,维护成本高。选型优先"生成新类"方案,确需改变原类行为时才做插件。

原理流程

  1. KSP:输出新文件,编译时与原类并存。
  2. 插件:遍历原类 IR 并就地变换。
  3. 两者产物最终都进字节码。
  4. 调试时分别查看生成源码与反编译结果。

代码或图示

KSP:User.class + UserMapperImpl.class(新增)
插件:User.class 内部方法体/开放度被调整

常见误区

  • 把插件生成的辅助代码当成独立源码阅读:部分变换在反编译中才可见。
  • 评估插件成本只看开发:K2 升级时插件适配风险也要计入。

追问

  • 哪些变换只能插件做?答:给原类加默认构造、打开继承、改写方法体、插入跟踪元信息。
  • 生成新类方案有何限制?答:无法改变原类 final/开放等固有形态。

04.8.3.2-061 编译器插件对 jvmTarget 与 IR 版本敏感吗?

一句话结论

敏感:插件绑定编译器内部 IR 结构与 API,Kotlin 版本、前端模式(K1/K2)变化可能要求插件同步升级;跨版本直接复用旧插件有加载或变换失败风险。

概念解释

后端字节码版本(jvmTarget)影响代码生成目标,IR 结构变化影响插件遍历逻辑。官方插件随 Kotlin 发布配套版本;第三方插件需声明兼容的编译器版本范围。

原理流程

  1. 插件编译期引用编译器内部 API。
  2. 运行期与当前编译器 IR 结构匹配。
  3. 版本不匹配:类链接失败或 IR 节点类型不符。
  4. 升级编译器时同步升级插件。

代码或图示

Kotlin 编译器版本 ──配套──▶ 编译器插件版本

常见误区

  • 只升级业务 Kotlin 不改配套插件:编译期变换失败。
  • 在 CI 上缓存旧插件 class 跨大版本复用:版本不匹配应重新解析。

追问

  • 如何查插件兼容版本?答:插件发布说明与 Kotlin 兼容矩阵;不确定标待确认。
  • 插件报 IR 节点类型错误一般是什么原因?答:插件版本与编译器前端不配套,先对齐版本。

04.8.3.2-062 自定义编译器插件的开发门槛在哪里?

一句话结论

门槛在于理解编译器 IR 结构、插件扩展点注册与跨版本适配;相比 KSP 处理器,IR 插件需要更深的编译器内部知识,且随前端演进维护成本更高。

概念解释

自定义插件要实现编译器扩展点、遍历 IR 树、构造合法节点,并处理类型与作用域校验。K2 迁移期还需跟踪 IR 变化。除非框架必须改写原类,否则优先选择生成新类或外部库方案。

原理流程

  1. 确定变换点与目标 IR 节点。
  2. 实现插件扩展点并注册。
  3. 遍历变换 IR,保证类型合法。
  4. 随编译器版本回归适配。

代码或图示

评估顺序:外部库 → KSP 生成新类 → 自定义 IR 插件(最后选择)

常见误区

  • 为简单代码生成需求自研 IR 插件:成本与维护风险过高。
  • 忽略插件测试:IR 变换错误可能导致非法字节码,需编译器级测试覆盖。

追问

  • 官方有插件开发指南吗?答:Kotlin 编译器插件开发文档是起点;内部 API 稳定性需自行评估。
  • 插件需要发布吗?答:内部工具插件可随构建工程分发,对外发布需提供 marker 与版本兼容声明。

04.8.3.2-063 编译器插件的命令行参数如何传递?

一句话结论

插件选项通过 KGP 编译配置或插件专属 extension 传入,最终转为编译器插件参数;参数名与取值以各插件官方文档为准,不在脚本中臆造。

概念解释

部分插件支持开关、注解包名、输出策略等配置。这些选项在构建脚本中声明,编译任务转发给插件。配置缺失时插件使用默认值,不符合约定会在编译期告警或报错。

原理流程

  1. 脚本在插件 extension 或编译选项中设置参数。
  2. KGP 收集参数传给编译器。
  3. 插件读取参数调整变换行为。
  4. 编译产物按配置生成。

代码或图示

// 示意:插件配置入口(具体 DSL 以官方文档为准)
kotlin {
    compilerOptions {
        // 插件相关编译选项
    }
}

常见误区

  • 把业务运行配置塞进插件参数:插件参数只服务编译期变换。
  • 凭记忆写未文档化的参数名:版本升级后可能被忽略或报错。

追问

  • 插件参数能否按模块区分?答:可在各模块编译配置中分别设置。
  • 如何确认参数生效?答:观察编译产物变化或插件日志输出。

04.8.3.2-064 编译器插件在 K2 下需要做什么迁移?

一句话结论

K2 重写前端后,插件挂载点与 IR 模型可能变化,需使用适配 K2 的插件版本并回归变换结果;自研插件需对照 K2 迁移说明调整遍历与节点构造。

概念解释

官方插件随 Kotlin 2.x 提供 K2 适配版本。第三方插件可能滞后。升级编译器前先核对插件 K2 支持状态,保留旧前端 fallback 的时间窗口以官方说明为准。

原理流程

  1. 查各插件 K2 兼容状态。
  2. 升级到适配版本。
  3. 编译验证变换产物(生成器、开放度、构造等)。
  4. 自研插件按迁移说明改造 IR 访问代码。

代码或图示

K2 升级:插件版本核对 → 编译回归 → 产物反编译核对

常见误区

  • 假设旧插件无缝工作于 K2:内部 API 变化可能直接不兼容。
  • 只跑编译不核对运行行为:变换错误可能延迟到运行期暴露。

追问

  • 如何知道插件是否支持 K2?答:发布说明标注前端支持;未标注的在 K2 工程实测并记录待确认。
  • K1 兼容期有多长?答:以 Kotlin 官方路线说明为准,不臆测截止版本。

04.8.3.2-065 序列化插件如何为 @Serializable 类生成序列化器?

一句话结论

插件分析类属性、类型与可选注解,编译期生成实现 KSerializer 的代码,包含结构序列化解构与重建逻辑;标准类型由运行期库提供序列化器,嵌套类型组合引用。

概念解释

生成器按属性顺序读写结构,处理可选默认值与命名策略。泛型类的序列化器携带类型参数。手写序列化器用于插件无法自动处理的定制类型。

原理流程

  1. 识别 @Serializable 标注类。
  2. 收集属性名、类型、可选性。
  3. 生成 serialize/deserialize 实现。
  4. 运行期 JSON 格式编码解码调用生成器。

代码或图示

@Serializable
data class Profile(val nickname: String, val age: Int = 0)
// 生成器按属性列表读写;age 缺省按默认值处理

常见误区

  • 嵌套未标注类型直接序列化:需为其提供序列化器,否则编译报错。
  • 生成器与手写器混用导致字段遗漏:以编译期报错为准补齐。

追问

  • 字段改名如何保持兼容?答:使用 @SerialName 映射外部字段名,版本演进策略见序列化文档。
  • 序列化器何时生成?答:编译期,产物 class 随模块打包。

04.8.3.2-066 allopen 与框架代理之间是什么关系?

一句话结论

需要生成子类代理的框架要求目标类可继承(open),allopen 在编译期按注解把类开放,使 Kotlin 默认 final 类能被框架代理。

概念解释

CGLIB 等代理机制通过子类化覆盖方法,final 类无法被继承。allopen 不改源码,只在产物层开放。注解选择哪些类进入开放范围,避免全工程类变 open。

原理流程

  1. 框架约定需要代理的注解。
  2. allopen 配置关联该注解。
  3. 编译期标注类变为可继承。
  4. 运行期框架生成子类代理。

代码或图示

Kotlin final 类 ──allopen──▶ 字节码 open 类 ──▶ 框架子类代理

常见误区

  • 以为手写 open 与 allopen 等价:都开放继承,区别在源码声明 vs 编译期合成。
  • 给数据类盲目开放:继承约束可能影响 equals/hashCode 约定。

追问

  • 接口代理需要 allopen 吗?答:基于接口的代理不依赖类开放;子类化代理才需要。
  • 如何确认类已开放?答:反编译查看类修饰符,或运行期代理是否成功创建。

04.8.3.2-067 noarg 生成无参构造的典型用途是什么?

一句话结论

供反射实例化框架在无参情况下创建对象:框架先调无参构造得到空对象,再通过字段/属性赋值填充状态;类源码不必显式写空构造。

概念解释

ORM、部分序列化与 DI 框架依赖无参构造。Kotlin 类有必填属性时默认不生成无参构造,noarg 合成一个满足框架反射要求的构造。字段初始状态按插件规则处理,业务赋值由框架后续完成。

原理流程

  1. 标注类进入 noarg 范围。
  2. 编译期合成无参构造。
  3. 框架反射调用构造实例化。
  4. 框架写入字段后对象投入使用。

代码或图示

@NoArg
data class User(var name: String = "", var age: Int = 0)

常见误区

  • 无参构造后直接使用对象:字段可能未完成业务初始化,需框架赋值流程完整。
  • 把必填非空属性交给无参构造绕过:状态不合法风险,设计上用默认值或工厂方法。

追问

  • noarg 构造会调用属性初始化器吗?答:按插件实现确认,不确定处标待确认;关键初始化不要依赖合成构造。
  • 与 JVM 无参构造规则兼容吗?答:生成的是 JVM 可见无参构造,供反射框架使用。

04.8.3.2-068 编译器插件产物是否进入业务 classpath?

一句话结论

插件变换作用于编译产出的字节码,生成的辅助类/序列化器随模块 jar 进入业务 classpath;插件自身实现只在编译期存在,不打进运行产物。

概念解释

区分两类产物:插件编译期生成/变换的结果属于业务产物;插件处理器 jar 是构建工具,不随业务发布。运行期库(如序列化运行库)则需显式声明为业务依赖。

原理流程

  1. 编译期插件加载并变换/生成代码。
  2. 生成类编译进模块 jar。
  3. 插件实现 jar 留在构建 classpath。
  4. 运行期库由业务 dependencies 引入。

代码或图示

插件 jar:构建期,不打包
生成序列化器 class:随 jar 打包
运行期序列化库:业务显式依赖

常见误区

  • 把编译器插件坐标加进 implementation:应走插件应用配置,而非业务依赖。
  • 遗漏运行期库:生成器存在但缺少编码解码实现,运行期报错。

追问

  • 生成类在运行期被谁调用?答:业务代码或运行期库按序列化器约定调用。
  • 插件依赖会传递给下游模块吗?答:构建期插件不传递;其生成产物随 jar 传递。

04.8.3.2-069 编译器插件与 ASM 字节码增强有何区别?

一句话结论

Kotlin 编译器插件在编译期基于 IR 参与生成过程,理解 Kotlin 语义;ASM 是在编译后直接操作 class 字节码,两者层级与信息保真度不同。

概念解释

IR 插件在源码到字节码的管线内工作,能利用类型与声明信息;ASM 方案面对已生成 class,按字节码指令改写。JVM 生态的字节码增强库多基于 ASM,Kotlin 侧优先官方编译器插件机制。

原理流程

  1. 源码 → Kotlin 编译 → IR 插件变换 → class 字节码。
  2. ASM 路径:class 产物再被字节码工具读取改写。
  3. 插件理解 Kotlin 结构,ASM 只看字节码。
  4. 最终都作用于产物字节码。

代码或图示

编译期:IR 插件(源码语义可见)
编译后:ASM 增强(指令级改写)

常见误区

  • 用 ASM 改 Kotlin 字节码忽略元数据:可能破坏 Kotlin 类元数据与可空性信息。
  • 把编译器插件当运行期增强 agent:二者加载时机不同。

追问

  • 后端 JVM 生态有哪些 ASM 类工具?答:如字节码增强/代理库,本节点到为止,具体框架见 06/09 分册。
  • 何时选 ASM 方案?答:跨语言 class 增强、编译后织入场景;Kotlin 原生改造优先编译器插件。

04.8.3.2-070 插件错误信息常见来自哪里?

一句话结论

常见来源包括插件与编译器版本不配套、被标注类违反插件约束、生成代码类型不匹配、插件读取了不支持的声明类型;错误通常在编译期插件阶段暴露并指向对应类。

概念解释

报错链路:插件加载失败(版本/类缺失)、处理中校验失败(注解目标错误)、生成源码编译失败(模板与类型不符)。按错误阶段区分是插件自身问题还是被标注代码问题。

原理流程

  1. 编译任务加载插件:版本不匹配则链接失败。
  2. 插件遍历声明:约束不满足抛诊断。
  3. 生成代码并入编译:类型错误在编译阶段暴露。
  4. 按堆栈与类定位修复。

代码或图示

加载期:插件类/版本问题
处理期:注解目标与声明约束问题
编译期:生成代码类型问题

常见误区

  • 把生成代码编译错误当作业务源码错误:先追溯是哪个处理器/插件产出。
  • 报错只看最后一行:插件诊断常附带被标注类位置。

追问

  • 如何区分 KSP 产物错误与插件变换错误?答:按任务名与生成目录归属判断。
  • 升级插件后报错如何回退?答:回到配套版本组合,再逐项适配新行为。

04.8.3.2-071 多个编译器插件之间的执行顺序如何确定?

一句话结论

插件按编译器注册顺序挂接到 IR 管线,后注册的插件在前一个变换后的 IR 上继续工作;顺序敏感的组合需在构建配置中明确先后,避免变换结果互相覆盖。

概念解释

不同插件作用于不同节点:序列化生成、开放度调整、组合函数转换各有挂载点。多数场景互不干扰,但同时改写同一类方法体时顺序会影响最终字节码。插件顺序由应用/注册顺序决定,框架级顺序约定以官方文档为准。

原理流程

  1. 编译任务按配置顺序加载插件。
  2. 各插件在对应阶段遍历 IR。
  3. 后一插件读取前一插件变换结果。
  4. 后端基于最终 IR 生成字节码。

代码或图示

IR 原始 → 插件 A 变换 → 插件 B 变换 → 后端字节码

常见误区

  • 假设插件顺序无关:改写同一节点时顺序敏感。
  • 两个插件竞争调整同一修饰符:后生效者覆盖,需核对最终产物。

追问

  • 如何调整插件顺序?答:按构建脚本中的应用顺序配置;插件间官方约定的顺序以文档为准。
  • 顺序问题如何复现?答:反编译对比不同顺序下的字节码差异。

04.8.3.2-072 插件对源码可访问性有什么影响?

一句话结论

插件可在产物层调整开放度、合成构造等形态,但不改变源码声明的包结构与源码可见性;运行期反射看到的是变换后的字节码修饰符。

概念解释

allopen/noarg 类插件只改产物成员形态,源码文件仍按原声明阅读。反射框架在运行期读取字节码修饰符,因此能看到开放类与无参构造。插件不应改变包名或把私有成员暴露为公开。

原理流程

  1. 源码声明保持不变。
  2. 插件在 IR/字节码层调整修饰符或合成成员。
  3. 产物 class 反映变换后形态。
  4. 反射与代理按产物形态工作。

代码或图示

源码:final class User
产物:open class User(allopen 变换后)

常见误区

  • 以为源码会被插件改写落盘:插件作用于编译产物,不回写源文件。
  • 依赖插件暴露私有成员:可见性调整能力有限,不应作为设计绕过手段。

追问

  • 反编译看到的修饰符以哪个为准?答:以编译产物为准,源码与产物差异来自插件变换。
  • 插件合成成员在源码导航中可见吗?答:IDE 可能从产物索引到,源码文件中不显示。

04.8.3.2-073 编译器插件在多平台编译中有什么差异?

一句话结论

同一插件在不同目标平台(JVM/JS/Native)的挂载能力与产物形态可能不同;部分插件仅支持 JVM,KMP 工程需按目标核对插件支持范围。

概念解释

KMP 各目标后端代码生成路径不同,插件对前端 IR 的支持也可能分平台。序列化插件跨平台支持较完整;端侧专用插件只在对应目标生效。配置时按目标平台分组启用。

原理流程

  1. KMP 工程声明各目标。
  2. 插件按支持范围挂接到对应编译任务。
  3. 不支持的目标跳过或报错。
  4. 各目标产物按其后端规则生成。

代码或图示

JVM 目标:JVM 插件全量可用
其他目标:仅支持跨平台的插件生效

常见误区

  • 假设 JVM 插件自动适用于所有 KMP 目标:平台不支持时编译报错。
  • 在公共源码集引入平台专用插件 API:公共代码应保持平台无关。

追问

  • 如何查插件的平台支持?答:插件文档标注支持目标;未标注的在对应目标实测。
  • 本工程是后端 JVM 视角:多平台细节见 KMP 相关章节,本节不展开端侧配置。

04.8.3.2-074 如何排查编译器插件未生效?

一句话结论

按"插件是否应用 → 版本是否配套 → 标注是否命中 → 产物是否出现"逐层排查:先确认插件在编译配置中加载,再核对版本与标注目标,最后检查生成/变换产物。

概念解释

未生效常见原因:插件未在脚本应用、坐标加错 configuration、注解包名不匹配、插件版本与编译器不兼容被跳过。排查从构建任务与产物反推,而不是直接怀疑运行库。

原理流程

  1. 检查 plugins{}/编译配置是否声明插件。
  2. 核对插件与 Kotlin 版本配套。
  3. 确认被标注类注解全限定名正确。
  4. 检查生成目录/反编译产物是否出现变换结果。

代码或图示

排查链:插件应用 → 版本配套 → 注解命中 → 产物出现

常见误区

  • 运行期报序列化器缺失就去查运行库:先确认编译期插件是否生成了序列化器。
  • 注解写错包名却以为插件没加载:注解不命中时插件自然无产物。

追问

  • 如何看插件是否被编译任务加载?答:查看编译任务配置与构建日志中的插件加载信息。
  • 插件静默跳过怎么办?答:开启插件诊断日志,核对版本兼容与注解匹配。

04.8.3.2-075 Room 如何用 KSP 生成 DAO 实现?

一句话结论

Room 的 KSP 处理器读取 @Dao 接口与 @Query/实体注解,在编译期生成 DAO 实现类,把方法调用翻译为 SQL 执行与结果映射;本节从生成链路视角说明,端侧数据库细节见 07 分册。

概念解释

处理器解析接口方法签名、SQL 语句与实体字段映射,生成实现类:查询方法绑定参数、执行 SQL、把行映射为实体。KSP 替代早期 kapt 链路,生成代码参与编译。

原理流程

  1. 实体与 DAO 注解被 KSP 收集。
  2. 处理器校验 SQL 与字段映射(能力随版本)。
  3. 生成 DAO 实现类与映射辅助代码。
  4. 运行期业务调用生成实现完成数据库操作。

代码或图示

@Dao
interface UserDao {
    @Query("SELECT * FROM user WHERE id = :id")
    suspend fun findById(id: Long): User?
}
// KSP 生成 UserDao_Impl 实现类

常见误区

  • 以为 Room 在运行期反射解析 SQL:实现类在编译期生成。
  • 后端 JVM 服务直接套用 Room:Room 面向 SQLite/端侧场景,后端数据库访问按 05 分册选型。

追问

  • Room 处理器坐标通过哪个 configuration 接入?答:KSP configuration;坐标与版本以官方当前版本为准。
  • SQL 校验在哪个阶段?答:处理器阶段按版本能力校验,未覆盖部分运行期暴露。

04.8.3.2-076 Exposed 与注解处理是什么关系?

一句话结论

Exposed 是 Kotlin SQL DSL 库,表定义与查询通过类型化 DSL 编写,通常不依赖注解处理器生成代码;与 Room 这类编译期生成 DAO 的模式不同。

概念解释

Exposed 在运行期通过 DSL 表达式构造 SQL,表对象定义列映射,没有为每个 DAO 生成实现类。后端 JVM 工程使用 Exposed 时不需要 KSP/kapt 链路,减少编译期生成依赖。

原理流程

  1. 定义表对象与列。
  2. 查询通过 DSL 构造语句。
  3. 运行期执行 SQL 并映射结果行。
  4. 无编译期生成类参与。

代码或图示

object Users : Table("users") {
    val id = long("id").autoIncrement()
    val name = varchar("name", 64)
}

常见误区

  • 把 Exposed 当 ORM 注解框架:它是 DSL,映射方式与注解生成不同。
  • 为 Exposed 配置 KSP 处理器:通常不需要。

追问

  • Exposed 结果映射怎么做?答:通过 DSL 行读取 API 映射到领域对象,具体 API 以库版本为准。
  • 哪些后端库走编译期生成?答:按各库文档核对;序列化、部分映射框架可能有生成链路。

04.8.3.2-077 Moshi Kotlin 代码生成链路是怎样的?

一句话结论

Moshi Kotlin 可通过 KSP 适配器生成器在编译期为数据类生成 JSON 适配器,运行期由 Moshi 调用生成器读写字段;反射式 Kotlin 适配器是另一条可选链路。

概念解释

生成链路避免运行期反射扫描字段,与序列化插件思路类似。处理器读取类属性与 JSON 名字策略,生成 JsonAdapter 实现。具体支持的生成方式与坐标以 Moshi 官方当前版本为准,不确定处标待确认。

原理流程

  1. 数据类标注对应适配器生成注解。
  2. KSP 处理器收集属性与命名配置。
  3. 生成 JSON 适配器类。
  4. 运行期 Moshi 注册并调用适配器编解码。

代码或图示

// 注解与生成器配置以官方当前版本为准
@JsonClass(generateAdapter = true)
data class Item(val sku: String, val price: Long)

常见误区

  • 混淆反射适配器与生成适配器:两者运行机制不同,配置方式也不同。
  • 只加运行期 Moshi 库不接生成器:反射链路行为与生成链路需分别确认。

追问

  • 生成适配器与 kotlinx-serialization 如何选型?答:按生态兼容、性能与团队熟悉度评估;后端 JSON 方案对比见 04.8.4 分册。
  • 生成类放在哪里?答:KSP 生成源码目录,随模块编译。

04.8.3.2-078 Dagger/Hilt 在 KSP/kapt 下的状态如何?

一句话结论

依赖注入框架的代码生成链路随生态演进,部分提供 KSP 支持、部分仍以 kapt 为主;具体支持状态以各框架官方公告为准,本节不臆造版本与坐标。

概念解释

DI 框架扫描注入点并生成工厂/连接类,传统走 JSR-269 处理器。KSP 迁移状态因框架而异:迁移前保留 kapt,迁移后切 KSP。后端纯 Kotlin 工程也常选用运行期 DI 库,避免编译期生成链路。

原理流程

  1. 盘点工程使用的 DI 框架。
  2. 查官方 KSP/kapt 支持状态。
  3. 按支持链路配置对应处理器。
  4. 升级时随框架发布切换。

代码或图示

DI 生成链路:kapt(javac 处理器)/ KSP(符号处理)/ 运行期容器(无生成)

常见误区

  • 假设所有 DI 框架都已支持 KSP:需逐框架核对官方说明。
  • 在后端工程强行引入端侧 DI 框架:按 06 分册后端选型评估。

追问

  • 运行期 DI 库与生成式 DI 区别?答:前者运行期组装容器,后者编译期生成工厂;权衡启动性能、可见性与调试成本。
  • 如何记录框架生成链路?答:在构建说明中标注所用处理器类型与版本。

04.8.3.2-079 AutoService 与注解注册是怎么回事?

一句话结论

AutoService 是为 Java 注解处理器生成 SPI 服务注册文件的工具;在 Kotlin 工程中若仍走 kapt 链路可复用,KSP 场景下处理器注册按 KSP 自己的服务发现机制处理。

概念解释

JSR-269 处理器需要在 META-INF/services 注册 Processor 类,AutoService 注解处理器自动生成该注册文件。KSP 处理器有独立注册方式,不套用 AutoService 产物。

原理流程

  1. Java 处理器类标注 @AutoService(Processor::class)。
  2. 注解处理期生成服务注册文件。
  3. javac/SPI 按清单加载处理器。
  4. KSP 处理器走自身注册机制。

代码或图示

javac 处理器:META-INF/services 注册文件
KSP 处理器:KSP 服务发现机制(以文档为准)

常见误区

  • 给 KSP 处理器加 AutoService 注解:注册机制不匹配,无效。
  • 忽略服务注册文件生成:处理器不被框架发现。

追问

  • 自研 KSP 处理器如何注册?答:按 KSP 文档提供的服务清单/工厂方式配置,具体格式以版本为准。
  • 服务注册文件会进产物吗?答:对应链路的注册文件随处理器 jar 打包。

04.8.3.2-080 Room 生成的表映射代码位于哪里?

一句话结论

生成的 DAO 实现与映射辅助类位于 KSP 生成源码目录,编译后进入模块 jar;业务代码 import 生成类由处理器按约定命名产出,不手工编辑。

概念解释

生成类包名通常与 DAO 接口相关联,类名加实现后缀。IDE 同步后可跳转查看生成代码用于调试。清理构建目录后重新生成,生成物不纳入版本管理。

原理流程

  1. KSP 任务输出到生成源目录。
  2. DAO 实现类与映射代码写入该目录。
  3. Kotlin 编译纳入生成源码。
  4. class 产物随 jar 打包。

代码或图示

生成目录:build/generated/ksp/...(路径以 KGP 版本为准)

常见误区

  • 修改生成实现类补逻辑:下次构建被覆盖,应改 DAO 接口或实体定义。
  • 把生成目录提交到版本库:生成物应忽略。

追问

  • 生成类找不到符号怎么办?答:确认 KSP 任务成功、生成目录已加入源集;重新同步 IDE。
  • 多个模块生成类重名?答:按包名与模块隔离,处理器命名约定区分。

04.8.3.2-081 序列化插件如何替代反射?

一句话结论

序列化插件在编译期把字段读写逻辑生成进序列化器 class,运行期直接调用生成代码,不再通过反射枚举字段或读取注解,降低反射开销与运行期字段扫描风险。

概念解释

反射式序列化依赖运行期读取类结构,字段更名/可见性问题延迟到运行期暴露;编译期生成在编译阶段就完成类型检查。生成器仍需运行期格式库承担编码解码。

原理流程

  1. 编译期分析类结构生成序列化器。
  2. 字段读写逻辑固化在 class 中。
  3. 运行期按生成器直接访问字段。
  4. 格式库负责 JSON/结构编码。

代码或图示

反射链路:运行期扫描字段 → 读写
生成链路:编译期生成读写代码 → 运行期直接调用

常见误区

  • 以为生成链路完全不需要运行期库:生成器只处理结构映射,格式编解码仍依赖库。
  • 生成器可绕过可见性约束:字段访问按 Kotlin/JVM 规则生成。

追问

  • 反射序列化有何适用场景?答:动态类型、插件化扩展场景;固定数据结构优先编译期生成。
  • 字段改名对生成链路影响?答:编译期按当前字段生成,改名同步更新序列化映射声明。

04.8.3.2-082 路由与 DI 框架常见的生成模式有哪些?

一句话结论

常见模式包括:扫描注解收集注册项生成路由表/工厂类、为接口生成实现代理、为注入点生成构造工厂;均在编译期产出连接代码,业务代码按生成类引用。

概念解释

路由框架收集 @Route 标注类生成路径到处理器的映射;DI 框架生成依赖工厂与注入连接。生成模式可组合:处理器收集符号,生成新类,必要时配合插件调整形态。

原理流程

  1. 处理器扫描注解与声明。
  2. 汇总注册表/工厂模型。
  3. 生成连接代码(映射表、工厂、代理)。
  4. 运行期业务调用生成类完成分发/组装。

代码或图示

扫描 @Route → 生成路由表
扫描 @Inject → 生成工厂与注入连接

常见误区

  • 假设框架运行期动态扫描类路径:很多框架用编译期注册表,新增类必须被处理器扫到。
  • 生成注册类与手写注册重复维护:以生成链路为准,避免双写。

追问

  • 后端路由框架是否走生成链路?答:按具体框架;Ktor 等多为运行期路由声明,详见 06 分册。
  • 生成注册表增量失效怎么办?答:新增标注类后重新跑处理器,确认注册表更新。

04.8.3.2-083 生成代码与运行期反射在编译期还是运行期工作?

一句话结论

KSP/kapt/编译器插件的生成工作发生在编译期;产物类在运行期被调用,运行期不再重复扫描注解(除非框架另设计反射回退)。

概念解释

区分"生成时机"与"产物运行时机":编译期处理器产出类,运行期业务调用产物。反射框架则在运行期读取类结构。两条链路混用会造成双重开销,设计时明确主路径。

原理流程

  1. 编译期:处理器/插件扫描源码并产出代码。
  2. 编译:产物类编入 jar。
  3. 运行期:直接调用产物类方法。
  4. 反射链路:运行期读取类结构并动态调用。

代码或图示

编译期生成 ──▶ 产物 class ──▶ 运行期直接调用
运行期反射 ──▶ 运行期扫描结构 ──▶ 动态调用

常见误区

  • 以为生成类运行期还会重读注解:生成完成后注解信息已固化进代码。
  • 在生成产物上再套反射代理:额外开销且易错,应理清职责。

追问

  • 如何判断某库是生成还是反射?答:查文档与依赖中是否含处理器配置;看编译产物是否有生成类。
  • 生成类能被反射二次利用吗?答:技术上可以,但非框架设计主路径。

04.8.3.2-084 生成类如何被业务代码引用?

一句话结论

业务代码按处理器约定的包名与类名 import 生成类;生成类在编译期进入源集,编译期即可被解析引用,无需运行期注册查找。

概念解释

生成类与手写类在编译 classpath 上并列。命名约定稳定后业务直接引用接口返回类型或生成实现。处理器提供工厂访问点(如 serializer())降低直接引用生成类的耦合。

原理流程

  1. 处理器按命名约定产出生成类。
  2. 生成源码加入编译源集。
  3. 业务代码 import 并引用。
  4. 编译器解析生成类符号。

代码或图示

// 业务侧引用生成能力(具体入口按框架约定)
val adapter = User.serializer()

常见误区

  • 业务代码手写实现类名猜测生成类:应按框架文档约定引用入口。
  • 生成类包名随模块漂移导致 import 断裂:命名约定需稳定。

追问

  • 生成类需要手写接口声明吗?答:处理器通常围绕已有接口/标注类生成实现,业务定义接口与模型。
  • IDE 报生成类无法解析?答:重新同步/构建生成源集,检查处理器任务是否成功。

04.8.3.2-085 增量构建下生成代码有哪些失效场景?

一句话结论

源码签名变更、新增/删除标注类、处理器依赖声明不全、构建脚本或处理器版本变化,都可能使生成产物失效重生成;未声明依赖会导致旧代码残留。

概念解释

增量分析依赖符号到产物的映射。标注类增删、属性签名变化属于输入变更;处理器未声明读取来源时,变更不触发对应产物更新。处理器版本升级整体刷新生成结果。

原理流程

  1. 检测源码与配置变更。
  2. 按依赖映射判定受影响生成文件。
  3. 失效文件重新生成。
  4. 未声明依赖的变更可能漏更新。

代码或图示

变更类签名 → 对应生成类重生成
新增 @Gen 类 → 新生成类产出
处理器升级 → 全量重新生成

常见误区

  • 改了模型字段但生成代码未更新:检查处理器依赖声明与增量状态,必要时 clean 重建。
  • 残留旧生成类导致编译冲突:清理生成目录后重建。

追问

  • 如何验证增量更新正确?答:改单字段,核对对应生成类变化、无关生成类不动。
  • 生成类删除后旧文件残留?答:处理器应管理产物清理;异常残留时 clean 构建目录。

04.8.3.2-086 多轮处理中新生成的符号能否被下一轮读取?

一句话结论

可以:KSP 多轮模型把本轮生成的新符号纳入后续轮次供其他处理器读取;这是处理器之间生成—消费衔接的机制基础。

概念解释

若处理器 A 生成的类需要处理器 B 再加工,B 在后续轮次看到 A 的产物。轮次结束条件与未处理符号返回需正确实现。并非所有生成内容都自动可见,依赖多轮调度规则。

原理流程

  1. Round 1:A 生成新类。
  2. 新符号进入下一轮集合。
  3. Round 2:B 读取并处理。
  4. 无新增后结束。

代码或图示

A 生成 X ──▶ Round 2 ──▶ B 处理 X

常见误区

  • 假设同一轮内后注册处理器能看到先生成类:需跨轮次衔接。
  • 处理器间靠全局变量传新符号:应通过生成文件与符号模型传递。

追问

  • kapt 是否有类似多轮?答:javac 注解处理本身有多轮机制,kapt 桥接该流程;模型保真度受限。
  • 如何调试跨轮产物?答:逐轮检查生成目录与处理器日志。

04.8.3.2-087 第三方库处理器版本与 Kotlin 版本如何保持兼容?

一句话结论

按官方兼容矩阵选择处理器版本:KSP 处理器版本绑定 Kotlin 版本区间,kapt 处理器跟随 javac 生态;升级 Kotlin 前先确认各库处理器已发布兼容版本。

概念解释

处理器编译期引用编译器/API,版本错位在处理阶段报错。多库工程需同时满足各自兼容窗口。版本目录集中登记,升级时按矩阵联动核对,不单独追新某一处理器。

原理流程

  1. 确定目标 Kotlin 版本。
  2. 逐个核对库处理器兼容版本。
  3. 目录登记配套组合。
  4. 构建验证全部生成链路。

代码或图示

Kotlin 2.0.x ──▶ 配套 KSP 版本 ──▶ 各库处理器兼容版本

常见误区

  • 只升级业务库不升级其处理器:生成链路与运行库版本不匹配。
  • 忽略库发布说明中的 Kotlin 兼容要求:编译期问题在集成阶段才暴露。

追问

  • 处理器版本与运行库版本必须一致吗?答:按框架发布说明确认;通常处理器与库版本配套。
  • 兼容窗口空窗怎么办?答:暂不升级 Kotlin,等待处理器发布支持版本。

04.8.3.2-088 如何确认项目用的是 KSP 还是 kapt?

一句话结论

检查构建脚本:存在 KSP 插件与 ksp(...) 配置即走 KSP;存在 kotlin-kapt 插件与 kapt(...) 配置即走 kapt;两者也可能短期并存。

概念解释

处理器坐标所在 configuration 决定加载链路。任务图中 KSP 任务与 kapt 任务名称不同,构建报告可区分。并存时两类任务都会出现,应核对是否为过渡状态。

原理流程

  1. 查看 plugins{} 中的 KSP/kapt 插件声明。
  2. 检查 dependencies 中处理器配置归属。
  3. 构建报告确认对应处理任务执行。
  4. 判断是否存在并存与迁移遗留。

代码或图示

// KSP
id("com.google.devtools.ksp")
ksp(libs.room.compiler)

// kapt
id("kotlin-kapt")
kapt(libs.some.processor)

常见误区

  • 看到注解处理器就认定 kapt:先看 configuration 归属。
  • 迁移后残留旧处理器依赖:旧配置未清除会重复执行处理链。

追问

  • 处理器坐标写在 implementation 算哪种?答:都不算,不会被处理链加载,属配置错误。
  • 如何统计各链路耗时?答:构建报告按任务名区分 KSP/kapt 任务时间。

04.8.3.2-089 生成代码如何反查与调试?

一句话结论

从生成类反推被处理的源类与处理器:查看生成目录中的类名/包名约定,定位对应注解标注源码;调试时先在处理器单测复现,再在构建期附加断点观察符号。

概念解释

生成类是产物,调试应沿"生成类 → 源类 → 处理器模板"回查。字段缺失、类型错误通常先对照源类签名与模板逻辑。反编译可查看插件变换后的最终字节码。

原理流程

  1. 打开生成目录中的问题类。
  2. 按命名约定找到源类。
  3. 核对处理器读取的符号与模板输出。
  4. 必要时附加调试器观察 Resolver 数据。

代码或图示

生成 UserMapperImpl.kt → 源 User.kt → 处理器模板/符号读取

常见误区

  • 直接改生成类修复问题:根因在处理器模板或源类定义,改动会被覆盖。
  • 只看生成代码不看源类注解参数:映射错误常来自注解配置。

追问

  • 生成代码在 IDE 中不显示?答:同步构建生成源集;检查处理器任务是否成功输出。
  • 如何保存生成产物供排查?答:构建后保留生成目录快照,CI 中可作为调试附件留存。

04.8.3.2-090 主流库生成链路可以如何总览对比?

一句话结论

按"生成方式(KSP/kapt/编译器插件/运行期反射)、产物形态、是否需要编译期配置"三个维度对比各库,后端选型时优先生成链路清晰、Kotlin 兼容良好的方案。

概念解释

序列化:编译器插件生成序列化器;DAO/映射:KSP 生成实现;DI:生成工厂或运行期容器;纯 DSL 库无生成。对比时同时评估处理器维护状态与 Kotlin 2.x 兼容情况。

原理流程

  1. 列出候选库及其生成机制。
  2. 标注处理器类型、产物与配置入口。
  3. 核对 Kotlin 版本兼容与迁移状态。
  4. 结合团队维护成本选型。

代码或图示

kotlinx-serialization:编译器插件生成器
Room/Moshi:KSP 生成(状态以官方为准)
Exposed:DSL,无生成
DI:生成工厂 / 运行期容器

常见误区

  • 只比运行期 API 不比生成链路:编译期配置与兼容风险被忽略。
  • 跨端侧与后端场景混选:端侧库能力与后端运行环境不同。

追问

  • 后端 JSON 序列化首选?答:按工程生态评估 kotlinx-serialization 等方案,详见 04.8.4 分册。
  • 新库接入前必查什么?答:生成链路类型、Kotlin 兼容版本、维护活跃度。

04.8.3.2-091 KSP2 与 KSP1 的差异是什么?

一句话结论

KSP2 是面向 K2 编译器的新一代 KSP 实现,适配新前端符号模型;KSP1 基于旧前端。差异细节、迁移注意事项以官方发布说明为准,本处不展开未验证的 API 变更清单(待确认)。

概念解释

升级 Kotlin 2.x 后,KSP2 提供与新前端配套的符号处理能力。处理器在两套实现间可能需要适配 API 变化。工程应选择与编译器配套的 KSP 版本线,不混用。

原理流程

  1. 确认编译器前端版本。
  2. 选择对应 KSP 版本线(KSP1/KSP2)。
  3. 处理器在对应 API 上运行。
  4. 按发布说明验证处理器行为。

代码或图示

旧前端 ── KSP1
K2 前端 ── KSP2(配套版本见官方矩阵)

常见误区

  • 以为 KSP 版本号小差异不影响前端适配:版本线与前端绑定,需核对说明。
  • 处理器在 KSP2 下行为偏差却不查迁移文档:API 语义可能调整。

追问

  • 如何确认当前运行 KSP2?答:查 KSP 版本发布说明与构建日志标识;具体识别方式以版本为准。
  • KSP1 还能维护多久?答:以官方路线说明为准,不臆测停止时间。

04.8.3.2-092 K2 下 kapt 的支持范围有哪些待确认点?

一句话结论

K2 下 kapt 对复杂 Kotlin 特性与新语法的支持可能受限,具体可用范围、告警与降级行为需对照官方 K2 迁移文档实测确认,本处标注待确认。

概念解释

kapt 依赖编译器导出签名的能力,K2 重构后该适配在跟进中。存量 kapt 工程升级 K2 前应跑通编译与生成链路;不支持的场景优先迁移 KSP 或暂缓编译器升级。

原理流程

  1. 查官方 kapt 对 K2 的支持说明。
  2. 在 K2 工程运行现有 kapt 处理器。
  3. 记录告警、报错与生成产物差异。
  4. 不可用场景制定迁移或暂缓方案。

代码或图示

待确认:K2 下 kapt 支持的语言特性边界、增量行为与错误提示

常见误区

  • 未实测就假设 kapt 全量可用:签名映射可能出现新差异。
  • 把 kapt 告警当无关信息:告警可能预示产物行为偏差。

追问

  • 官方说明在哪里查?答:Kotlin 官网 K2 迁移与 kapt 文档章节。
  • 过渡期如何保障构建?答:锁定已知兼容的编译器版本,跟踪处理器生态更新。

04.8.3.2-093 升级 Kotlin 后插件/处理器报错的常见原因是什么?

一句话结论

常见原因是处理器或编译器插件未升级到配套版本、新编译器收紧了类型检查、API 弃用/移除、生成模板与新语言特性不兼容;按报错阶段(加载/处理/编译)归类修复。

概念解释

编译器升级改变内部 API 与类型规则:旧处理器链接失败,旧模板生成不符合新规则的代码。先对齐工具链版本组合,再处理源码 API 迁移,最后修复处理器兼容问题。

原理流程

  1. 升级后先观察报错阶段。
  2. 加载期错误:插件/处理器版本不配套。
  3. 处理期错误:符号 API 变化。
  4. 编译期错误:生成代码或源码不兼容新规则。

代码或图示

版本对齐 → 处理器升级 → 源码 API 迁移 → 生成链路回归

常见误区

  • 跳过版本对齐直接改源码报错:根因可能是旧处理器不兼容新编译器。
  • 一次跨多个大版本升级:问题叠加,难以定位。

追问

  • 弃用 API 警告如何处理?答:按迁移说明替换,结合 allWarningsAsErrors 门禁逐步清理。
  • 回滚方案?答:恢复升级前版本组合,定位受阻的处理器后再重试。

04.8.3.2-094 KSP 处理器报错如何定位到具体源码?

一句话结论

处理器诊断携带被标注符号的位置信息,构建输出可按类名/文件定位;日志中先找报错处理器与符号,再回查对应源类注解与属性。

概念解释

KSP 报错分处理器主动报告与生成代码编译报错两类。前者从诊断中的符号位置定位源类;后者从生成类反查源类与模板。堆栈指向处理器内部代码时,结合单测复现。

原理流程

  1. 读取构建输出中的处理器名与诊断消息。
  2. 按符号位置定位源文件与标注类。
  3. 检查注解参数、类型可见性与签名约束。
  4. 生成代码错误则反查模板输出。

代码或图示

诊断:@Gen 只能标注 data class → 定位源类 → 修正声明

常见误区

  • 只看编译器最后一条错误:处理器原始诊断可能在更早日志中。
  • 报错类名是生成类却去改源码:先反查源类与处理器。

追问

  • 处理器未输出位置信息怎么办?答:在处理器中补充位置日志;框架默认诊断能力以版本为准。
  • 多处理器串行报错先修哪个?答:先修上游生成类处理器,其产物影响下游处理。

04.8.3.2-095 生成代码包名或乱码错误如何排查?

一句话结论

包名错误通常来自包名读取/模板拼接失误,乱码多为编码或模板字符串问题;先核对源类包名与生成目录,再检查生成模板的字符串编码与转义。

概念解释

KSP 读取 packageName 拼生成包名,拼接规则错误会导致类落到错误包。编码问题在 Windows 环境需注意源文件 UTF-8 无 BOM;模板拼接特殊字符未转义会产出非法源码。

原理流程

  1. 打开生成文件核对包名声明。
  2. 对照源类包名与处理器拼接规则。
  3. 检查模板字符串编码与转义。
  4. 修复处理器模板后重新生成。

代码或图示

源类包名 com.example → 生成类应为 com.example.gen
包名错位:检查 packageName 拼接与目录约定

常见误区

  • 把生成文件包名手动改对:处理器模板未修,下次生成依旧错误。
  • 忽略文件编码:非 UTF-8 中文标识符/注释可能产生乱码。

追问

  • 生成源码编译报非法字符怎么办?答:检查模板字符串转义与源文件编码。
  • 中文类名/包名有什么建议?答:生成代码与包名使用 ASCII 标识符,中文仅用于显示文本。

04.8.3.2-096 处理器的扫描范围是哪个 sourceSet?

一句话结论

KSP/kapt 默认处理主源集(main)中的标注类;测试源集是否被处理由配置决定,处理器一般不扫描构建目录中的生成物。

概念解释

处理器输入是参与编译的源码集合。测试源码集有独立编译任务,对应处理配置需单独声明。生成物不被重复扫描,避免循环处理。

原理流程

  1. 编译任务确定输入 sourceSet。
  2. 对应处理器配置绑定该源集。
  3. 处理器扫描源集中的标注声明。
  4. 生成代码并入对应编译任务。

代码或图示

main 源集 → KSP/kapt 处理 → 主编译
test 源集 → 按配置决定是否处理 → 测试编译

常见误区

  • 测试工具类标注了生成注解却不生成:测试源集未配置处理器。
  • 处理器扫描到生成目录:输入范围应排除生成物目录。

追问

  • 测试专用生成类怎么配?答:在测试对应处理器配置中声明,具体 configuration 命名以插件文档为准。
  • 多 build type/flavor 源集呢?答:按变体源集分别配置处理任务。

04.8.3.2-097 测试源码集会被处理器处理吗?

一句话结论

取决于是否为测试源集配置了对应处理器依赖;默认主源集处理器不自动处理测试源码,测试中使用的生成类需单独配置链路。

概念解释

测试编译有独立 classpath 与任务。若测试代码需要生成的实现/适配器,测试 configuration 也要接入处理器。否则测试引用不到生成类,编译报错。

原理流程

  1. 检查测试源码中的标注类。
  2. 在测试处理器配置中加入对应处理器。
  3. 测试编译前运行处理任务。
  4. 生成类进入测试源集编译。

代码或图示

dependencies {
    // 测试源集处理器配置(命名以插件文档为准)
}

常见误区

  • 主源集配了处理器就以为测试自动覆盖:两套源集独立。
  • 测试工具类放在 main 只为走处理器:污染主产物,应理清归属。

追问

  • 测试替身需要生成类吗?答:多数测试用手写 fake 即可,生成链路服务生产模型。
  • 处理器能区分 main/test 输入吗?答:按任务绑定的源集读取,处理器可感知来源集信息(API 以版本为准)。

04.8.3.2-098 缓存命中导致旧生成代码残留如何处理?

一句话结论

任务缓存或增量记录过期时,可能复用旧生成产物;表现为改了注解/源码但生成类不变。处理方式是清理生成目录与对应任务状态后重建,再检查处理器依赖声明是否完整。

概念解释

生成任务的输入若未完整声明,缓存判定认为输入未变而复用旧产物。处理器版本升级、源码签名变更都应使产物失效。残留类与新手写类冲突时编译报重复声明。

原理流程

  1. 现象:生成代码未随源码更新。
  2. 检查任务状态是否 UP_TO_DATE/FROM_CACHE。
  3. 清理生成目录与任务历史后重建。
  4. 复核处理器输入依赖声明。

代码或图示

源码变更 → 生成任务未重跑(缓存误判)→ 旧类残留
处理:clean 生成目录 → 重新处理 → 修正依赖声明

常见误区

  • 反复改源码不生效就怀疑编译器:先排除生成任务缓存残留。
  • 不修复输入声明只清缓存:下次变更仍可能误命中。

追问

  • 如何确认缓存键包含源码变更?答:核对处理器声明的符号依赖是否覆盖变更点。
  • CI 上残留如何避免?答:干净工作区重建 + 远程缓存条目按输入哈希更新。

04.8.3.2-099 KSP 与 IDE 同步是什么关系?

一句话结论

IDE 同步构建脚本后会触发生成源集加入索引,生成类可被导航与补全;处理器任务未成功执行时 IDE 看不到生成类,需重新同步或先跑一次构建。

概念解释

IDE 依赖 Gradle 模型把生成目录注册为源码目录。KSP 任务输出在构建后产生,同步流程触发任务执行或读取既有产物。IDE 与命令行构建使用同一套生成目录约定。

原理流程

  1. IDE 同步读取 Gradle 模型与配置。
  2. 触发/识别 KSP 生成目录。
  3. 生成源码加入 IDE 索引。
  4. 业务代码可导航到生成类。

代码或图示

IDE 同步 → 生成源集注册 → 索引生成类 → 补全/导航可用

常见误区

  • 命令行能编译、IDE 报生成类缺失:IDE 未重新同步生成源集。
  • 在 IDE 中编辑生成类:产物会被下次构建覆盖。

追问

  • 同步后仍找不到生成类?答:先命令行跑通 KSP 任务,再刷新 IDE 模型。
  • IDE 索引过大怎么办?答:生成目录按约定管理,不手工纳入额外源码。

04.8.3.2-100 如何在 KSP、kapt 与编译器插件之间做选型决策?

一句话结论

优先 KSP 做 Kotlin 感知的新代码生成;仅当依赖库只提供 Java 处理器时保留 kapt;需要改写既有类形态或方法体时才用编译器插件;无生成必要时选运行期库。

概念解释

决策顺序:先判断是否需要编译期生成。需要新类 → KSP;生态仅有 Java 处理器 → kapt 过渡;改写原类 → 编译器插件;运行期可解决 → 不引入生成链路。选型同时评估 Kotlin 2.x 兼容与长期维护状态。

原理流程

  1. 明确需求:新增类 / 改写原类 / 运行期组装。
  2. 核对第三方库支持的处理链路。
  3. 评估 Kotlin 版本兼容与迁移成本。
  4. 落地配置并回归生成产物。

代码或图示

新生成类:KSP 优先
仅 Java 处理器:kapt 过渡
改写既有类:编译器插件
运行期可完成:不接生成链路

常见误区

  • 为小工具脚本自研编译器插件:成本过高,优先库或 KSP。
  • 新项目新建 kapt 处理器:长期维护与 K2 兼容风险,应直接选 KSP。

追问

  • 一个工程能否混合多种链路?答:可以并存于不同模块/库,但应记录归属并逐步收敛。
  • 选型时必须核对哪些版本信息?答:Kotlin 编译器、KSP、各处理器/插件配套版本与官方兼容矩阵。

参考来源

  • Kotlin 官方文档:KSP 概述、处理器 API 与增量模型,https://kotlinlang.org/docs/ksp-overview.html
  • Kotlin 官方文档:Kotlin 编译器插件与 Gradle 配置(序列化、allopen、noarg 等),https://kotlinlang.org/docs/gradle-compiler-plugins.html
  • Kotlin 官方文档:KSP 与 Kotlin 版本兼容说明及发布更新,https://kotlinlang.org/docs/ksp-versions.html
  • Gradle 官方文档:Kotlin Gradle Plugin 与注解处理配置,https://docs.gradle.org/current/userguide/kotlin_dsl.html
  • JetBrains/kotlin 仓库与各库官方发布说明:Room、Moshi 等处理器支持状态以其当前文档为准

待整理清单

  • [ ] 核对 KSP2 相对 KSP1 的具体 API 差异与处理器迁移点(见 04.8.3.2-091)
  • [ ] 核对 K2 编译器下 kapt 的支持范围、增量行为与告警清单(见 04.8.3.2-050、04.8.3.2-092)
  • [ ] 核对各第三方库(DI、Moshi 等)当前 KSP/kapt 支持状态与配套坐标(见 04.8.3.2-077、04.8.3.2-078)
  • [ ] 补充自研 KSP 处理器的服务注册文件格式与测试框架示例(见 04.8.3.2-021、04.8.3.2-038)
  • [ ] 核对 noarg 合成构造是否调用属性初始化器(见 04.8.3.2-067)