KuiklyUI core-ksp 模块分析

KuiklyUI core-ksp 模块分析

1. 模块概览

core-ksp 是 KuiklyUI 项目中的一个关键模块，它实现了基于 KSP (Kotlin Symbol Processing) 的注解处理器，用于自动生成页面注册代码。该模块负责扫描带有 @Page 注解的类，并为不同平台生成相应的页面注册和初始化代码。

2. 核心功能

主要功能点：

• 扫描并收集带有 @Page 注解的类信息
• 根据构建选项过滤需要处理的页面
• 为不同平台（Android、iOS、HarmonyOS）生成特定的页面注册代码
• 支持多模块构建模式

处理流程：

1. 初始化 KSP 处理器
2. 扫描带有 @Page 注解的类
3. 根据构建选项和注解属性筛选页面
4. 为目标平台生成代码文件

3. 核心组件

3.1 处理器入口

class KuiklyCoreProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
        return CoreProcessor(environment.codeGenerator, environment.logger, environment.options)
    }
}

这个类是 KSP 处理器的入口点，实现了 SymbolProcessorProvider 接口，负责创建 CoreProcessor 实例。

3.2 处理器实现

class CoreProcessor(
    private val codeGenerator: CodeGenerator,
    private val logger: KSPLogger,
    private val option: Map<String, String>,
) : SymbolProcessor {
    // 实现处理器逻辑
}

CoreProcessor 是实际执行处理逻辑的类，它实现了 SymbolProcessor 接口，主要功能包括：

• 处理带有 @Page 注解的类
• 根据平台选择合适的代码生成器
• 生成页面注册代码

3.3 代码生成器

模块中定义了一系列抽象和具体的代码生成器：

• KuiklyCoreAbsEntryBuilder: 抽象基类，定义了代码生成的基本框架
• AndroidTargetEntryBuilder: 为 Android 平台生成代码
• IOSTargetEntryBuilder: 为 iOS 平台生成代码
• OhOsTargetEntryBuilder: 为 HarmonyOS 平台生成代码
• 多模块版本: AndroidMultiEntryBuilder, IOSMultiTargetEntryBuilder, OhOsTargetMultiEntryBuilder

3.4 扩展函数

Extensions.kt 提供了一系列辅助函数：

// 平台判断扩展函数
fun String.iosFamily(): Boolean { return contains("ios") }
fun String.androidJVMFamily(): Boolean { return contains("android") }
fun String.ohosFamily(): Boolean { return contains("ohos") }

// 将 KSClassDeclaration 转换为 PageInfo
fun KSClassDeclaration.toPageInfo(): PageInfo { /* ... */ }

// 其他辅助函数

4. 技术实现

4.1 页面信息收集

处理器通过以下步骤收集页面信息：

private fun buildEntryFile(
    resolver: Resolver,
    absEntryBuilder: KuiklyCoreAbsEntryBuilder,
): List<FileSpec> {
    // 获取构建选项
    val pageName = option["pageName"] ?: ""
    val packLocalAarBundle = option["packLocalAarBundle"] ?: ""
    val packBundleByModuleId = option["packBundleByModuleId"] ?: ""
    
    // 收集并过滤页面信息
    val pageClassDeclarations = mutableListOf<PageInfo>()
    resolver.getSymbolsWithAnnotation(Page::class.qualifiedName!!)
        .filterIsInstance<KSClassDeclaration>()
        .forEach { classDeclaration ->
            val pageInfo = classDeclaration.toPageInfo()
            // 根据不同条件过滤页面
        }
    
    // 使用对应的 builder 生成代码
    return absEntryBuilder.build(pageClassDeclarations)
}

4.2 平台特定代码生成

处理器会根据目标平台选择合适的代码生成器：

private fun getEntryBuilder(): KuiklyCoreAbsEntryBuilder {
    val enableMultiModule = option["enableMultiModule"]?.toBoolean() ?: false
    val isMainModule = option["isMainModule"]?.toBoolean() ?: false
    val subModules = option["subModules"] ?: ""
    val moduleId = option["moduleId"] ?: ""
    
    // 检测目标平台
    val outputSourceSet = codeGenerator.generatedFile.first().toString().sourceSetBelow("ksp")
    
    // 根据平台和配置选择合适的 builder
    return when {
        outputSourceSet.androidJVMFamily() -> { /* Android 平台 */ }
        outputSourceSet.iosFamily() -> { /* iOS 平台 */ }
        outputSourceSet.ohosFamily() -> { /* HarmonyOS 平台 */ }
        else -> { /* 默认使用 Android */ }
    }
}

4.3 代码生成机制

代码生成基于 KotlinPoet 库，通过构建 FileSpec、TypeSpec、FunSpec 等对象来生成 Kotlin 代码：

fun build(pagesAnnotations: List<PageInfo>): List<FileSpec> {
    val fileSpecs = mutableListOf<FileSpec>()
    val fileSpecBuilder = FileSpec.builder(packageName(), entryFileName())
    
    // 添加注释和导入
    fileSpecBuilder
        .addComment("\nthis file is generating by ksp\n")
        .addComment("please do not modified it!!!")
        .addImport("com.tencent.kuikly.core.manager", "BridgeManager")
        
    // 调用具体的构建方法
    build(fileSpecBuilder, pagesAnnotations)
    fileSpecs.add(fileSpecBuilder.build())
    
    return fileSpecs
}

5. 构建配置

core-ksp 模块使用 Gradle Kotlin DSL 进行配置：

plugins {
    kotlin("multiplatform")
    id("maven-publish")
    signing
}

kotlin {
    jvm()
    
    sourceSets {
        val jvmMain by getting {
            dependencies {
                implementation(Dependencies.kotlinpoet)
                implementation(Dependencies.kspApi)
                implementation(project(":core-annotations"))
            }
            // 配置源代码目录
        }
    }
}

6. 依赖关系

core-ksp 模块依赖以下组件：

• kotlinpoet: 用于生成 Kotlin 代码的库
• kspApi: KSP 处理 API
• core-annotations : 提供 @Page 注解定义

7. 应用场景

core-ksp 模块主要在以下场景中发挥作用：

1. 在编译时自动处理带有 @Page 注解的类
2. 为不同平台生成统一的页面注册代码
3. 支持按模块或按特定条件打包页面
4. 为 KuiklyUI 框架提供页面发现和注册机制

8. 总结

core-ksp 模块是 KuiklyUI 框架中的一个关键组件，它通过 KSP 技术实现了编译时代码生成，为框架提供了页面发现和注册的核心功能。该模块支持多平台和多模块构建，能够根据不同的配置灵活地生成适合目标平台的代码。通过自动生成页面注册代码，它大大简化了开发者的工作，提高了代码的一致性和可维护性。