未命名的副本_公众号封面首图_2022-03-10+22_20_20.jpeg

上一篇回顾 零基础开发 Node.js Addons 插件：Hello Node-API。本篇介绍使用 Node-API 为 Node.js 开发基于 C 的 Addons 时，如何接收与处理 Node.js 层传递的参数、Node-API 参数类型如何与 C 的类型互转、使用 CMake.js 构建源码。

实现两个整数相加

以下是使用 C 语言写的两个整数相加的函数，很简单的一个例子。

  1. int add(int a, int b) {
  2.   int sum = a + b;
  3.   return sum;
  4. }

创建项目 n-api-calculator，文件结构如下所示：

  1. ├── app.js
  2. ├── CMakeLists.txt
  3. └── src
  4.     └──calculator.c

编码实现

本次我们主要实现的是 calculator.c 这个文件，首先引入如下两个头文件。

  1. #include <assert.h>
  2. #include <node_api.h>

定义通用的参数校验宏

Node-API 提供的一些 API 都会返回 status 供我们判断本次是否操作成功，类似这样的通用判断逻辑在代码里会出现多次，在这里首先将 status 的判断封装成一个宏，如下例代码所示，第一个参数 env 为上下文信息，第二个参数 call 为传入的回调函数;

  1. #define NAPI_STATUS_CALL(env, call)                               \
  2.   do {                                                            \
  3.     napi_status status = (call);                                  \
  4.     if (status != napi_ok) {                                      \
  5.       const napi_extended_error_info* error_info = NULL;          \
  6.       napi_get_last_error_info((env), &error_info);               \
  7.       bool is_pending;                                            \
  8.       napi_is_exception_pending((env), &is_pending);              \
  9.       if (!is_pending) {                                          \
  10.         const char* message = (error_info->error_message == NULL) \
  11.             ? "empty error message"                               \
  12.             : error_info->error_message;                          \
  13.         napi_throw_error((env), NULL, message);                   \
  14.         return NULL;                                              \
  15.       }                                                           \
  16.     }                                                             \
  17.   } while(0)

定义 addFn 函数

  1. napi_value addFn(napi_env env, napi_callback_info info) {
  2.   ...
  3. }

获取 Node.js 层传递的参数

使用 Node-API 提供的 napi_get_cb_info 方法获取 napi_callback_info 上下文信息，这一块是 Node.js 层调用函数时传入的参数信息，以下是 napi_get_cb_info 方法的定义：

  1. napi_status napi_get_cb_info(
  2.     napi_env env,
  3.     napi_callback_info cbinfo, // 传递给回调函数的信息，这一块就是 Node.js 层传递过来的值
  4.     size_t* argc, // 指定提供给 argv 数组的长度，并接收的参数长度。
  5.     napi_value* argv, // 存放参数的地方，仅复制指定的 argc 数量的参数，如果少于 argc 指定的数量，其余的参数指定为 Node-API 提供的值 undefined。
  6.     napi_value* thisArg,// 接收 JavaScript 参数 this
  7.     void** data // 接收回调的数据指针
  8. )

定义参数个数 argc 为 2，同样的再定义存储参数的数组 argv，重点还是 napi_get_cb_info 这个方法。

C 语言中通过 & 符号，可以取到该变量对应的内存地址，因此 argc 这个变量会随着实际的参数个数而改变。

  1. napi_value addFn(napi_env env, napi_callback_info info) {
  2.   size_t argc = 2;
  3.   napi_value argv[2];
  5.   NAPI_STATUS_CALL(env, napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
  6. }

对 Node.js 层传入的参数做校验处理

有时候我们需要对参数获取到的参数做一些校验，如果不符合我们的期望希望能抛出一些异常，Node-API 也为我们提供了一些错误信息的 API。

例如 napi_throw_type_error 抛出一个 TypeError 类型错误，n_api_napi_throw_range_error 抛出一个 RangeError 类型错误，更多信息参考 n_api_exceptions。

  1. napi_value addFn(napi_env env, napi_callback_info info) {
  2.   ...
  3.   if (argc < 2) {
  4.     napi_throw_error(env, "BadParameter", "Two parameters are required");
  5.     return NULL;
  6.   }
  7. }

错误处理还有一种是获取参数的类型，做类型校验，这可以通过 napi_typeof 函数获得一个参数的类型。

  1. napi_value addFn(napi_env env, napi_callback_info info) {
  2.   ...
  3.   napi_valuetype argv1Type, argv2Type;
  4.   NAPI_STATUS_CALL(env, napi_typeof(env, argv[0], &argv1Type));
  5.   NAPI_STATUS_CALL(env, napi_typeof(env, argv[1], &argv2Type));
  6.   if (argv1Type != napi_number || argv2Type != napi_number) {
  7.      napi_throw_type_error(env, "ParameterTypeError", "The parameter must be of type number");
  8.     return NULL;
  9.   }
  10. }

Node-API 和 C 类型互转

Node-API 类型的参数是不能直接传递到 C 函数的，这里需要一层转换，例如在 Node.js 我们要表示一个整型会用到 Number 类型，那么如果传递到 C 函数中，可以使用 Node-API 提供的函数 **napi_get_value_int32()** 函数转换为 C 语言中的 int 类型。遇到其它类型也是同样的方法，参考 从 Node-API 转换为 C 类型的函数

  1. napi_value addFn(napi_env env, napi_callback_info info) {
  2.   ...
  4.   int a, b;
  5.   NAPI_STATUS_CALL(env, napi_get_value_int32(env, argv[0], &a));
  6.   NAPI_STATUS_CALL(env, napi_get_value_int32(env, argv[1], &b));
  7. }

add() 这个函数是我们使用标准的 C 类型定义的，很简单的一个示例，但是道理是相同的，现在传入我们转换之后的参数 a、b 是可以正常运算的，但是 add 函数的返回值是一个 C 类型的值，因此 还要从 C 类型转换到 Node-API 支持的类型。

如下例所示，使用 Node-API 提供的 napi_create_int32() 函数转换 C 类型到 Node-API 类型，类似的其它类型也是如此，参考从 C 类型转换为 Node-API 的函数。

  1. int add(int a, int b) {
  2.   int sum = a + b;
  3.   return sum;
  4. }
  6. napi_value addFn(napi_env env, napi_callback_info info) {
  7.   ...
  8.   napi_value sum;
  9.   NAPI_STATUS_CALL(env, napi_create_int32(env, add(a, b), &sum));
  10.   return sum;
  11. }

模块注册

模块注册在第一篇中已经讲解过了，与之类似，我们本次注册模块名称为 calculator。

  1. napi_value init(napi_env env, napi_value exports) {
  2.   napi_property_descriptor properties[] = {
  3.     {
  4.       "add",
  5.       NULL,
  6.       addFn,
  7.       NULL,
  8.       NULL,
  9.       NULL,
  10.       napi_default,
  11.       NULL
  12.     }
  13.   };
  14.   NAPI_STATUS_CALL(env, napi_define_properties(env, exports, 1, properties));
  15.   return exports;
  16. }
  18. NAPI_MODULE(calculator, init);

CMake.js 构建

除了 node-gyp 之外（上一篇使用的是该方式），使用 CMake.js 也是一个不错的选择，CMake.js 是基于 CMake 的构建系统，它不需要你必须安装 Python 环境。

开始之前先使用 NPM 安装 npm install -g cmake-js。

项目根目录创建一个 CMakeLists.txt 文件，写入如下内容：

  1. CMAKE_MINIMUM_REQUIRED(VERSION 3.2 FATAL_ERROR)
  3. # Name of the project (will be the name of the plugin)
  4. project(calculator)
  6. # If there are multiple files separated by spaces
  7. # file(GLOB COMMONM_FILES "src/calculator.c src/other.c")
  8. file(GLOB COMMONM_FILES "src/calculator.c")
  10. # If it is cross-platform, please refer to the following method
  11. # IF(WIN32)
  12. #   file(GLOB OS_FILES "src/win.c")
  13. # ELSE(WIN32)
  14. #   file(GLOB OS_FILES "src/linux.c")
  15. # ENDIF(WIN32)
  16. # set (SOURCE_FILES ${COMMONM_FILES} ${OS_FILES})
  18. set (SOURCE_FILES ${COMMONM_FILES})
  20. # Build a shared library named after the project from the files in `src/`
  21. add_library(${PROJECT_NAME} SHARED ${SOURCE_FILES})
  23. # Gives our library file a .node extension without any "lib" prefix
  24. set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
  26. # Essential include files to build a node addon,
  27. # You should add this line in every CMake.js based project
  28. target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_JS_INC})
  30. # Essential library files to link to a node addon
  31. # You should add this line in every CMake.js based project
  32. target_link_libraries(${PROJECT_NAME} ${CMAKE_JS_LIB})

运行 cmake-js build，可生成一个 ./build/Release/calculator.node 文件。

应用测试

创建 app.js 可以测试下。

  1. const { add } = require('bindings')('calculator');
  2. // console.log(add(1)); // Error: Two parameters are required
  3. // console.log(add('1', 2)); // TypeError: The parameter must be of type number
  4. console.log(add(1, 2)); // 3

Reference


](https://discourse.urho3d.io/t/how-do-you-include-source-in-subdirectories/871/2)