【鸿蒙优选三方库】@ohos/aki:一行代码让 ArkTS 调 C++

【鸿蒙优选三方库】@ohos/aki:一行代码让 ArkTS 调 C++

裸写 NAPI 绑定一个 add(a, b),要写三十行 napi_get_value_int32、napi_create_int32。绑定一个 C++ 类?更是一场噩梦。@ohos/aki 把它压缩成一行------同样的功能,代码量减少一半以上。
📦 仓库地址 | ohpm install @ohos/aki | v1.3.0 | Apache-2.0


它解决什么问题

鸿蒙应用一旦要复用 C/C++ 库、做高性能计算、调底层能力,就绕不开 Node-API。但 NAPI 的样板代码量惊人:

  • 取参数、转类型、创建返回值,全是手写
  • 异步要自己管 AsyncWorker / ThreadSafeFunction
  • C++ 类、继承、枚举、Promise 都要手写桥接
  • JS 异常、C++ 异常、生命周期管理让人掉头发

AKI(Alpha Kernel Interacting)在 NAPI 之上做了一层语法糖:

cpp 复制代码
// AKI:一行绑定
JSBIND_FUNCTION(add) { return args[0].As<int>() + args[1].As<int>(); }
JSBIND_ADDON(add)
typescript 复制代码
// ArkTS:直接调
import { add } from 'libentry.so'
console.info('3 + 5 = ' + add(3, 5))

核心能力

能力 说明
函数绑定 JSBIND_FUNCTION 一行
类绑定 JSBIND_CLASS + JSBIND_METHOD + JSBIND_FIELD
自动类型转换 基本类型、字符串、ArrayBuffer、对象、回调
Promise 桥接 aki::Promise,支持 Then/Catch
AsyncWorker 耗时任务不阻塞 UI
TaskRunner 跨线程调度
线程安全函数 多线程回调 ArkTS
aki::Value 通用 JS 值包装
Persistent 跨线程持有 JS 引用防 GC
混合开发 与现有 NAPI 代码共存

30 秒上手

源码依赖(推荐):

bash 复制代码
cd entry/src/main/cpp
git clone https://gitcode.com/CPF-ApplicationTPC/aki.git
cmake 复制代码
add_subdirectory(aki)
target_link_libraries(hello PUBLIC aki_jsbind)

绑定一个 C++ 类:

cpp 复制代码
#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_ADDON(Calculator)
typescript 复制代码
import { Calculator } from 'libentry.so'

const calc = new Calculator()
calc.Add(3, 5)
console.info(calc.GetResult())   // 8

异步(不阻塞 UI):

cpp 复制代码
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;
}
typescript 复制代码
const userId = await fetchUser()   // 直接 await

社区已解决的典型问题

aki::Value 跨线程使用出问题 (#310) 升级到新版后,aki::Value 跨线程使用触发多线程检测报错,而 1.2.25 版本没有。原因是旧版用全局线程本地 env,跨线程访问绕过了系统检查;新版改为存储创建线程的 env。维护者明确回复:napi_value 在哪个线程产生就只能在该线程使用,旧版能跑通其实是 AKI 的漏洞,实际运行存在稳定性隐患。

正确做法是跨线程只传纯 C++ 数据:

cpp 复制代码
// ❌ 把 aki::Value 带到子线程
std::thread([jsValue]() { auto d = jsValue.As<int>(); }).detach();

// ✅ JS 线程取出纯数据,只把数据带到子线程
int data = args[0].As<int>();
std::thread([data, promise]() mutable {
    promise.Resolve(heavyCompute(data));
}).detach();

release 包崩溃无法定位 (#316) 线上包是 release 编译的,崩溃后没有符号表可回溯堆栈。仓库已提出符号表备份需求。发版时自己也要归档未 strip 的 .so,否则线上崩溃只能干瞪眼。

空指针崩溃 (#307) master 已对空指针场景做兼容处理,避免传入空值直接崩溃。但框架兼容是兜底不是免责,C++ 侧仍应主动做空值校验。

aki::Promise 支持 Then/Catch (#306) 此前 C++ 侧调用 JS 异步函数后无法处理其返回的 Promise。现已支持,实现真正的双向异步互调。


适合谁用

  • 复用现有 C/C++ 库:OpenCV、SQLite、Eigen、加密算法
  • 高性能计算:图像处理、音视频编解码、科学计算
  • Native 插件开发:很多鸿蒙三方库底层就用 AKI
  • NAPI 代码改造:渐进式迁移,与现有代码共存
  • 跨语言团队协作:C++ 工程师专注算法,ArkTS 工程师专注 UI

303 个 Issue 已关闭。AKI 的价值不只是少写代码------它把 NAPI 里那些容易出错的类型转换、线程安全、生命周期管理都封装好了,踩坑概率显著下降。

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

相关推荐
程序猿追10 小时前
鸿蒙 PC 的 Ionic 工单有两个错误,按下生成后光标该去哪儿
华为·harmonyos
KevinChaos14 小时前
随手备忘录手记 04|HarmonyOS 7.0新特性实验:物品图鉴的加载逻辑
华为·harmonyos
Sirius_Ji21 小时前
从硬解基座到字幕与滤镜链:ffmpeg-for-HarmonyOS v0.3.2
harmonyos
用户86194177207411 天前
uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"
微信·harmonyos
码间留白1 天前
uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"
uni-app·harmonyos·鸿蒙·uts插件·微信商家转账
GitCode官方1 天前
开源鸿蒙跨平台直播|AI 时代,用 cj-tauri 开发鸿蒙 PC 应用
人工智能·华为·harmonyos·atomgit
程序猿追2 天前
鸿蒙 PC 用 Tauri 做本地查找,怎样让慢请求给新请求让路
华为·状态模式·harmonyos
程序猿追2 天前
鸿蒙 PC 用 Ionic 做巡检目录,缩窄窗口后草稿还在吗
华为·harmonyos
jianqiang.xue2 天前
1颗NPU分时复用:鸿蒙把轻AI塞进了MCU
人工智能·单片机·mcu·嵌入式·harmonyos·鸿蒙·端侧ai
程序猿追2 天前
鸿蒙 PC 用 Tauri 迁移配置文件,先保留旧版再写新版
华为·harmonyos