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