还在为 NAPI 的样板代码头疼？AKI（Alpha Kernel Interacting）是一款专为 OpenHarmony 打造的 ArkTS FFI 框架，用极简语法糖让 JS/ETS 与 C/C++ 跨语言互调变得"所键即所得"——一行代码完成绑定，一行代码完成回调。

• 包名：@ohos/aki
• 当前版本：v1.3.0
• 协议：Apache-2.0
• 安装：ohpm install @ohos/aki（或源码依赖）
• 仓库：https://gitcode.com/CPF-ApplicationTPC/aki

---

一、它解决了什么问题？

OpenHarmony 应用一旦要复用现有 C/C++ 库、做高性能计算、调用系统底层能力，绕不开的就是 Node-API（NAPI）。但原生的 NAPI 写起来极其繁琐：

• 一堆 napi_get_cb_info、napi_create_xxx、napi_unwrap 的样板代码；
• 异步回调需要手动管理 AsyncWorker / ThreadSafeFunction；
• C++ 类、继承、枚举、Promise 都要手写桥接；
• JS 异常、C++ 异常、生命周期管理让人掉头发。

AKI 在 NAPI 之上做了一层"语法糖"，把以上工作压缩到几行代码：

// AKI 写法 —— 一行绑定全局函数
JSBIND_FUNCTION(add) { return args[0].As<int>() + args[1].As<int>(); }
JSBIND_ADDON(add)  // 注册到 ArkTS

ArkTS 侧直接 import { add } from 'libentry.so' 即可调用。

---

二、核心特点

特性	说明
极简语法糖	大幅减少 NAPI 样板代码
ETS ↔ C/C++ 互调	支持函数、类、成员函数、成员属性、继承、枚举
自动类型转换	基本类型、字符串、ArrayBuffer、对象、回调全支持
Promise 桥接	C++ 侧 aki::Promise 一键返回 Promise 给 ArkTS
异步 Worker	AsyncWorker 解决耗时任务不阻塞 UI
TaskRunner	跨线程调度（主线程/子线程）
线程安全函数	解决多线程回调到 ArkTS 的竞态
aki::Value	通用 JS 值包装，灵活处理动态数据
Persistent 引用	跨线程持有 JS 对象，防止被 GC
混合开发	支持与现有 NAPI 代码混用
完整 Benchmark	仓库自带 NAPI vs AKI 性能基准对比

---

三、适用场景

• 复用现有 C/C++ 库：把 OpenCV、SQLite、加密算法等搬进鸿蒙应用。
• 高性能计算：图像处理、音视频编解码、加解密在 Native 跑。
• Native 插件开发：为鸿蒙三方库写 ArkTS 接口（很多库基于 AKI）。
• 已有 NAPI 代码改造：从冗长 NAPI 迁移到 AKI，代码量减半。
• 跨语言团队协作：C++ 工程师专注 Native 实现，ArkTS 工程师专注 UI 与业务。
• 系统底层能力调用：访问不便用 ArkTS 表达的系统 API。

---

四、快速上手

1. 依赖配置（二选一）

方式 A：源码依赖（推荐）

cd entry/src/main/cpp
git clone https://gitcode.com/CPF-ApplicationTPC/aki.git

CMakeLists.txt：

add_subdirectory(aki)
target_link_libraries(hello PUBLIC aki_jsbind)

方式 B：ohpm har 包依赖

cd entry
ohpm install @ohos/aki

CMakeLists.txt：

set(AKI_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules/.ohpm/@ohos+aki)
# ... 引入 AKI 路径
target_link_libraries(hello PUBLIC aki_jsbind)

2. 极简示例：ArkTS 调用 C++ 函数

C++ 侧（hello.cpp）：

#include <aki/jsbind.h>

// 一行绑定全局函数
JSBIND_FUNCTION(add) {
    int a = args[0].As<int>();
    int b = args[1].As<int>();
    return a + b;
}

// 注册到 ArkTS
JSBIND_ADDON(add)

ArkTS 侧：

import { add } from 'libentry.so'

console.info('3 + 5 = ' + add(3, 5)) // 输出: 3 + 5 = 8

3. 绑定 C++ 类

C++ 侧：

#include <aki/jsbind.h>

class Calculator {
public:
    Calculator() : result_(0) {}

    int Add(int a, int b) {
        result_ = a + b;
        return result_;
    }

    int GetResult() const { return result_; }

private:
    int result_;
};

JSBIND_CLASS(Calculator) {
    JSBIND_CONSTRUCTOR();  // 无参构造
    JSBIND_METHOD(Add);
    JSBIND_METHOD(GetResult);
    JSBIND_FIELD(result_); // 可选：暴露成员属性
}

JSBIND_ADDON(Calculator)

ArkTS 侧：

import { Calculator } from 'libentry.so'

const calc = new Calculator()
calc.Add(3, 5)
console.info('结果: ' + calc.GetResult()) // 8

4. Promise 与异步 Worker

// C++ 侧：返回 Promise
JSBIND_FUNCTION(fetchUser) {
    aki::Promise promise;
    
    // 模拟异步耗时操作
    std::thread([promise]() mutable {
        std::this_thread::sleep_for(std::chrono::seconds(1));
        promise.Resolve("user_001");
    }).detach();
    
    return promise; // 返回给 ArkTS，await 即可
}

// ArkTS 侧
import { fetchUser } from 'libentry.so'

const userId = await fetchUser()
console.info('用户: ' + userId)

---

五、亮点能力速览

• aki::Value：通用 JS 值包装，处理复杂动态数据结构。
• aki::Binding：统一管理所有绑定入口。
• aki::ScopedLogMessage：原生日志宏，自动桥接到 ArkTS 日志。
• aki::NapiOverloader：C++ 函数重载到 ArkTS。
• aki::Persistent：跨线程安全持有 JS 引用，告别悬空引用。
• 线程安全：内置 ThreadSafeFunction 封装，任意线程回调 ArkTS 都不崩。

---

六、为什么值得选它？

1. 代码量减半：相比裸写 NAPI，同样的功能代码量减少 50%+。
2. 类型安全：编译期检查跨语言类型不匹配，运行期再也不会 napi_get_value_string 返回乱码。
3. 异步模型完整：Promise / AsyncWorker / TaskRunner 三件套覆盖所有并发场景。
4. 混合开发友好：已有的 NAPI 代码可以与 AKI 共存，渐进式迁移。
5. 生态验证：仓库内多个 demo（绑定类、继承、枚举、回调、Promise 等）覆盖全部用法。

如果你正在为鸿蒙应用接入 C/C++ 库，AKI 就是那把让你"写一次就上头"的瑞士军刀。