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/序列化实现的库。
原理流程
- 编译流程中 KSP 收集源码与依赖中的符号声明。
- 处理器实现
SymbolProcessor,按注解或规则筛选符号。 - 通过代码生成器写出 Kotlin/Java 源文件或资源。
- 生成代码参与后续 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 类型系统。两者产物都参与后续编译,但处理路径与信息保真度不同。
原理流程
- kapt:Kotlin 源码 → stub 生成 → Java 注解处理器读桩 → 生成代码 → Kotlin 编译合并。
- KSP:Kotlin 源码 → 符号模型 → 处理器直接读取 → 生成代码 → Kotlin 编译合并。
- KSP 省去桩生成环节,类型信息保留更完整。
- 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 只构建处理器所需的符号视图。实际提速幅度受处理器遍历范围、生成代码量影响,但缺少桩生成环节是结构性优势。
原理流程
- kapt 阶段:解析 Kotlin → 生成桩 → javac 读取桩 → 处理器执行。
- KSP 阶段:构建符号模型 → 处理器查询符号 → 生成代码。
- 少一轮跨语言模型转换。
- 增量场景下 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 版本演进,不确定处标待确认。
原理流程
- 编译模块含 Kotlin 与 Java 源码。
- KSP 构建符号模型时纳入可解析的 Java 声明。
- 处理器读取 Java 类签名用于类型推导。
- 生成代码仍进入 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 编译任务在任务图中按顺序连接。
原理流程
- KSP 任务收集当前轮次符号。
- 处理器执行并输出生成文件。
- 若产生新符号,进入下一轮处理。
- 轮次结束后生成源码并入 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 按生态支持情况迁移。
原理流程
- KGP 配置 kapt 插件后注册 kapt 任务。
- 编译器为 Kotlin 类生成 Java 桩签名。
- javac 启动注解处理,处理器在桩上执行。
- 生成源码交回 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 架构的必要代价。
原理流程
- 解析 Kotlin 类声明与签名。
- 映射为 Java 兼容签名生成桩。
- javac 注解处理读取桩类型。
- 处理器生成代码后桩被丢弃,不进最终产物。
代码或图示
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 下可能读到不完整信息。
原理流程
- Kotlin 类型进入映射层。
- 可空性转为注解或平台类型。
- 特有语法折叠为 Java 兼容签名。
- 处理器基于近似视图工作,细节丢失。
代码或图示
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 版本;个别处理器在迁移期可能存在行为差异。
原理流程
- 确认 Kotlin 编译器版本与前端模式。
- 选择配套 KSP 版本线。
- 接入处理器并跑生成代码链路。
- 对照发布说明核对未覆盖场景。
代码或图示
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 插件条目。
原理流程
- 查 KSP 官方兼容表确定 Kotlin 版本对应 KSP 版本。
- 目录登记配套版本。
- 构建期 KSP 校验编译器版本。
- 不匹配即报错中断。
代码或图示
[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 源文件、资源文件,也可读取符号信息用于校验;产物进入对应生成源码目录或资源目录参与后续编译。
概念解释
代码生成是主要用途:为注解标注类生成实现类、代理类、序列化器等。资源产物用于生成配置文件、服务注册清单。处理器不直接修改被标注类的字节码。
原理流程
- 处理器通过代码生成 API 创建文件。
- 指定包名、文件名与内容。
- 生成源码加入编译源集。
- 资源产物加入对应资源目录。
代码或图示
处理器输出:*.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 对应角色,概念相似但类型与调用方式不同。
原理流程
- JSR-269:javac 在编译期回调 Java Processor。
- kapt 把 Kotlin 桩喂给该链。
- KSP:KGP 在编译前回调 Kotlin SymbolProcessor。
- 两套 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 实现。
原理流程
- 列出工程用到的生成类库。
- 核对各库 KSP/kapt 支持状态。
- 有 KSP 的迁移,无 KSP 的保留 kapt。
- 跟踪库发版,支持 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 模型呈现。
原理流程
- 读取 Kotlin 声明:直接使用符号模型。
- 读取 Kotlin 依赖类:解析元数据补全类型语义。
- 读取 Java 依赖类:使用 Java 签名视图。
- 处理器按可见信息做生成决策。
代码或图示
Kotlin 类:AST 符号 + 元数据
Java 类:Java 签名视图
常见误区
- 假设跨语言依赖的可空性始终精确:Java 平台类型需按约定处理。
- 在 KSP 中反射读取 class 文件内容:处理期基于符号模型,不做运行期反射。
追问
- 依赖是编译产物 jar 而非源码怎么办?答:KSP 读取 jar 中类签名与元数据,不可见方法体实现。
- 元数据被剥离会怎样?答:类型语义信息缺失,处理器需降级处理并标注限制。
04.8.3.2-015 KSP 的多轮处理(round)模型是怎样的?
一句话结论
KSP 分轮处理:每轮处理器基于当前符号集合工作并生成新代码;新生成符号进入下一轮,直到某轮没有新符号产生才结束。
概念解释
多轮模型类似 javac 处理轮次,用于处理器之间生成与读取衔接。每轮结束 KSP 判断是否还有待处理注解/符号。处理器需正确返回未处理符号列表,避免无限轮次。
原理流程
- 第一轮:收集源码符号,处理器生成代码。
- 后续轮:上轮生成符号纳入集合,再次处理。
- 无新增待处理符号时结束。
- 全部生成源码交编译任务。
代码或图示
Round 1:源符号 → 处理器 → 生成 A
Round 2:A 纳入符号 → 处理器 → 生成 B
Round 3:无新符号 → 结束
常见误区
- 处理器不返回未处理符号:可能导致轮次异常或符号遗漏。
- 处理器在轮次间保留可变状态假设顺序:多轮执行顺序与隔离需按 API 约定处理。
追问
- 生成的新类能否被下一轮 KSP 读取?答:可以,这正是多轮模型支持的衔接方式。
- 如何避免处理轮次过多?答:处理器只处理目标注解,及时返回剩余未处理符号。
04.8.3.2-016 KSP 的增量支持粒度如何?
一句话结论
KSP 记录符号与生成文件的依赖关系,源码变更时按受影响符号缩小重处理范围;增量粒度与隔离策略随版本演进,实测以当前 KSP 文档为准。
概念解释
相比 kapt 增量受限,KSP 设计上支持更细的增量:变更类只重跑依赖它的处理器逻辑。处理器需正确声明读取范围,过度遍历全量符号会削弱增量收益。
原理流程
- 上轮记录符号到生成文件的映射。
- 本次检测变更源码。
- 分析受影响符号集合。
- 只重处理相关生成产物。
代码或图示
变更 A.kt → 受影响符号 → 重跑对应处理器逻辑 → 更新生成文件
常见误区
- 处理器遍历整个模块符号集:变更波及面被放大,增量退化。
- 假设生成文件自动随源码更新:处理器需按依赖关系正确产出。
追问
- kapt 增量为何受限?答:桩生成与 javac 处理链按较粗粒度失效,细节见后续 kapt 专题题。
- 如何验证 KSP 增量生效?答:对比改动单文件前后 KSP 任务执行范围与耗时。
04.8.3.2-017 如何调试 KSP 处理器?
一句话结论
处理器作为 JVM 代码可单测其符号查询逻辑,构建期可附加调试器到运行 KSP 的进程;日志通过处理器日志 API 输出符号与生成决策。
概念解释
处理器开发分两层:符号映射与代码生成逻辑可脱离完整构建做单元测试;与编译器/任务图衔接的部分需在构建进程中调试。先在测试夹具上构造符号输入,再联调真实模块。
原理流程
- 编写处理器单测,构造模拟类/注解输入。
- 断言查询结果与生成文件内容。
- 构建期必要时远程附加调试器到 KSP 进程。
- 通过日志定位符号读取偏差。
代码或图示
单测:模拟符号 → 处理器 → 断言生成代码
联调:真实模块 → 调试器附加 → 断点观察 Resolver
常见误区
- 只在大工程里改处理器看生成结果:反馈慢,应先隔离单测。
- 把调试 print 留在处理器生产代码:改用日志 API 并控制级别。
追问
- 处理器单测夹具怎么构造?答:使用 KSP 测试框架提供的编译/符号测试能力,具体 API 以当前版本为准。
- 生成代码错误如何反查?答:从生成类反推被处理源类,核对符号读取与模板输出。
04.8.3.2-018 KSP 处理器依赖如何声明?
一句话结论
处理器通过 KSP 专用 configuration(如 ksp(...))加入构建,与业务运行依赖分离;处理器本身及其编译期依赖不进业务运行 classpath。
概念解释
KSP configuration 只在符号处理阶段使用,处理器类由 KSP 加载执行。业务模块声明 KSP 依赖后,处理器随编译任务运行,产物源码再参与编译。处理器实现库版本与 KSP API 兼容。
原理流程
- 应用 KSP 插件。
- dependencies 中以 KSP configuration 声明处理器坐标。
- 构建期 KSP 从该配置加载处理器。
- 处理器输出源码进入编译源集。
代码或图示
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 同步后可查看生成类便于调试,但源文件以处理器重新生成为准。该目录与手工编写源码分离。
原理流程
- KSP 任务执行时创建生成源目录。
- 处理器写入
.kt/.java文件。 - Kotlin 编译任务把生成目录纳入 sourceSet。
- 产物随 jar 打包,生成目录本身不入库。
代码或图示
模块 build 目录下:generated/ksp/...(具体路径以 KGP 版本为准)
常见误区
- 直接修改生成目录中的类:下次构建被覆盖,改动丢失。
- 把生成目录纳入版本管理:生成物应忽略,重新构建生成。
追问
- 生成类在 IDE 中找不到?答:执行同步/构建让生成目录加入源集;检查 KSP 任务是否成功。
- 多 sourceSet 生成目录如何区分?答:按 sourceSet 分别生成,路径约定以插件文档为准。
04.8.3.2-020 KSP 与编译守护进程有什么关系?
一句话结论
KSP 任务在构建编排下运行,处理器类加载与执行可复用编译相关守护进程环境;处理器重、模块大时需关注处理阶段内存与进程复用配置。
概念解释
KSP 不是独立编译器前端,但其处理任务与 Kotlin 编译任务顺序衔接。构建守护进程复用影响启动开销,处理器本身的内存占用随符号规模增长。
原理流程
- Gradle daemon 调度 KSP 任务。
- 加载处理器实现与符号模型。
- 处理器执行生成逻辑。
- 交接给 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 提供文件写入。返回未处理列表供多轮调度判断。
原理流程
- 框架实例化处理器并注入环境。
- 每轮调用
process(resolver)。 - 处理器按注解过滤声明并生成代码。
- 返回剩余未处理符号,结束条件由框架判定。
代码或图示
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 任务图。
原理流程
- 框架初始化处理器时注入环境。
- 处理器通过 logger 报告信息与错误。
- 选项读取构建脚本传入的配置。
- 环境信息辅助判断处理范围。
代码或图示
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 表达,而不是直接挂在类声明上。
原理流程
- Resolver 按注解或名字取到类声明。
- 读取
packageName、simpleName。 - 访问
superTypes、declaredFunctions、declaredProperties。 - 结合注解参数决定生成逻辑。
代码或图示
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,并区分声明来源。
原理流程
- 从类声明取出函数/属性列表。
- 读取名称、类型与修饰符。
- 解析返回值/属性类型的可空性与参数。
- 按模板生成对应代码。
代码或图示
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 列表,需按类型判断目标节点。注解全限定名必须与源码一致,包名写错会查不到结果。
原理流程
- 构造注解全限定名。
resolver.getSymbolsWithAnnotation(...)获取符号。- 过滤目标声明类型。
- 读取注解参数并生成代码。
代码或图示
val annotated = resolver
.getSymbolsWithAnnotation("com.example.Gen")
.filterIsInstance<KSClassDeclaration>()
常见误区
- 用简单类名匹配注解:必须用全限定名,避免同名注解混淆。
- 未过滤类型直接当类声明访问:函数/属性标注会导致类型转换错误。
追问
- 重复标注同一类多个注解怎么办?答:遍历注解视图逐个匹配目标注解。
- 元注解(作用于注解类本身)如何处理?答:按注解声明节点查询,规则同上。
04.8.3.2-026 KSType 如何表达类型引用与可空性?
一句话结论
KSType 描述解析后的类型:含类型声明、类型参数与可空标记;可空性通过类型的 nullable 视图判断,原始类型引用与解析后类型区分使用。
概念解释
声明节点回答"是什么类",类型引用回答"变量/返回值的类型与可空性"。泛型实参挂在 KSType 上。未解析类型可能返回错误类型,处理器需做空值与错误判断。
原理流程
- 从函数/属性取得类型引用。
resolve()解析为 KSType。- 读取可空性、类型参数与声明。
- 生成代码时按类型拼写对应 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 后读取其声明与泛型实参;沿层次向上遍历需做访问与环检测。
概念解释
生成代理/适配器时常需知道类实现了哪些接口、继承哪个抽象类。父类型列表包含超类与接口;解析后可继续访问父类声明的成员。跨模块父类信息来自依赖符号模型。
原理流程
- 读取
cls.superTypes。 - 逐条 resolve 为 KSType 与 KSClassDeclaration。
- 判断是类还是接口,收集需要的方法签名。
- 必要时向上遍历父类链。
代码或图示
val interfaces = cls.superTypes.map { it.resolve().declaration }
.filterIsInstance<KSClassDeclaration>()
常见误区
- 只看直接父类忽略继承链:父类方法可能是生成目标。
- 遍历父类不防环:异常层次下递归不终止。
追问
- 如何判断某个接口被实现?答:解析父类型声明的全限定名做匹配。
- 泛型父类实参如何保留?答:从父类型 KSType 的 arguments 读取并映射到生成代码。
04.8.3.2-028 处理器如何生成文件(CodeGenerator)?
一句话结论
通过代码生成器按包名与文件名创建源文件或资源,写入生成内容;生成器处理目录归属与重名登记,处理器只提供内容文本或生成模型。
概念解释
生成 API 区分 Kotlin/Java 源码与资源。文件内容通常由模板字符串拼接,复杂模型可借助生成器的类型辅助。生成文件在后续轮次/编译中可见。
原理流程
- 处理器确定包名、类名与内容。
- 调用生成器创建对应类型文件。
- 写入源码/资源内容。
- 框架登记产物供编译任务纳入。
代码或图示
// 生成调用骨架(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 签名的映射,可空性与挂起函数表达受限。生成物语言应与消费方技术栈一致。
原理流程
- 确认生成代码被谁消费。
- Kotlin 消费:按 Kotlin 语法模板生成。
- Java 消费:映射签名为 Java 兼容形式。
- 编译期验证生成代码可编译。
代码或图示
// Kotlin 生成目标示例
class UserMapperImpl : UserMapper {
override fun toDomain(row: Row): User = TODO()
}
常见误区
- 生成 Kotlin 类却用 Java 平台类型假设:可空性处理不严谨。
- 在 Java 产物中暴露挂起函数:需映射为回调签名,复杂度高。
追问
- 混合消费方怎么选?答:以主要调用方语言为准,必要时生成两层适配。
- 生成代码风格由谁保证?答:处理器模板负责命名与格式,静态分析可对生成目录做豁免配置。
04.8.3.2-030 处理器之间的依赖与执行顺序如何确定?
一句话结论
多个处理器在同一 KSP 运行中按注册顺序依次处理,多轮模型衔接生成与读取;处理器间需要显式产物依赖时,应通过生成文件与轮次约定,避免依赖隐式顺序。
概念解释
处理器 A 生成的类可被处理器 B 在下一轮读取。执行顺序由注册/加载顺序决定,但跨处理器契约应显式化:B 不应假设 A 的内部实现,只依赖其生成产物命名约定。
原理流程
- 框架按注册顺序加载处理器。
- 每轮各处理器依次处理当前符号集合。
- 生成产物进入后续轮次。
- 依赖关系通过生成文件声明记录。
代码或图示
Processor A 生成 X.kt ──▶ Round 2 ──▶ Processor B 读取 X
常见误区
- 处理器间靠静态可变对象传递数据:轮次隔离下不可靠。
- 未登记生成依赖:增量构建时 A 的产物可能未及时更新给 B。
追问
- 如何强制两个处理器先后执行?答:按注册顺序配置,并通过多轮产物衔接;框架级排序能力以 KSP 文档为准。
- 处理器冲突重复生成同名类怎么办?答:命名规则区分职责,构建期检测重名。
04.8.3.2-031 如何判断一轮处理是否结束(rounding)?
一句话结论
每轮处理器返回未处理的符号集合;当一轮没有新生成符号、也没有待处理注解时,KSP 结束处理流程,进入编译阶段。
概念解释
结束判定由框架根据本轮新增产物与剩余待处理符号综合判断。处理器正确返回未处理项,避免框架误判还有工作。无限生成循环会被框架按轮次限制终止并报错。
原理流程
- 本轮处理器执行并生成文件。
- 返回剩余未处理符号。
- 框架检查是否存在新增符号/待处理注解。
- 无新增则结束,否则进入下一轮。
代码或图示
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 构建诊断。报告错误时带上类名/位置,帮助定位源码。处理器不应把可恢复的类型不确定打成致命错误,需分级处理。
原理流程
- 处理器在读取/生成过程中发现问题。
- 按严重级别调用 logger 方法。
- warn 进入报告继续流程,error 阻断任务。
- 构建输出展示诊断与符号位置。
代码或图示
logger.error("@Gen 只能标注在类上:${cls.simpleName.asString()}")
常见误区
- 用
println输出诊断:不走构建日志体系,CI 中难以聚合。 - 类型读取失败只告警不跳过:后续生成可能产出非法源码。
追问
- 日志能否关联源码位置?答:符号通常携带位置信息,logger 支持位置参数的 API 以版本为准。
- 处理器告警如何在 CI 门禁统计?答:纳入构建输出分析,具体规则按团队 CI 配置。
04.8.3.2-033 处理器读取源文件内容有哪些限制?
一句话结论
处理器基于符号模型读取声明与签名,不解析方法体实现逻辑;需要源码文本时能力受限,应避免把生成决策建立在方法体语句上。
概念解释
KSP 暴露结构信息(声明、类型、注解),不提供语句级 AST 遍历。方法体内的局部逻辑不可见。生成框架通常基于签名约定(接口、注解、属性)工作,不读实现体。
原理流程
- 符号模型提供声明节点。
- 节点暴露签名、类型、注解。
- 方法体语句不进入模型。
- 处理器按结构信息生成代码。
代码或图示
可读:类/函数/属性签名、注解、类型参数
不可读:函数体内的语句与局部变量实现
常见误区
- 想在处理器里分析方法体做代码改写:应考虑编译器插件而非 KSP。
- 依赖私有局部命名生成代码:局部信息不可见,生成不稳定。
追问
- 注解参数里的字符串常量可读吗?答:可读注解元素值,这属于声明级信息。
- 需要读取完整源码文件怎么办?答:符号模型不提供时,评估其他工具链;KSP 定位是结构处理。
04.8.3.2-034 泛型类型参数在 KSP 中如何解析?
一句话结论
类与函数声明持有类型参数列表,每个参数含名字、方差与上界;使用处的 KSType 携带实参类型,处理器需把声明参数与实参对应起来映射到生成代码。
概念解释
泛型声明(如 class Repository<T : Entity>)与泛型使用(Repository<User>)分别建模。生成实现类时要保留类型参数或填充实参。上界约束决定类型可调用的成员。
原理流程
- 读取声明的 typeParameters。
- 读取使用处 KSType.arguments 实参。
- 映射参数名到生成模板。
- 校验上界约束满足情况。
代码或图示
for (typeParam in cls.typeParameters) {
val bounds = typeParam.bounds.map { it.resolve() }
}
常见误区
- 生成代码丢掉类型参数:实现类签名与原接口不一致,编译报错。
- 实参为通配符时按具体类型处理:需区分 variance 与星投影。
追问
- 星投影在类型视图中如何表示?答:按类型参数实参的占位标识判断,具体 API 以版本为准。
- 递归泛型(自引用上界)如何处理?答:沿类型解析链读取,注意环与边界。
04.8.3.2-035 注解参数如何读取?
一句话结论
从声明的注解视图取得参数值,按类型读取字符串、布尔、枚举、类引用与嵌套数组;类引用进一步解析为符号类型。
概念解释
注解元素在 KSP 中以类型化视图提供,默认值与未显式设置需区分。类类型参数解析后可得 KSClassDeclaration;数组参数遍历逐项读取。读取失败要降级处理并记录诊断。
原理流程
- 找到目标注解视图。
- 按元素名取值并转换类型。
- 类引用参数 resolve 为声明。
- 参数值参与生成模板。
代码或图示
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 字段名以版本为准。
原理流程
- 读取类声明的种类与修饰符。
- 识别 sealed/inline/value 等特征。
- 按对应语言约束生成适配代码。
- 生成代码通过编译期类型检查。
代码或图示
sealed class 层次:可读取直接子类声明
value class:读取包装值属性,生成时遵守内联类约束
常见误区
- 给 value class 生成普通包装字段:违反内联类规则,编译报错。
- 忽略 sealed 子类封闭性:生成跨越层次的引用需谨慎。
追问
- sealed 子类在同一模块其他文件中可见吗?答:同一编译单元内符号模型可见,跨模块受可见性限制。
- 遇到不支持的声明类型如何处理?答:记录错误诊断并跳过生成,不要强行套用模板。
04.8.3.2-037 生成类的包名与命名冲突如何避免?
一句话结论
生成类包名通常基于被标注类包名加约定后缀(如 .gen),类名加固定后缀;同包重名由框架登记检测,处理器应在生成前做命名约定检查。
概念解释
稳定的命名规则让业务代码可引用生成类,也避免与手写类冲突。后缀选择应表达生成职责(Impl、Mapper、Serializer 等)。处理器不应随机命名或依赖源码顺序决定类名。
原理流程
- 取被标注类包名与简单名。
- 按约定拼接生成包名与类名。
- 生成器登记文件名,重名时报冲突。
- 业务代码按约定名字引用。
代码或图示
com.example.User → com.example.gen.UserMapperImpl
常见误区
- 生成类与手写类同名同包:编译期类冲突,需改后缀约定。
- 包名随处理器配置漂移:跨模块引用生成类时代码耦合路径不稳定。
追问
- 多个注解生成同一类怎么办?答:按职责区分后缀,或一个处理器聚合生成。
- 生成内部类还是顶层类?答:按框架约定选择;顶层类更易被其他文件引用。
04.8.3.2-038 KSP 处理器如何做单元测试?
一句话结论
用 KSP 测试框架构造最小编译工程与样例源码,运行处理器后断言生成文件内容、符号查询结果与日志诊断;不依赖完整业务工程即可回归。
概念解释
处理器逻辑分为符号读取与代码模板两部分。测试框架提供模拟编译环境,输入样例类/注解,收集 KSP 产物。测试覆盖正常生成、缺注解、类型不匹配等分支。
原理流程
- 准备样例源码与注解定义。
- 在测试环境运行处理器。
- 收集生成文件与诊断信息。
- 断言类名、字段、方法签名与错误输出。
代码或图示
测试输入:@Gen class Sample(...)
运行处理器 → 断言 SampleGen.kt 内容符合模板
常见误区
- 只测模板字符串不测符号读取:类型解析分支未覆盖。
- 测试依赖磁盘上的真实工程:环境迁移后不稳定。
追问
- 测试框架提供哪些能力?答:编译样例源码、调用处理器、读取生成产物;具体 API 以 KSP 测试库文档为准。
- 生成代码编译正确性如何验证?答:测试中对生成源码再做一次编译校验,避免产出非法 Kotlin。
04.8.3.2-039 KSP 处理器如何声明增量隔离?
一句话结论
处理器通过生成依赖声明记录读取的符号与产出文件关系,使增量分析能判断哪些产物需随源码变更更新;声明方式按 KSP 当前 API(聚合型/隔离型依赖)为准。
概念解释
KSP 增量依赖模型区分"聚合全部符号"与"按符号隔离"。处理器只读取局部符号时应声明细粒度依赖;遍历全量则退化为聚合型,变更波及整个处理器产物。
原理流程
- 生成文件时声明依赖的符号集合。
- 变更分析按映射判断受影响产物。
- 隔离良好的处理器只更新对应生成文件。
- 聚合声明下相关产物整体重生成。
代码或图示
// 生成文件时附带依赖声明(API 形态以当前版本为准)
Dependencies(aggregating = false, sources = listOf(cls))
常见误区
- 读取了符号却不声明依赖:增量下产物过期不更新。
- 处理器整体聚合却期待细粒度增量:能力与声明不匹配。
追问
- 如何检查处理器增量行为?答:改单个样例类,观察只更新对应生成文件。
- 隔离型处理器有何限制?答:不能跨符号全局汇总信息,需按框架模型设计。
04.8.3.2-040 处理器性能上有哪些注意点?
一句话结论
避免遍历全量符号做重复查询,缓存可复用的符号解析结果,控制生成代码量与字符串拼接;大模块下处理器自身遍历往往是 KSP 阶段主要耗时。
概念解释
Resolver 查询有成本,重复按名查找、反复 resolve 类型会放大开销。处理器应在一轮内组织好符号集合,减少重复遍历。生成大量文件时模板与 IO 也是开销来源。
原理流程
- 一轮内一次性取出目标注解符号。
- 类型解析结果按需缓存。
- 模板按模型批量生成。
- 构建报告核对处理器耗时分布。
代码或图示
优化:单次查询 → 分组处理 → 批量生成
避免:循环内反复按名查找、重复 resolve 同一类型
常见误区
- 在每个函数/属性处理时重新查询全局符号集:复杂度随规模上升。
- 生成未使用的辅助代码:产物膨胀,编译与打包变慢。
追问
- 如何定位处理器慢在哪一步?答:在处理器内分段计时或看构建报告,区分查询、解析与生成。
- 符号模型占用内存过大怎么办?答:缩小处理范围,避免保留无关符号引用。
04.8.3.2-041 kapt 的 stub 生成完整流程是怎样的?
一句话结论
kapt 先解析 Kotlin 源码编译出类签名模型,再为每个 Kotlin 类生成 Java 桩源(含包名、方法签名、字段与注解),交给 javac 启动注解处理,桩不进入最终产物。
概念解释
桩生成要把 Kotlin 签名翻译为 Java 兼容形式:挂起函数加 Continuation 参数、可空性转注解/平台类型、泛型映射为 Java 泛型。翻译完成后 javac 处理器在桩上按 JSR-269 工作。
原理流程
- KGP 注册 kapt 任务,输入 Kotlin 源码。
- 解析签名并生成桩视图。
- javac 加载桩并运行注册的注解处理器。
- 处理器生成源码,桩丢弃,交回 Kotlin 编译。
代码或图示
Kotlin 源码 → 签名解析 → Java stub → javac 注解处理 → 生成源码 → Kotlin 编译
常见误区
- 以为桩是手写或缓存的源码:桩由编译器按签名动态生成。
- 桩生成慢只归因于处理器:翻译阶段本身就有解析成本。
追问
- 桩生成产物落盘吗?答:在构建目录的 kapt 中间目录中,属于生成物,不入库。
- 桩包含方法体吗?答:不包含,只有签名供处理器读取。
04.8.3.2-042 kapt 的增量编译有哪些限制?
一句话结论
kapt 的增量粒度较粗:桩生成与 javac 处理链常按较大范围失效,单文件改动可能触发相关包甚至模块重新走 kapt 流程;增量能力不及 KSP。
概念解释
跨语言桩模型使变更分析难以精确到符号级。KGP 提供的 kapt 增量优化受桩映射与 javac 处理限制。工程实践中 kapt 阶段在热构建下仍明显耗时,这是迁移 KSP 的主要动因之一。
原理流程
- 检测源码变更。
- kapt 判断受影响桩集合(粒度较粗)。
- 重新生成桩并跑 javac 处理。
- 生成源码并入编译。
代码或图示
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 元数据或签名特征,稳定性有限。
原理流程
- 解析 Kotlin 挂起函数签名。
- 追加 Continuation 形参,返回类型映射为 Java 兼容类型。
- 桩方法暴露给 javac 处理器。
- 生成代码如需协程签名要额外适配。
代码或图示
// 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。
原理流程
- Kotlin 解析构建签名模型。
- 桩模型与 javac 符号表并存。
- 处理器及其依赖加载进处理进程。
- 生成代码占用额外内存。
代码或图示
kapt 内存 ≈ Kotlin 模型 + Java 桩模型 + javac 环境 + 处理器与生成代码
常见误区
- 只加业务测试 JVM 内存:kapt 处理进程内存需单独评估配置。
- 以为内存高是泄漏:多模型并存是结构性占用。
追问
- kapt OOM 怎么调?答:按 KGP 文档调整 kapt 进程内存参数;长期方案仍是迁移 KSP。
- 内存参数名随版本变化吗?答:以当前 KGP 文档为准,不写死未经验证的属性名。
04.8.3.2-045 kapt 处理器能否访问 Kotlin 私有成员?
一句话结论
桩按 Kotlin 可见性生成对应 Java 视图,私有成员不对外暴露;处理器不应假设能读取私有实现细节,访问受限成员在桩模型中不可见。
概念解释
可见性是声明级属性,kapt 在桩中保留访问修饰符。处理器处理的是类公开/受保护签名。需要读取内部结构的场景应重新评估注解位置与框架设计。
原理流程
- Kotlin 解析保留成员可见性。
- 桩按可见性映射 Java 修饰符。
- javac 处理器按 Java 可见性规则读取。
- 私有成员不在处理器可见范围。
代码或图示
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 编写。
原理流程
- 处理器坐标加入
kapt(...)配置。 - kapt 生成桩后启动 javac。
- javac 发现并加载注册的 Processor。
- 处理器读桩生成代码,流程与纯 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 阶段耗时与产物范围。
原理流程
- 配置 kapt 运行选项。
- 按模式生成桩、调用处理器或仅输出桩。
- 产物进入后续编译。
- 调试时检查中间桩目录。
代码或图示
完整模式:桩生成 + 注解处理 + 生成源码
调试模式:观察桩内容与映射结果
常见误区
- 把调试模式配置留在生产构建:可能跳过必要的处理步骤。
- 依赖未文档化的内部开关:版本升级后行为可能变化。
追问
- 如何查看生成的桩?答:检查构建目录下 kapt 中间输出;路径以 KGP 版本为准。
- kapt 校验严格度可调吗?答:按 KGP 提供的选项调整,不确定项标待确认。
04.8.3.2-048 kapt 慢主要慢在哪些环节?
一句话结论
主要耗时在 Kotlin 签名解析与桩生成、javac 启动与符号表构建、处理器遍历与生成代码;相比 KSP 多出跨语言模型转换与两轮解析。
概念解释
定位 kapt 慢要拆分阶段:桩生成是固定成本,处理器扫描是可变成本。大模块、处理器多、生成代码量大时各环节叠加。优化先测量再决定迁移还是裁剪处理器。
原理流程
- 构建报告拆分 kapt 任务各阶段耗时。
- 桩生成占比高:架构性成本,考虑 KSP。
- 处理器扫描占比高:优化处理器遍历范围。
- 生成代码多:评估是否减少生成量。
代码或图示
kapt 耗时 = 桩生成 + javac 环境 + 处理器执行 + 代码生成
常见误区
- 把 kapt 整体慢归为机器性能:结构性成本换机器无法消除。
- 不测量就盲目加内存:GC 占比不高时加堆收益有限。
追问
- 迁移 KSP 后桩生成环节还在吗?答:不在,KSP 直接读符号模型。
- 如何对比两个链路耗时?答:同一模块分别跑 kapt 与 KSP,对比任务时间与冷/热构建。
04.8.3.2-049 从 kapt 迁移 KSP 的常见阻塞点是什么?
一句话结论
阻塞点主要是目标库没有 KSP 处理器版本、处理器依赖 javac 专有 API、桩中可映射的 Kotlin 语义在 KSP 模型中需重新适配,以及生成代码链路回归验证。
概念解释
迁移顺序通常是:有 KSP 支持的库先切,仅 kapt 的保留;内部处理器按 KSP API 重写。迁移后需回归生成类编译、运行行为与增量效果。兼容窗口内两套链路可能短期并存。
原理流程
- 盘点工程 kapt 依赖与处理器。
- 按官方支持状态分组:可迁移 / 待生态 / 自研。
- 切换配置并修复处理器 API 适配。
- 全量回归生成代码与测试。
代码或图示
盘点 → 切有 KSP 的库 → 重写自研处理器 → 回归编译/测试/增量 → 移除 kapt
常见误区
- 一次性全部切换:生态不支持的库会阻断编译,应分批。
- 迁移后不对比生成代码:行为差异可能到运行期才暴露。
追问
- 迁移中两套配置并存有何风险?答:构建时间翻倍、产物可能重复,过渡期尽量短。
- 如何判断库 KSP 支持是否就绪?答:查库发布说明与坐标;版本能力不确定标待确认。
04.8.3.2-050 K2 编译器下 kapt 的维护状态如何?
一句话结论
K2 前端重写后,kapt 对新编译器的支持范围有限制,官方方向是 KSP 承接 Kotlin 代码生成;具体哪些 kapt 场景在 K2 下可用需以官方文档为准,标待确认并实测。
概念解释
kapt 依赖编译器内部签名导出能力,K2 重构后该适配需要持续跟进。新项目不应再以 kapt 为主要处理链;存量 kapt 在升级 Kotlin 大版本前先核对官方兼容说明。
原理流程
- 升级 Kotlin 到 K2 前查 kapt 兼容说明。
- 评估现有 kapt 处理器是否在支持范围内。
- 可迁移的切 KSP,受限场景暂缓升级或保留兼容版本。
- 构建期观察 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)约束。
原理流程
- 编译任务按脚本配置加载插件。
- 插件挂接到编译器对应阶段。
- 在 IR 或声明层做生成/改写。
- 输出字节码合并到产物。
代码或图示
源码 → 前端解析 → [插件挂载点] → IR → 后端字节码 → class
常见误区
- 把编译器插件与 KSP 处理器混为一谈:前者改写/参与编译内部,后者产出独立源文件。
- 以为插件跨 Kotlin 版本随意升级:插件绑定编译器内部 API,需配套版本。
追问
- 插件由谁提供?答:官方随 Kotlin 发布(序列化等)或第三方提供;坐标以官方文档当前版本为准。
- 插件能访问运行期信息吗?答:插件在编译期工作,只基于编译可见的源码与元数据。
04.8.3.2-052 编译器插件与注解处理器的分工是什么?
一句话结论
注解处理(KSP/kapt)产出新源文件、不改写原类;编译器插件可在 IR 层改写已有类的方法实现、调整声明形态,两者解决不同问题。
概念解释
生成独立实现类适合代理/映射场景;需要给原类加默认构造、打开类继承、转换组合函数等场景由插件完成。实际框架常组合使用:插件调整编译形态,处理器生成辅助类。
原理流程
- 判断需求:新增类 → 注解处理;改写既有类/方法 → 编译器插件。
- 处理器生成源码并入编译。
- 插件在编译管线中作用于 IR。
- 最终字节码包含两者产物。
代码或图示
KSP/kapt:新增 *.kt 源文件
IR 插件:修改原类 IR / 字节码形态
常见误区
- 想用 KSP 给原类加方法:KSP 只能生成新类,改写归插件。
- 把所有生成需求都做成 IR 插件:开发与维护成本高,优先生成新类方案。
追问
- 一个框架能同时用两种机制吗?答:可以,按职责组合,如插件调整开放度、处理器生成实现。
- 插件改写如何在调试时观察?答:反编译最终字节码或查看插件报告,确认 IR 变换结果。
04.8.3.2-053 IR 插件工作在编译器的哪个阶段?
一句话结论
IR(中间表示)插件在前端生成 IR 之后、后端产出字节码之前介入,遍历并变换 IR 树,可替换方法体、新增指令或调整声明。
概念解释
Kotlin 编译器先把源码翻译为 IR,再由后端生成字节码/原生代码。IR 插件操作这棵中间树,比改 AST 更接近最终产物。IR 结构随编译器版本演进,插件 API 稳定性需关注。
原理流程
- 前端解析源码构建 IR。
- IR 插件按规则遍历节点。
- 变换方法体/声明/表达式。
- 后端基于变换后 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 编译器版本配套,不单独随意升级。
原理流程
- 构建脚本应用插件或开启选项。
- KGP 把插件加入编译配置。
- 编译进程加载插件并挂接阶段。
- 编译时执行变换。
代码或图示
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 场景一般不引入该插件。
原理流程
- 标注
@Composable的函数进入插件处理范围。 - 插件在 IR 层插入分组与状态读取跟踪。
- 生成带重组元信息的字节码。
- 运行期组合调度器依据元信息执行。
代码或图示
@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 库使用这些生成器。插件必须与编译器版本配套。
原理流程
- 类标注
@Serializable。 - 插件在编译期为其生成序列化器类。
- 运行期调用生成器读写结构。
- 嵌套类、泛型按生成器组合处理。
代码或图示
@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。
原理流程
- 配置 allopen 关联的注解。
- 编译期扫描标注类。
- 插件在 IR/字节码层把类与成员改为 open。
- 框架代理可继承该类。
代码或图示
// 配置示意(具体 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 按注解在编译期合成该构造,字段在构造中取默认/零值,初始化逻辑需注意。
原理流程
- 配置 noarg 关联注解。
- 编译期为标注类生成无参构造。
- 构造内按类型默认值初始化字段。
- 框架反射调用无参构造实例化。
代码或图示
// 配置示意(DSL 以官方文档为准)
noArg {
annotation("com.example.NoArg")
}
常见误区
- 以为生成的无参构造会执行属性初始化逻辑:合成构造的字段状态需按插件实现确认,业务初始化应在后续方法完成。
- 必填非空属性被无参构造绕过:可能产生未初始化状态,设计时核对。
追问
- noarg 与 allopen 常一起用吗?答:常见于需要代理 + 反射实例化的框架场景,两者独立配置。
- 生成构造在反编译中可见吗?答:可见,属于编译期合成的字节码成员。
04.8.3.2-059 parcelize 插件在本视角下如何定位?
一句话结论
parcelize 是面向 Android Parcelable 协议的编译器插件,生成序列化桥接代码;属于端侧框架能力,本节只说明其插件性质,具体用法见 07 端侧分册。
概念解释
它与序列化插件同属"编译期生成协议适配代码"的插件模式,目标平台是 Android。JVM 后端工程不引入该插件。了解其分类有助于区分编译器插件的不同目标场景。
原理流程
- 类实现对应接口并标注。
- 插件生成协议读写方法。
- 端侧框架调用生成方法完成对象序列化。
代码或图示
parcelize:端侧 Parcelable 适配(详见 07 分册)
常见误区
- 在后端 JVM 模块引入端侧插件:目标平台不匹配,编译报错。
- 混淆 JVM 序列化与端侧协议:两者生成机制与运行环境不同。
追问
- 编译器插件都按平台隔离吗?答:插件按目标平台加载,跨平台插件需在 KMP 中按目标配置。
- 后端对象序列化选什么?答:kotlinx-serialization 等 JVM 可用方案,见 04.8.4 分册。
04.8.3.2-060 编译器插件改写与 KSP 生成新类的本质区别是什么?
一句话结论
KSP 产物是独立新源文件,原类不动;编译器插件在既有类的 IR/字节码上做变换,原类结构被直接修改。
概念解释
生成新类便于调试与引用,边界清晰;改写原类能力更强但影响编译器内部模型,维护成本高。选型优先"生成新类"方案,确需改变原类行为时才做插件。
原理流程
- KSP:输出新文件,编译时与原类并存。
- 插件:遍历原类 IR 并就地变换。
- 两者产物最终都进字节码。
- 调试时分别查看生成源码与反编译结果。
代码或图示
KSP:User.class + UserMapperImpl.class(新增)
插件:User.class 内部方法体/开放度被调整
常见误区
- 把插件生成的辅助代码当成独立源码阅读:部分变换在反编译中才可见。
- 评估插件成本只看开发:K2 升级时插件适配风险也要计入。
追问
- 哪些变换只能插件做?答:给原类加默认构造、打开继承、改写方法体、插入跟踪元信息。
- 生成新类方案有何限制?答:无法改变原类 final/开放等固有形态。
04.8.3.2-061 编译器插件对 jvmTarget 与 IR 版本敏感吗?
一句话结论
敏感:插件绑定编译器内部 IR 结构与 API,Kotlin 版本、前端模式(K1/K2)变化可能要求插件同步升级;跨版本直接复用旧插件有加载或变换失败风险。
概念解释
后端字节码版本(jvmTarget)影响代码生成目标,IR 结构变化影响插件遍历逻辑。官方插件随 Kotlin 发布配套版本;第三方插件需声明兼容的编译器版本范围。
原理流程
- 插件编译期引用编译器内部 API。
- 运行期与当前编译器 IR 结构匹配。
- 版本不匹配:类链接失败或 IR 节点类型不符。
- 升级编译器时同步升级插件。
代码或图示
Kotlin 编译器版本 ──配套──▶ 编译器插件版本
常见误区
- 只升级业务 Kotlin 不改配套插件:编译期变换失败。
- 在 CI 上缓存旧插件 class 跨大版本复用:版本不匹配应重新解析。
追问
- 如何查插件兼容版本?答:插件发布说明与 Kotlin 兼容矩阵;不确定标待确认。
- 插件报 IR 节点类型错误一般是什么原因?答:插件版本与编译器前端不配套,先对齐版本。
04.8.3.2-062 自定义编译器插件的开发门槛在哪里?
一句话结论
门槛在于理解编译器 IR 结构、插件扩展点注册与跨版本适配;相比 KSP 处理器,IR 插件需要更深的编译器内部知识,且随前端演进维护成本更高。
概念解释
自定义插件要实现编译器扩展点、遍历 IR 树、构造合法节点,并处理类型与作用域校验。K2 迁移期还需跟踪 IR 变化。除非框架必须改写原类,否则优先选择生成新类或外部库方案。
原理流程
- 确定变换点与目标 IR 节点。
- 实现插件扩展点并注册。
- 遍历变换 IR,保证类型合法。
- 随编译器版本回归适配。
代码或图示
评估顺序:外部库 → KSP 生成新类 → 自定义 IR 插件(最后选择)
常见误区
- 为简单代码生成需求自研 IR 插件:成本与维护风险过高。
- 忽略插件测试:IR 变换错误可能导致非法字节码,需编译器级测试覆盖。
追问
- 官方有插件开发指南吗?答:Kotlin 编译器插件开发文档是起点;内部 API 稳定性需自行评估。
- 插件需要发布吗?答:内部工具插件可随构建工程分发,对外发布需提供 marker 与版本兼容声明。
04.8.3.2-063 编译器插件的命令行参数如何传递?
一句话结论
插件选项通过 KGP 编译配置或插件专属 extension 传入,最终转为编译器插件参数;参数名与取值以各插件官方文档为准,不在脚本中臆造。
概念解释
部分插件支持开关、注解包名、输出策略等配置。这些选项在构建脚本中声明,编译任务转发给插件。配置缺失时插件使用默认值,不符合约定会在编译期告警或报错。
原理流程
- 脚本在插件 extension 或编译选项中设置参数。
- KGP 收集参数传给编译器。
- 插件读取参数调整变换行为。
- 编译产物按配置生成。
代码或图示
// 示意:插件配置入口(具体 DSL 以官方文档为准)
kotlin {
compilerOptions {
// 插件相关编译选项
}
}
常见误区
- 把业务运行配置塞进插件参数:插件参数只服务编译期变换。
- 凭记忆写未文档化的参数名:版本升级后可能被忽略或报错。
追问
- 插件参数能否按模块区分?答:可在各模块编译配置中分别设置。
- 如何确认参数生效?答:观察编译产物变化或插件日志输出。
04.8.3.2-064 编译器插件在 K2 下需要做什么迁移?
一句话结论
K2 重写前端后,插件挂载点与 IR 模型可能变化,需使用适配 K2 的插件版本并回归变换结果;自研插件需对照 K2 迁移说明调整遍历与节点构造。
概念解释
官方插件随 Kotlin 2.x 提供 K2 适配版本。第三方插件可能滞后。升级编译器前先核对插件 K2 支持状态,保留旧前端 fallback 的时间窗口以官方说明为准。
原理流程
- 查各插件 K2 兼容状态。
- 升级到适配版本。
- 编译验证变换产物(生成器、开放度、构造等)。
- 自研插件按迁移说明改造 IR 访问代码。
代码或图示
K2 升级:插件版本核对 → 编译回归 → 产物反编译核对
常见误区
- 假设旧插件无缝工作于 K2:内部 API 变化可能直接不兼容。
- 只跑编译不核对运行行为:变换错误可能延迟到运行期暴露。
追问
- 如何知道插件是否支持 K2?答:发布说明标注前端支持;未标注的在 K2 工程实测并记录待确认。
- K1 兼容期有多长?答:以 Kotlin 官方路线说明为准,不臆测截止版本。
04.8.3.2-065 序列化插件如何为 @Serializable 类生成序列化器?
一句话结论
插件分析类属性、类型与可选注解,编译期生成实现 KSerializer 的代码,包含结构序列化解构与重建逻辑;标准类型由运行期库提供序列化器,嵌套类型组合引用。
概念解释
生成器按属性顺序读写结构,处理可选默认值与命名策略。泛型类的序列化器携带类型参数。手写序列化器用于插件无法自动处理的定制类型。
原理流程
- 识别
@Serializable标注类。 - 收集属性名、类型、可选性。
- 生成
serialize/deserialize实现。 - 运行期 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。
原理流程
- 框架约定需要代理的注解。
- allopen 配置关联该注解。
- 编译期标注类变为可继承。
- 运行期框架生成子类代理。
代码或图示
Kotlin final 类 ──allopen──▶ 字节码 open 类 ──▶ 框架子类代理
常见误区
- 以为手写
open与 allopen 等价:都开放继承,区别在源码声明 vs 编译期合成。 - 给数据类盲目开放:继承约束可能影响 equals/hashCode 约定。
追问
- 接口代理需要 allopen 吗?答:基于接口的代理不依赖类开放;子类化代理才需要。
- 如何确认类已开放?答:反编译查看类修饰符,或运行期代理是否成功创建。
04.8.3.2-067 noarg 生成无参构造的典型用途是什么?
一句话结论
供反射实例化框架在无参情况下创建对象:框架先调无参构造得到空对象,再通过字段/属性赋值填充状态;类源码不必显式写空构造。
概念解释
ORM、部分序列化与 DI 框架依赖无参构造。Kotlin 类有必填属性时默认不生成无参构造,noarg 合成一个满足框架反射要求的构造。字段初始状态按插件规则处理,业务赋值由框架后续完成。
原理流程
- 标注类进入 noarg 范围。
- 编译期合成无参构造。
- 框架反射调用构造实例化。
- 框架写入字段后对象投入使用。
代码或图示
@NoArg
data class User(var name: String = "", var age: Int = 0)
常见误区
- 无参构造后直接使用对象:字段可能未完成业务初始化,需框架赋值流程完整。
- 把必填非空属性交给无参构造绕过:状态不合法风险,设计上用默认值或工厂方法。
追问
- noarg 构造会调用属性初始化器吗?答:按插件实现确认,不确定处标待确认;关键初始化不要依赖合成构造。
- 与 JVM 无参构造规则兼容吗?答:生成的是 JVM 可见无参构造,供反射框架使用。
04.8.3.2-068 编译器插件产物是否进入业务 classpath?
一句话结论
插件变换作用于编译产出的字节码,生成的辅助类/序列化器随模块 jar 进入业务 classpath;插件自身实现只在编译期存在,不打进运行产物。
概念解释
区分两类产物:插件编译期生成/变换的结果属于业务产物;插件处理器 jar 是构建工具,不随业务发布。运行期库(如序列化运行库)则需显式声明为业务依赖。
原理流程
- 编译期插件加载并变换/生成代码。
- 生成类编译进模块 jar。
- 插件实现 jar 留在构建 classpath。
- 运行期库由业务 dependencies 引入。
代码或图示
插件 jar:构建期,不打包
生成序列化器 class:随 jar 打包
运行期序列化库:业务显式依赖
常见误区
- 把编译器插件坐标加进 implementation:应走插件应用配置,而非业务依赖。
- 遗漏运行期库:生成器存在但缺少编码解码实现,运行期报错。
追问
- 生成类在运行期被谁调用?答:业务代码或运行期库按序列化器约定调用。
- 插件依赖会传递给下游模块吗?答:构建期插件不传递;其生成产物随 jar 传递。
04.8.3.2-069 编译器插件与 ASM 字节码增强有何区别?
一句话结论
Kotlin 编译器插件在编译期基于 IR 参与生成过程,理解 Kotlin 语义;ASM 是在编译后直接操作 class 字节码,两者层级与信息保真度不同。
概念解释
IR 插件在源码到字节码的管线内工作,能利用类型与声明信息;ASM 方案面对已生成 class,按字节码指令改写。JVM 生态的字节码增强库多基于 ASM,Kotlin 侧优先官方编译器插件机制。
原理流程
- 源码 → Kotlin 编译 → IR 插件变换 → class 字节码。
- ASM 路径:class 产物再被字节码工具读取改写。
- 插件理解 Kotlin 结构,ASM 只看字节码。
- 最终都作用于产物字节码。
代码或图示
编译期:IR 插件(源码语义可见)
编译后:ASM 增强(指令级改写)
常见误区
- 用 ASM 改 Kotlin 字节码忽略元数据:可能破坏 Kotlin 类元数据与可空性信息。
- 把编译器插件当运行期增强 agent:二者加载时机不同。
追问
- 后端 JVM 生态有哪些 ASM 类工具?答:如字节码增强/代理库,本节点到为止,具体框架见 06/09 分册。
- 何时选 ASM 方案?答:跨语言 class 增强、编译后织入场景;Kotlin 原生改造优先编译器插件。
04.8.3.2-070 插件错误信息常见来自哪里?
一句话结论
常见来源包括插件与编译器版本不配套、被标注类违反插件约束、生成代码类型不匹配、插件读取了不支持的声明类型;错误通常在编译期插件阶段暴露并指向对应类。
概念解释
报错链路:插件加载失败(版本/类缺失)、处理中校验失败(注解目标错误)、生成源码编译失败(模板与类型不符)。按错误阶段区分是插件自身问题还是被标注代码问题。
原理流程
- 编译任务加载插件:版本不匹配则链接失败。
- 插件遍历声明:约束不满足抛诊断。
- 生成代码并入编译:类型错误在编译阶段暴露。
- 按堆栈与类定位修复。
代码或图示
加载期:插件类/版本问题
处理期:注解目标与声明约束问题
编译期:生成代码类型问题
常见误区
- 把生成代码编译错误当作业务源码错误:先追溯是哪个处理器/插件产出。
- 报错只看最后一行:插件诊断常附带被标注类位置。
追问
- 如何区分 KSP 产物错误与插件变换错误?答:按任务名与生成目录归属判断。
- 升级插件后报错如何回退?答:回到配套版本组合,再逐项适配新行为。
04.8.3.2-071 多个编译器插件之间的执行顺序如何确定?
一句话结论
插件按编译器注册顺序挂接到 IR 管线,后注册的插件在前一个变换后的 IR 上继续工作;顺序敏感的组合需在构建配置中明确先后,避免变换结果互相覆盖。
概念解释
不同插件作用于不同节点:序列化生成、开放度调整、组合函数转换各有挂载点。多数场景互不干扰,但同时改写同一类方法体时顺序会影响最终字节码。插件顺序由应用/注册顺序决定,框架级顺序约定以官方文档为准。
原理流程
- 编译任务按配置顺序加载插件。
- 各插件在对应阶段遍历 IR。
- 后一插件读取前一插件变换结果。
- 后端基于最终 IR 生成字节码。
代码或图示
IR 原始 → 插件 A 变换 → 插件 B 变换 → 后端字节码
常见误区
- 假设插件顺序无关:改写同一节点时顺序敏感。
- 两个插件竞争调整同一修饰符:后生效者覆盖,需核对最终产物。
追问
- 如何调整插件顺序?答:按构建脚本中的应用顺序配置;插件间官方约定的顺序以文档为准。
- 顺序问题如何复现?答:反编译对比不同顺序下的字节码差异。
04.8.3.2-072 插件对源码可访问性有什么影响?
一句话结论
插件可在产物层调整开放度、合成构造等形态,但不改变源码声明的包结构与源码可见性;运行期反射看到的是变换后的字节码修饰符。
概念解释
allopen/noarg 类插件只改产物成员形态,源码文件仍按原声明阅读。反射框架在运行期读取字节码修饰符,因此能看到开放类与无参构造。插件不应改变包名或把私有成员暴露为公开。
原理流程
- 源码声明保持不变。
- 插件在 IR/字节码层调整修饰符或合成成员。
- 产物 class 反映变换后形态。
- 反射与代理按产物形态工作。
代码或图示
源码:final class User
产物:open class User(allopen 变换后)
常见误区
- 以为源码会被插件改写落盘:插件作用于编译产物,不回写源文件。
- 依赖插件暴露私有成员:可见性调整能力有限,不应作为设计绕过手段。
追问
- 反编译看到的修饰符以哪个为准?答:以编译产物为准,源码与产物差异来自插件变换。
- 插件合成成员在源码导航中可见吗?答:IDE 可能从产物索引到,源码文件中不显示。
04.8.3.2-073 编译器插件在多平台编译中有什么差异?
一句话结论
同一插件在不同目标平台(JVM/JS/Native)的挂载能力与产物形态可能不同;部分插件仅支持 JVM,KMP 工程需按目标核对插件支持范围。
概念解释
KMP 各目标后端代码生成路径不同,插件对前端 IR 的支持也可能分平台。序列化插件跨平台支持较完整;端侧专用插件只在对应目标生效。配置时按目标平台分组启用。
原理流程
- KMP 工程声明各目标。
- 插件按支持范围挂接到对应编译任务。
- 不支持的目标跳过或报错。
- 各目标产物按其后端规则生成。
代码或图示
JVM 目标:JVM 插件全量可用
其他目标:仅支持跨平台的插件生效
常见误区
- 假设 JVM 插件自动适用于所有 KMP 目标:平台不支持时编译报错。
- 在公共源码集引入平台专用插件 API:公共代码应保持平台无关。
追问
- 如何查插件的平台支持?答:插件文档标注支持目标;未标注的在对应目标实测。
- 本工程是后端 JVM 视角:多平台细节见 KMP 相关章节,本节不展开端侧配置。
04.8.3.2-074 如何排查编译器插件未生效?
一句话结论
按"插件是否应用 → 版本是否配套 → 标注是否命中 → 产物是否出现"逐层排查:先确认插件在编译配置中加载,再核对版本与标注目标,最后检查生成/变换产物。
概念解释
未生效常见原因:插件未在脚本应用、坐标加错 configuration、注解包名不匹配、插件版本与编译器不兼容被跳过。排查从构建任务与产物反推,而不是直接怀疑运行库。
原理流程
- 检查
plugins{}/编译配置是否声明插件。 - 核对插件与 Kotlin 版本配套。
- 确认被标注类注解全限定名正确。
- 检查生成目录/反编译产物是否出现变换结果。
代码或图示
排查链:插件应用 → 版本配套 → 注解命中 → 产物出现
常见误区
- 运行期报序列化器缺失就去查运行库:先确认编译期插件是否生成了序列化器。
- 注解写错包名却以为插件没加载:注解不命中时插件自然无产物。
追问
- 如何看插件是否被编译任务加载?答:查看编译任务配置与构建日志中的插件加载信息。
- 插件静默跳过怎么办?答:开启插件诊断日志,核对版本兼容与注解匹配。
04.8.3.2-075 Room 如何用 KSP 生成 DAO 实现?
一句话结论
Room 的 KSP 处理器读取 @Dao 接口与 @Query/实体注解,在编译期生成 DAO 实现类,把方法调用翻译为 SQL 执行与结果映射;本节从生成链路视角说明,端侧数据库细节见 07 分册。
概念解释
处理器解析接口方法签名、SQL 语句与实体字段映射,生成实现类:查询方法绑定参数、执行 SQL、把行映射为实体。KSP 替代早期 kapt 链路,生成代码参与编译。
原理流程
- 实体与 DAO 注解被 KSP 收集。
- 处理器校验 SQL 与字段映射(能力随版本)。
- 生成 DAO 实现类与映射辅助代码。
- 运行期业务调用生成实现完成数据库操作。
代码或图示
@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 链路,减少编译期生成依赖。
原理流程
- 定义表对象与列。
- 查询通过 DSL 构造语句。
- 运行期执行 SQL 并映射结果行。
- 无编译期生成类参与。
代码或图示
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 官方当前版本为准,不确定处标待确认。
原理流程
- 数据类标注对应适配器生成注解。
- KSP 处理器收集属性与命名配置。
- 生成 JSON 适配器类。
- 运行期 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 库,避免编译期生成链路。
原理流程
- 盘点工程使用的 DI 框架。
- 查官方 KSP/kapt 支持状态。
- 按支持链路配置对应处理器。
- 升级时随框架发布切换。
代码或图示
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 产物。
原理流程
- Java 处理器类标注
@AutoService(Processor::class)。 - 注解处理期生成服务注册文件。
- javac/SPI 按清单加载处理器。
- KSP 处理器走自身注册机制。
代码或图示
javac 处理器:META-INF/services 注册文件
KSP 处理器:KSP 服务发现机制(以文档为准)
常见误区
- 给 KSP 处理器加 AutoService 注解:注册机制不匹配,无效。
- 忽略服务注册文件生成:处理器不被框架发现。
追问
- 自研 KSP 处理器如何注册?答:按 KSP 文档提供的服务清单/工厂方式配置,具体格式以版本为准。
- 服务注册文件会进产物吗?答:对应链路的注册文件随处理器 jar 打包。
04.8.3.2-080 Room 生成的表映射代码位于哪里?
一句话结论
生成的 DAO 实现与映射辅助类位于 KSP 生成源码目录,编译后进入模块 jar;业务代码 import 生成类由处理器按约定命名产出,不手工编辑。
概念解释
生成类包名通常与 DAO 接口相关联,类名加实现后缀。IDE 同步后可跳转查看生成代码用于调试。清理构建目录后重新生成,生成物不纳入版本管理。
原理流程
- KSP 任务输出到生成源目录。
- DAO 实现类与映射代码写入该目录。
- Kotlin 编译纳入生成源码。
- class 产物随 jar 打包。
代码或图示
生成目录:build/generated/ksp/...(路径以 KGP 版本为准)
常见误区
- 修改生成实现类补逻辑:下次构建被覆盖,应改 DAO 接口或实体定义。
- 把生成目录提交到版本库:生成物应忽略。
追问
- 生成类找不到符号怎么办?答:确认 KSP 任务成功、生成目录已加入源集;重新同步 IDE。
- 多个模块生成类重名?答:按包名与模块隔离,处理器命名约定区分。
04.8.3.2-081 序列化插件如何替代反射?
一句话结论
序列化插件在编译期把字段读写逻辑生成进序列化器 class,运行期直接调用生成代码,不再通过反射枚举字段或读取注解,降低反射开销与运行期字段扫描风险。
概念解释
反射式序列化依赖运行期读取类结构,字段更名/可见性问题延迟到运行期暴露;编译期生成在编译阶段就完成类型检查。生成器仍需运行期格式库承担编码解码。
原理流程
- 编译期分析类结构生成序列化器。
- 字段读写逻辑固化在 class 中。
- 运行期按生成器直接访问字段。
- 格式库负责 JSON/结构编码。
代码或图示
反射链路:运行期扫描字段 → 读写
生成链路:编译期生成读写代码 → 运行期直接调用
常见误区
- 以为生成链路完全不需要运行期库:生成器只处理结构映射,格式编解码仍依赖库。
- 生成器可绕过可见性约束:字段访问按 Kotlin/JVM 规则生成。
追问
- 反射序列化有何适用场景?答:动态类型、插件化扩展场景;固定数据结构优先编译期生成。
- 字段改名对生成链路影响?答:编译期按当前字段生成,改名同步更新序列化映射声明。
04.8.3.2-082 路由与 DI 框架常见的生成模式有哪些?
一句话结论
常见模式包括:扫描注解收集注册项生成路由表/工厂类、为接口生成实现代理、为注入点生成构造工厂;均在编译期产出连接代码,业务代码按生成类引用。
概念解释
路由框架收集 @Route 标注类生成路径到处理器的映射;DI 框架生成依赖工厂与注入连接。生成模式可组合:处理器收集符号,生成新类,必要时配合插件调整形态。
原理流程
- 处理器扫描注解与声明。
- 汇总注册表/工厂模型。
- 生成连接代码(映射表、工厂、代理)。
- 运行期业务调用生成类完成分发/组装。
代码或图示
扫描 @Route → 生成路由表
扫描 @Inject → 生成工厂与注入连接
常见误区
- 假设框架运行期动态扫描类路径:很多框架用编译期注册表,新增类必须被处理器扫到。
- 生成注册类与手写注册重复维护:以生成链路为准,避免双写。
追问
- 后端路由框架是否走生成链路?答:按具体框架;Ktor 等多为运行期路由声明,详见 06 分册。
- 生成注册表增量失效怎么办?答:新增标注类后重新跑处理器,确认注册表更新。
04.8.3.2-083 生成代码与运行期反射在编译期还是运行期工作?
一句话结论
KSP/kapt/编译器插件的生成工作发生在编译期;产物类在运行期被调用,运行期不再重复扫描注解(除非框架另设计反射回退)。
概念解释
区分"生成时机"与"产物运行时机":编译期处理器产出类,运行期业务调用产物。反射框架则在运行期读取类结构。两条链路混用会造成双重开销,设计时明确主路径。
原理流程
- 编译期:处理器/插件扫描源码并产出代码。
- 编译:产物类编入 jar。
- 运行期:直接调用产物类方法。
- 反射链路:运行期读取类结构并动态调用。
代码或图示
编译期生成 ──▶ 产物 class ──▶ 运行期直接调用
运行期反射 ──▶ 运行期扫描结构 ──▶ 动态调用
常见误区
- 以为生成类运行期还会重读注解:生成完成后注解信息已固化进代码。
- 在生成产物上再套反射代理:额外开销且易错,应理清职责。
追问
- 如何判断某库是生成还是反射?答:查文档与依赖中是否含处理器配置;看编译产物是否有生成类。
- 生成类能被反射二次利用吗?答:技术上可以,但非框架设计主路径。
04.8.3.2-084 生成类如何被业务代码引用?
一句话结论
业务代码按处理器约定的包名与类名 import 生成类;生成类在编译期进入源集,编译期即可被解析引用,无需运行期注册查找。
概念解释
生成类与手写类在编译 classpath 上并列。命名约定稳定后业务直接引用接口返回类型或生成实现。处理器提供工厂访问点(如 serializer())降低直接引用生成类的耦合。
原理流程
- 处理器按命名约定产出生成类。
- 生成源码加入编译源集。
- 业务代码 import 并引用。
- 编译器解析生成类符号。
代码或图示
// 业务侧引用生成能力(具体入口按框架约定)
val adapter = User.serializer()
常见误区
- 业务代码手写实现类名猜测生成类:应按框架文档约定引用入口。
- 生成类包名随模块漂移导致 import 断裂:命名约定需稳定。
追问
- 生成类需要手写接口声明吗?答:处理器通常围绕已有接口/标注类生成实现,业务定义接口与模型。
- IDE 报生成类无法解析?答:重新同步/构建生成源集,检查处理器任务是否成功。
04.8.3.2-085 增量构建下生成代码有哪些失效场景?
一句话结论
源码签名变更、新增/删除标注类、处理器依赖声明不全、构建脚本或处理器版本变化,都可能使生成产物失效重生成;未声明依赖会导致旧代码残留。
概念解释
增量分析依赖符号到产物的映射。标注类增删、属性签名变化属于输入变更;处理器未声明读取来源时,变更不触发对应产物更新。处理器版本升级整体刷新生成结果。
原理流程
- 检测源码与配置变更。
- 按依赖映射判定受影响生成文件。
- 失效文件重新生成。
- 未声明依赖的变更可能漏更新。
代码或图示
变更类签名 → 对应生成类重生成
新增 @Gen 类 → 新生成类产出
处理器升级 → 全量重新生成
常见误区
- 改了模型字段但生成代码未更新:检查处理器依赖声明与增量状态,必要时 clean 重建。
- 残留旧生成类导致编译冲突:清理生成目录后重建。
追问
- 如何验证增量更新正确?答:改单字段,核对对应生成类变化、无关生成类不动。
- 生成类删除后旧文件残留?答:处理器应管理产物清理;异常残留时 clean 构建目录。
04.8.3.2-086 多轮处理中新生成的符号能否被下一轮读取?
一句话结论
可以:KSP 多轮模型把本轮生成的新符号纳入后续轮次供其他处理器读取;这是处理器之间生成—消费衔接的机制基础。
概念解释
若处理器 A 生成的类需要处理器 B 再加工,B 在后续轮次看到 A 的产物。轮次结束条件与未处理符号返回需正确实现。并非所有生成内容都自动可见,依赖多轮调度规则。
原理流程
- Round 1:A 生成新类。
- 新符号进入下一轮集合。
- Round 2:B 读取并处理。
- 无新增后结束。
代码或图示
A 生成 X ──▶ Round 2 ──▶ B 处理 X
常见误区
- 假设同一轮内后注册处理器能看到先生成类:需跨轮次衔接。
- 处理器间靠全局变量传新符号:应通过生成文件与符号模型传递。
追问
- kapt 是否有类似多轮?答:javac 注解处理本身有多轮机制,kapt 桥接该流程;模型保真度受限。
- 如何调试跨轮产物?答:逐轮检查生成目录与处理器日志。
04.8.3.2-087 第三方库处理器版本与 Kotlin 版本如何保持兼容?
一句话结论
按官方兼容矩阵选择处理器版本:KSP 处理器版本绑定 Kotlin 版本区间,kapt 处理器跟随 javac 生态;升级 Kotlin 前先确认各库处理器已发布兼容版本。
概念解释
处理器编译期引用编译器/API,版本错位在处理阶段报错。多库工程需同时满足各自兼容窗口。版本目录集中登记,升级时按矩阵联动核对,不单独追新某一处理器。
原理流程
- 确定目标 Kotlin 版本。
- 逐个核对库处理器兼容版本。
- 目录登记配套组合。
- 构建验证全部生成链路。
代码或图示
Kotlin 2.0.x ──▶ 配套 KSP 版本 ──▶ 各库处理器兼容版本
常见误区
- 只升级业务库不升级其处理器:生成链路与运行库版本不匹配。
- 忽略库发布说明中的 Kotlin 兼容要求:编译期问题在集成阶段才暴露。
追问
- 处理器版本与运行库版本必须一致吗?答:按框架发布说明确认;通常处理器与库版本配套。
- 兼容窗口空窗怎么办?答:暂不升级 Kotlin,等待处理器发布支持版本。
04.8.3.2-088 如何确认项目用的是 KSP 还是 kapt?
一句话结论
检查构建脚本:存在 KSP 插件与 ksp(...) 配置即走 KSP;存在 kotlin-kapt 插件与 kapt(...) 配置即走 kapt;两者也可能短期并存。
概念解释
处理器坐标所在 configuration 决定加载链路。任务图中 KSP 任务与 kapt 任务名称不同,构建报告可区分。并存时两类任务都会出现,应核对是否为过渡状态。
原理流程
- 查看
plugins{}中的 KSP/kapt 插件声明。 - 检查 dependencies 中处理器配置归属。
- 构建报告确认对应处理任务执行。
- 判断是否存在并存与迁移遗留。
代码或图示
// 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 生成代码如何反查与调试?
一句话结论
从生成类反推被处理的源类与处理器:查看生成目录中的类名/包名约定,定位对应注解标注源码;调试时先在处理器单测复现,再在构建期附加断点观察符号。
概念解释
生成类是产物,调试应沿"生成类 → 源类 → 处理器模板"回查。字段缺失、类型错误通常先对照源类签名与模板逻辑。反编译可查看插件变换后的最终字节码。
原理流程
- 打开生成目录中的问题类。
- 按命名约定找到源类。
- 核对处理器读取的符号与模板输出。
- 必要时附加调试器观察 Resolver 数据。
代码或图示
生成 UserMapperImpl.kt → 源 User.kt → 处理器模板/符号读取
常见误区
- 直接改生成类修复问题:根因在处理器模板或源类定义,改动会被覆盖。
- 只看生成代码不看源类注解参数:映射错误常来自注解配置。
追问
- 生成代码在 IDE 中不显示?答:同步构建生成源集;检查处理器任务是否成功输出。
- 如何保存生成产物供排查?答:构建后保留生成目录快照,CI 中可作为调试附件留存。
04.8.3.2-090 主流库生成链路可以如何总览对比?
一句话结论
按"生成方式(KSP/kapt/编译器插件/运行期反射)、产物形态、是否需要编译期配置"三个维度对比各库,后端选型时优先生成链路清晰、Kotlin 兼容良好的方案。
概念解释
序列化:编译器插件生成序列化器;DAO/映射:KSP 生成实现;DI:生成工厂或运行期容器;纯 DSL 库无生成。对比时同时评估处理器维护状态与 Kotlin 2.x 兼容情况。
原理流程
- 列出候选库及其生成机制。
- 标注处理器类型、产物与配置入口。
- 核对 Kotlin 版本兼容与迁移状态。
- 结合团队维护成本选型。
代码或图示
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 版本线,不混用。
原理流程
- 确认编译器前端版本。
- 选择对应 KSP 版本线(KSP1/KSP2)。
- 处理器在对应 API 上运行。
- 按发布说明验证处理器行为。
代码或图示
旧前端 ── 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 或暂缓编译器升级。
原理流程
- 查官方 kapt 对 K2 的支持说明。
- 在 K2 工程运行现有 kapt 处理器。
- 记录告警、报错与生成产物差异。
- 不可用场景制定迁移或暂缓方案。
代码或图示
待确认:K2 下 kapt 支持的语言特性边界、增量行为与错误提示
常见误区
- 未实测就假设 kapt 全量可用:签名映射可能出现新差异。
- 把 kapt 告警当无关信息:告警可能预示产物行为偏差。
追问
- 官方说明在哪里查?答:Kotlin 官网 K2 迁移与 kapt 文档章节。
- 过渡期如何保障构建?答:锁定已知兼容的编译器版本,跟踪处理器生态更新。
04.8.3.2-093 升级 Kotlin 后插件/处理器报错的常见原因是什么?
一句话结论
常见原因是处理器或编译器插件未升级到配套版本、新编译器收紧了类型检查、API 弃用/移除、生成模板与新语言特性不兼容;按报错阶段(加载/处理/编译)归类修复。
概念解释
编译器升级改变内部 API 与类型规则:旧处理器链接失败,旧模板生成不符合新规则的代码。先对齐工具链版本组合,再处理源码 API 迁移,最后修复处理器兼容问题。
原理流程
- 升级后先观察报错阶段。
- 加载期错误:插件/处理器版本不配套。
- 处理期错误:符号 API 变化。
- 编译期错误:生成代码或源码不兼容新规则。
代码或图示
版本对齐 → 处理器升级 → 源码 API 迁移 → 生成链路回归
常见误区
- 跳过版本对齐直接改源码报错:根因可能是旧处理器不兼容新编译器。
- 一次跨多个大版本升级:问题叠加,难以定位。
追问
- 弃用 API 警告如何处理?答:按迁移说明替换,结合 allWarningsAsErrors 门禁逐步清理。
- 回滚方案?答:恢复升级前版本组合,定位受阻的处理器后再重试。
04.8.3.2-094 KSP 处理器报错如何定位到具体源码?
一句话结论
处理器诊断携带被标注符号的位置信息,构建输出可按类名/文件定位;日志中先找报错处理器与符号,再回查对应源类注解与属性。
概念解释
KSP 报错分处理器主动报告与生成代码编译报错两类。前者从诊断中的符号位置定位源类;后者从生成类反查源类与模板。堆栈指向处理器内部代码时,结合单测复现。
原理流程
- 读取构建输出中的处理器名与诊断消息。
- 按符号位置定位源文件与标注类。
- 检查注解参数、类型可见性与签名约束。
- 生成代码错误则反查模板输出。
代码或图示
诊断:@Gen 只能标注 data class → 定位源类 → 修正声明
常见误区
- 只看编译器最后一条错误:处理器原始诊断可能在更早日志中。
- 报错类名是生成类却去改源码:先反查源类与处理器。
追问
- 处理器未输出位置信息怎么办?答:在处理器中补充位置日志;框架默认诊断能力以版本为准。
- 多处理器串行报错先修哪个?答:先修上游生成类处理器,其产物影响下游处理。
04.8.3.2-095 生成代码包名或乱码错误如何排查?
一句话结论
包名错误通常来自包名读取/模板拼接失误,乱码多为编码或模板字符串问题;先核对源类包名与生成目录,再检查生成模板的字符串编码与转义。
概念解释
KSP 读取 packageName 拼生成包名,拼接规则错误会导致类落到错误包。编码问题在 Windows 环境需注意源文件 UTF-8 无 BOM;模板拼接特殊字符未转义会产出非法源码。
原理流程
- 打开生成文件核对包名声明。
- 对照源类包名与处理器拼接规则。
- 检查模板字符串编码与转义。
- 修复处理器模板后重新生成。
代码或图示
源类包名 com.example → 生成类应为 com.example.gen
包名错位:检查 packageName 拼接与目录约定
常见误区
- 把生成文件包名手动改对:处理器模板未修,下次生成依旧错误。
- 忽略文件编码:非 UTF-8 中文标识符/注释可能产生乱码。
追问
- 生成源码编译报非法字符怎么办?答:检查模板字符串转义与源文件编码。
- 中文类名/包名有什么建议?答:生成代码与包名使用 ASCII 标识符,中文仅用于显示文本。
04.8.3.2-096 处理器的扫描范围是哪个 sourceSet?
一句话结论
KSP/kapt 默认处理主源集(main)中的标注类;测试源集是否被处理由配置决定,处理器一般不扫描构建目录中的生成物。
概念解释
处理器输入是参与编译的源码集合。测试源码集有独立编译任务,对应处理配置需单独声明。生成物不被重复扫描,避免循环处理。
原理流程
- 编译任务确定输入 sourceSet。
- 对应处理器配置绑定该源集。
- 处理器扫描源集中的标注声明。
- 生成代码并入对应编译任务。
代码或图示
main 源集 → KSP/kapt 处理 → 主编译
test 源集 → 按配置决定是否处理 → 测试编译
常见误区
- 测试工具类标注了生成注解却不生成:测试源集未配置处理器。
- 处理器扫描到生成目录:输入范围应排除生成物目录。
追问
- 测试专用生成类怎么配?答:在测试对应处理器配置中声明,具体 configuration 命名以插件文档为准。
- 多 build type/flavor 源集呢?答:按变体源集分别配置处理任务。
04.8.3.2-097 测试源码集会被处理器处理吗?
一句话结论
取决于是否为测试源集配置了对应处理器依赖;默认主源集处理器不自动处理测试源码,测试中使用的生成类需单独配置链路。
概念解释
测试编译有独立 classpath 与任务。若测试代码需要生成的实现/适配器,测试 configuration 也要接入处理器。否则测试引用不到生成类,编译报错。
原理流程
- 检查测试源码中的标注类。
- 在测试处理器配置中加入对应处理器。
- 测试编译前运行处理任务。
- 生成类进入测试源集编译。
代码或图示
dependencies {
// 测试源集处理器配置(命名以插件文档为准)
}
常见误区
- 主源集配了处理器就以为测试自动覆盖:两套源集独立。
- 测试工具类放在 main 只为走处理器:污染主产物,应理清归属。
追问
- 测试替身需要生成类吗?答:多数测试用手写 fake 即可,生成链路服务生产模型。
- 处理器能区分 main/test 输入吗?答:按任务绑定的源集读取,处理器可感知来源集信息(API 以版本为准)。
04.8.3.2-098 缓存命中导致旧生成代码残留如何处理?
一句话结论
任务缓存或增量记录过期时,可能复用旧生成产物;表现为改了注解/源码但生成类不变。处理方式是清理生成目录与对应任务状态后重建,再检查处理器依赖声明是否完整。
概念解释
生成任务的输入若未完整声明,缓存判定认为输入未变而复用旧产物。处理器版本升级、源码签名变更都应使产物失效。残留类与新手写类冲突时编译报重复声明。
原理流程
- 现象:生成代码未随源码更新。
- 检查任务状态是否 UP_TO_DATE/FROM_CACHE。
- 清理生成目录与任务历史后重建。
- 复核处理器输入依赖声明。
代码或图示
源码变更 → 生成任务未重跑(缓存误判)→ 旧类残留
处理:clean 生成目录 → 重新处理 → 修正依赖声明
常见误区
- 反复改源码不生效就怀疑编译器:先排除生成任务缓存残留。
- 不修复输入声明只清缓存:下次变更仍可能误命中。
追问
- 如何确认缓存键包含源码变更?答:核对处理器声明的符号依赖是否覆盖变更点。
- CI 上残留如何避免?答:干净工作区重建 + 远程缓存条目按输入哈希更新。
04.8.3.2-099 KSP 与 IDE 同步是什么关系?
一句话结论
IDE 同步构建脚本后会触发生成源集加入索引,生成类可被导航与补全;处理器任务未成功执行时 IDE 看不到生成类,需重新同步或先跑一次构建。
概念解释
IDE 依赖 Gradle 模型把生成目录注册为源码目录。KSP 任务输出在构建后产生,同步流程触发任务执行或读取既有产物。IDE 与命令行构建使用同一套生成目录约定。
原理流程
- IDE 同步读取 Gradle 模型与配置。
- 触发/识别 KSP 生成目录。
- 生成源码加入 IDE 索引。
- 业务代码可导航到生成类。
代码或图示
IDE 同步 → 生成源集注册 → 索引生成类 → 补全/导航可用
常见误区
- 命令行能编译、IDE 报生成类缺失:IDE 未重新同步生成源集。
- 在 IDE 中编辑生成类:产物会被下次构建覆盖。
追问
- 同步后仍找不到生成类?答:先命令行跑通 KSP 任务,再刷新 IDE 模型。
- IDE 索引过大怎么办?答:生成目录按约定管理,不手工纳入额外源码。
04.8.3.2-100 如何在 KSP、kapt 与编译器插件之间做选型决策?
一句话结论
优先 KSP 做 Kotlin 感知的新代码生成;仅当依赖库只提供 Java 处理器时保留 kapt;需要改写既有类形态或方法体时才用编译器插件;无生成必要时选运行期库。
概念解释
决策顺序:先判断是否需要编译期生成。需要新类 → KSP;生态仅有 Java 处理器 → kapt 过渡;改写原类 → 编译器插件;运行期可解决 → 不引入生成链路。选型同时评估 Kotlin 2.x 兼容与长期维护状态。
原理流程
- 明确需求:新增类 / 改写原类 / 运行期组装。
- 核对第三方库支持的处理链路。
- 评估 Kotlin 版本兼容与迁移成本。
- 落地配置并回归生成产物。
代码或图示
新生成类: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)