KNOI 架构详细分析报告

KNOI 架构详细分析报告

1. 整体架构

1.1 架构图

graph TD
    subgraph 开发工具链
        A[KNOI Gradle Plugin] -->|配置生成| B[KSP 处理器]
        B -->|代码生成| C[TypeScript 接口]
        B -->|注解处理| D[Kotlin 实现类]
    end

    subgraph 运行时核心
        E[Kotlin 核心库] <-->|NAPI 桥接| F[C++ 适配层]
        F <-->|ArkTS NAPI| G[ArkTS 运行时]
        E --> H[服务注册中心]
        E --> I[类型转换引擎]
    end

    subgraph 应用层
        J[Kotlin 业务模块] -->|依赖| E
        K[ArkTS UI 模块] -->|调用| G
        J -->|同一侧调用| J
        K -->|同一侧调用| K
    end

    A -->|依赖注入| E
    J -->|服务注册| H
    K -->|服务发现| H

2. 跨语言交互模型

2.1 调用模式全梳理

2.1.1 双向跨语言调用

ArkTS → Kotlin

@ServiceProvider
open class TestServiceB {
    fun methodWithCallbackReturnCallback(a: (Array<JSValue>) -> Unit): ((Array<JSValue>) -> String) {
        a.invoke(arrayOf(ktValueToJSValue(getEnv(), "result", String::class)))
        return { "callback result" }
    }
}

Kotlin → ArkTS

bind("testCallback", (callback: (String) => Unit) => {
  callback("arkts_callback_response")
  return (data: String) => data + "_processed"
})

2.1.2 同一侧调用

Kotlin 调用 Kotlin 服务

// 同进程内服务调用
val result = KNOI.get<TestServiceBApi>().methodWithIntReturnInt(1)

ArkTS 调用 ArkTS 函数

// 直接函数调用（无需 KNOI 桥接）
function localCallDemo() {
  const handler = () => console.log("arkts_local_callback")
  handler()
}

2.2 回调机制详解

2.2.1 跨语言回调传递

1. ArkTS 传递回调给 Kotlin

// ArkTS 侧注册带回调参数的函数
bind("withCallback", (callback: (String) => Unit) => {
  callback("from_arkts")
})

// Kotlin 侧调用并接收回调
invoke<Unit>("withCallback") { result: String ->
  info("Kotlin received: \$result")
}

2. Kotlin 返回回调给 ArkTS

// Kotlin 侧定义返回函数类型的方法
fun getCallback(): (String) -> String {
  return { it + "_from_kotlin" }
}

// ArkTS 侧调用并执行回调
const callback = service.getCallback()
const result = callback("input") // 结果: input_from_kotlin

2.2.2 回调生命周期管理

// 最佳实践：单回调绑定 + Kotlin 侧分发
let singleCallback: (data: String) => void

bind("registerListener", (cb: (data: String) => void) => {
  singleCallback = cb
})

// ArkTS 内部事件触发时
singleCallback("event_data")

3. 性能优化策略

3.1 回调缓存机制

// Kotlin 侧缓存回调实例
object CallbackCache {
    private var cachedCallback: (String) -> Unit = {}

    fun setCallback(cb: (String) -> Unit) {
        cachedCallback = cb
    }

    fun triggerCallback(data: String) {
        cachedCallback(data)
    }
}

3.2 线程模型优化

调用场景	线程切换策略	性能影响
主线程 → 主线程	无切换	低延迟（推荐）
子线程 → Worker 线程	自动负载均衡	高并发场景首选
主线程 → Worker 线程	禁止（会触发运行时异常）	需避免

4. 典型调用场景示例

4.1 跨语言回调链

sequenceDiagram
    participant AT as ArkTS
    participant K as Kotlin

    AT->>K: 调用 methodWithCallback( (res) => { ... } )
    K->>K: 处理业务逻辑
    K->>AT: 执行回调函数(res="processed")
    AT->>AT: 本地处理回调结果

4.2 同一侧服务组合

graph LR
    A[ServiceA] -->|本地调用| B[ServiceB]
    B -->|本地调用| C[ServiceC]
    C -->|返回结果| B
    B -->|返回结果| A

5. 最佳实践指南

1. 优先本地调用：同一语言内优先直接调用，避免不必要的跨语言桥接
2. 回调精简原则：跨语言回调链不超过2层，复杂逻辑通过服务拆分实现
3. 缓存策略：静态数据和高频回调在Kotlin侧缓存（）
4. 线程匹配：子线程调用优先匹配Worker线程注册的服务实例

---

注：完整类型转换表和异常处理机制见原文档章节3.1和4.2