#HarmonyOS NEXT体验官# 鸿蒙NDK开发入门 原创 精华

一、NDK简介

  NDK（Native Development Kit）是鸿蒙提供的Native API、编译脚本和编译工具链的集合，方便开发者使用C/C++实现应用的关键功能。一般情况下应用开发使用ArkTS，ArkTS已经能满足大部分的功能开发，但有些功能还是需要用C/C++来实现，像音视频、直播、美颜、地图、AI等功能就需要使用C/C++来实现。学习NDK的前提是熟悉C/C++，重点掌握指针。

二、Node-API

  Node-API为开发者提供了ArkTS/JS与C/C++模块之间的交互能力。说白了，ArkTS/JS和C/C++要想相互调用，就需要使用Node-API。

2、1 Node-API的数据类型

napi_status

  napi_status是一个枚举数据类型，表示Node-API接口返回的状态信息。每当调用一个Node-API函数，都会返回该值，表示操作成功与否的相关信息。

typedef enum {
    napi_ok,
    napi_invalid_arg,
    napi_object_expected,
    napi_string_expected,
    napi_name_expected,
    napi_function_expected,
    napi_number_expected,
    napi_boolean_expected,
    napi_array_expected,
    napi_generic_failure,
    napi_pending_exception,
    napi_cancelled,
    napi_escape_called_twice,
    napi_handle_scope_mismatch,
    napi_callback_scope_mismatch,
    napi_queue_full,
    napi_closing,
    napi_bigint_expected,
    napi_date_expected,
    napi_arraybuffer_expected,
    napi_detachable_arraybuffer_expected,
    napi_would_deadlock, /* unused */
    napi_no_external_buffers_allowed,
    napi_cannot_run_js
} napi_status;

napi_value

  napi_value是C的一个结构体指针，表示一个JavaScript对象的引用。ArkTS向C/C++传递的参数，C/C++不能直接使用，需要使用napi_value解析。C/C++向ArkTS传参，直接传递napi_value即可。

napi_env

• 用于表示Node-API执行时的上下文，Native侧函数入参，并传递给函数中的Node-API接口。
• napi_env与JS线程绑定，JS线程退出后，napi_env将失效。
• 禁止缓存napi_env，禁止在不同线程中传递napi_env。

三、创建NDK项目

  使用DevEco-Studio可以创建NDK项目，如下图所示，创建项目的时候选择Native C++。

  与ArkTS项目相比，NDK项目多了一个cpp目录。

3、1 CMakeLists.txt

  cpp目录里面有个CMakeLists.txt，这是cmake的构建文件，C/C++就是使用cmake构建的。CMakeLists.txt脚本中添加了编译所需的源代码、头文件以及三方库，开发者可根据实际工程添加自定义编译参数、函数声明、简单的逻辑控制等。

# the minimum version of CMake.
cmake_minimum_required(VERSION 3.4.1)
project(MyApplication) 

# 定义一个变量，并赋值为当前模块cpp目录
# ${CMAKE_CURRENT_SOURCE_DIR}指的就是CMakeLists.txt所在路径
set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})

# 添加头文件.h目录，包括cpp，cpp/include，告诉cmake去这里找到代码引入的头文件
include_directories(${NATIVERENDER_ROOT_PATH}
                    ${NATIVERENDER_ROOT_PATH}/include)

# 声明一个产物libentry.so，SHARED表示产物为动态库，napi_init.cpp为产物的源代码
add_library(entry SHARED napi_init.cpp)

# 声明产物entry链接时需要的三方库libace_napi.z.so
# 这里直接写三方库的名称是因为它是在ndk中，已在链接寻址路径中，无需额外声明
target_link_libraries(entry PUBLIC libace_napi.z.so)

3、2 externalNativeOptions

  模块级build-profile.json5中externalNativeOptions参数是NDK工程C/C++文件编译配置的入口，可以通过path指定CMake脚本路径、arguments配置CMake参数、cppFlags配置C++编译器参数、abiFilters配置编译架构等。

3、3 毕昇编译器

  毕昇编译器是基于LLVM开源软件开发的一款用于C/C++等语言的native编译器，能将C/C++代码工程编译链接成可以在设备上运行的二进制。在无需改动用户代码的条件下，相比业界主流的开源LLVM或GCC编译器，毕昇编译器能提供更强大的优化能力，使编译链接出来的二进制的运行时长更短、指令数更少，帮助提升应用在设备上的运行流畅度。
  开发者可以获取DevEco Studio 5.0.3.402及以上的版本，在HarmonyOS应用的工程级build-profile.json5中简单配置即可使用毕昇编译器。在runtimeOS为HarmonyOS的时候，设置nativeCompiler为BiSheng，即可使用毕昇编译器构建HarmonyOS工程的C/C++代码。

四、Node-API实现跨语言交互开发流程

4、1 导入so

  创建完ndk项目后，打开index.ets文件，在index.ets文件的顶部会有如下代码，这就是导入so。

import testNapi from 'libentry.so';

4、2 注册模块

  当导入so，会加载其对应的so。加载so时，首先会调用napi_module_register方法，将模块注册到系统中，并调用模块初始化函数。如下代码，napi_module_register函数是在RegisterDemoModule函数中调用，RegisterDemoModule函数被__attribute__((constructor))修饰。__attribute__((constructor))是‌GCC和兼容的编译器中的一个特性，用于指示编译器将一个函数标记为在程序启动时自动执行的初始化函数，被__attribute__((constructor))修饰的函数会在main函数执行之前执行。
  napi_module_register函数的参数是个napi_module结构体指针，napi_module有两个关键属性：一个是.nm_register_func，定义模块初始化函数；另一个是.nm_modname，定义模块的名称，也就是ArkTS侧引入的so库的名称，模块系统会根据此名称来区分不同的so。

// 准备模块加载相关信息，将上述Init函数与本模块名等信息记录下来。
static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = nullptr,
    .reserved = {0},
};

// 加载so时，该函数会自动被调用，将上述demoModule模块注册到系统中。
extern "C" __attribute__((constructor)) void RegisterDemoModule() { 
    napi_module_register(&demoModule);
 }

4、3模块初始化

  如下代码，Init函数是在napi_module结构体的.nm_register_func属性指定的。napi_property_descriptor结构体用于实现ArkTS接口与C++接口的绑定和映射。当创建完ndk项目，index.d.ts文件会有export const add: (a: number, b: number) => number;这样一段代码，这段代码声明了一个add函数，表明ArkTS会通过add函数调用到C/C++。C/C++不能直接使用add函数，就需要使用napi_property_descriptor结构体将ArkTS的add函数与C/C++函数进行绑定，这里绑定到C/C++的Add函数。

EXTERN_C_START
// 模块初始化
static napi_value Init(napi_env env, napi_value exports)
{
    // ArkTS接口与C++接口的绑定和映射，
    napi_property_descriptor desc[] = {
        // ArkTS的add函数绑定C/C++的Add函数
        { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr }
    };
    // 在exports对象上挂载CallNative/NativeCallArkTS两个Native方法
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END
// 模块基本信息
static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

  大部分情况下，不仅仅需要绑定一个函数。当需要绑定多个函数，首先需要index.d.ts文件声明函数，如下代码，index.d.ts文件声明两个函数。

export const add: (a: number, b: number) => number;
export const sub: (a: number, b: number) => number;

  Init函数就需要加上{ "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr }和{ "sub", nullptr, Sub, nullptr, nullptr, nullptr, napi_default, nullptr }

static napi_value Init(napi_env env, napi_value exports)
{
    // ArkTS接口与C++接口的绑定和映射，
    napi_property_descriptor desc[] = {
        // ArkTS的add函数绑定C/C++的Add函数
        { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr }
        // ArkTS的sub函数绑定C/C++的Sub函数
        { "sub", nullptr, Sub, nullptr, nullptr, nullptr, napi_default, nullptr }
    };
    // 在exports对象上挂载CallNative/NativeCallArkTS两个Native方法
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}

4、4 解析参数

  当ArkTS的add函数绑定到C/C++的Add函数，我们需要定义Add函数。接下来就是通用的解析流程了。

• 声明参数的个数，由于ArkTS传入多少个参数，参数的个数就多少。
• 调用napi_get_cb_info函数将ArkTS传入的参数并依次放入参数数组中。
• 依次获取ArkTS传入的参数。
• 需要给ArkTS回传参数，定义napi_value，获取到ArkTS传入的两个参数，执行相应的业务逻辑，将结果赋值给napi_value。
• 返回napi_value给ArkTS。

static napi_value Add(napi_env env, napi_callback_info info)
{
    // 声明参数的个数，由于ArkTS会传递过来两个参数，参数的个数就为2
    size_t argc = 2;
    // 声明参数数组
    napi_value args[2] = {nullptr};
    // 将ArkTS传入的参数并依次放入参数数组中
    napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);
    // 依次获取参数
    // 获取ArkTS传入的第一个参数
    double value0;
    napi_get_value_double(env, args[0], &value0);
    // 获取ArkTS传入的第二个参数
    double value1;
    napi_get_value_double(env, args[1], &value1);
    // 需要给ArkTS回传参数，定义napi_value
    napi_value sum;
    // 获取到ArkTS传入的两个参数后，将两个参数相加，相加结果赋值给napi_value
    napi_create_double(env, value0 + value1, &sum);
    // 返回napi_value给ArkTS
    return sum;
}

五、Node-API的约束限制

5、1 so命名规则

  导入使用的模块名和注册时的模块名大小写保持一致，如模块名为entry，则so的名字为libentry.so，napi_module中nm_modname字段应为entry，ArkTS侧使用时写作：import xxx from ‘libentry.so’。

5、2注册建议

• nm_register_func对应的函数（如上述Init函数）需要加上static，防止与其他so里的符号冲突；
• 模块注册的入口，即使用__attribute__((constructor))修饰的函数的函数名（如上述RegisterDemoModule函数）需要确保不与其它模块重复。

5、3多线程限制

  每个引擎实例对应一个JS线程，实例上的对象不能跨线程操作，否则会引起应用崩溃。使用时需要遵循如下原则：

• Node-API接口只能在JS线程使用。
• Native接口入参env与特定JS线程绑定只能在创建时的线程使用。

六、总结

• 当ArkTS侧在导入Native模块时，ArkTS引擎会加载模块对应的so及其依赖。首次加载时会触发模块的注册，将模块定义的方法属性挂载到exports对象上并返回该对象。
• 当ArkTS侧通过导入返回的对象调用方法时，ArkTS引擎会调用对应的C/C++方法。在C/C++函数中解析js传递过来的参数，执行对应的业务代码，最后将结果返回给js。