本文深入解析混合java/kotlin android项目中注解处理器无法识别kotlin类的根本原因，明确指出kapt的编译阶段限制，并提供从kapt平滑迁移到ksp的完整实践方案，确保所有kotlin源码（包括activity、fragment等）均能被正确扫描和处理。
本文深入解析混合java/kotlin android项目中注解处理器无法识别kotlin类的根本原因，明确指出kapt的编译阶段限制，并提供从kapt平滑迁移到ksp的完整实践方案，确保所有kotlin源码（包括activity、fragment等）均能被正确扫描和处理。
在Android混合开发项目中，当使用传统javax.annotation.processing API编写的注解处理器（如您所示的EnableScannerTypesAnnotationProcessor）时，常会遇到一个关键限制：该处理器仅能处理Java源码生成的AST，无法访问Kotlin源码的语义结构。这是因为KAPT（Kotlin Annotation Processing Tool）本质上是一个“桥接层”——它将Kotlin代码编译为Java stubs（存根），再将这些stub传递给Java注解处理器。而stub仅包含签名信息（如类名、方法声明），不保留注解元数据（尤其是未显式标注@Retention(RetentionPolicy.SOURCE)或@Retention(RetentionPolicy.CLASS)的注解），导致RoundEnvironment.getElementsAnnotatedWith()无法检索到Kotlin类上的注解元素。
您的问题中，第二个Kotlin Activity未出现在annotatedTypes集合中，正是这一机制的典型表现：KAPT生成的stub中丢失了@YourInternalAnnotation的声明，因此AbstractProcessor完全“看不见”该类。
✅ 正确解法：迁移到KSP（Kotlin Symbol Processing）
KSP是JetBrains官方推荐的现代替代方案，它直接解析Kotlin编译器的内部符号（KSFile、KSClassDeclaration等），原生支持Kotlin语法、注解、泛型及空安全特性，无需stub转换，可100%覆盖.kt文件中的注解。
Miller (mlr) 是一个命令行工具，用于查询、整形和重新格式化名称索引数据，如 CSV、TSV、JSON 和 JSON Lines。它将 awk、sed、cut、join 和 sort 的功能整合到一个专为结构化数据处理而构建的单一工具中。
迁移步骤（以Gradle Kotlin DSL为例）：
-
添加KSP依赖（替换原有KAPT配置）
在模块级 build.gradle.kts 中：plugins { id("com.google.devtools.ksp") version "1.9.22-1.0.23" apply false // 请同步Kotlin版本 } dependencies { // 移除旧的 kapt "your-processor:xxx" implementation("com.google.devtools.ksp:symbol-processing-api:1.9.22-1.0.23") ksp(project(":your-processor-module")) // 若处理器为独立模块 // 或直接引入已发布的KSP处理器 // ksp("com.example:scanner-processor:1.0.0") } -
重写处理器逻辑（核心示例）
替换原Java AbstractProcessor，新建KSP处理器：class EnableScannerTypesSymbolProcessor( private val codeGenerator: CodeGenerator, private val logger: KSPLogger ) : SymbolProcessor { override fun process(resolver: Resolver): List<KSAnnotated> { val annotatedActivities = resolver.getSymbolsWithAnnotation("your.package.EnableScanner") .filterIsInstance<KSClassDeclaration>() .filter { it.classKind == ClassKind.CLASS && it.isActivity() } annotatedActivities.forEach { activity -> // 直接获取Kotlin类全限定名、构造函数、父类等完整信息 val className = activity.qualifiedName?.asString() ?: return@forEach generateScannerRegistryEntry(className) // 生成注册代码 } return emptyList() } private fun KSClassDeclaration.isActivity(): Boolean { return this.superTypes.any { type -> type.resolve().declaration.qualifiedName?.asString() == "android.app.Activity" } } private fun generateScannerRegistryEntry(className: String) { // 使用KSP提供的CodeGenerator生成Java/Kotlin源码 codeGenerator.createNewFile( dependencies = Dependencies.ALL, packageName = "your.generated.package", fileName = "ScannerRegistry" ).use { writer -> writer.write("// Auto-generated by KSP\n") writer.write("public class ScannerRegistry {\n") writer.write(" public static final Class<?>[] ACTIVITIES = {\n") writer.write(" $className.class,\n") writer.write(" };\n") writer.write("}\n") } } } -
注册处理器（resources/META-INF/services/com.google.devtools.ksp.SymbolProcessorProvider）：
your.package.EnableScannerTypesSymbolProcessorProvider
⚠️ 关键注意事项：
- KAPT已弃用：自Kotlin 1.9起，KAPT进入维护模式，新项目强烈建议直接采用KSP。
- Gradle兼容性：KSP需AGP 8.1+ 和 Kotlin 1.8.0+，请同步升级构建工具链。
- 注解保留策略：确保自定义注解使用@Retention(AnnotationRetention.BINARY)（KSP默认读取class文件）或@Retention(AnnotationRetention.SOURCE)（需启用ksp { includeSource = true }）。
- 增量编译支持：KSP天然支持增量构建，显著提升大型项目编译速度。
总结：KAPT的stub机制是Java-centric设计的历史产物，无法满足现代Kotlin优先项目的元编程需求。KSP不仅解决了Kotlin类不可见问题，还提供了更丰富的API（如类型推导、扩展函数识别、DSL友好的代码生成），是混合项目注解处理的终极解决方案。迁移成本可控，且一次投入，长期受益。
