Node-API

Node-API

稳定性: 2 - 稳定

• Node-API，以前叫 N-API，用于构建本机插件

• Node-API 独立于 JS Runtime（如V8），并作为Node.js的一部分进行维护

• Node-API 在 Node.js 将来的各个版本中都提供稳定的应用程序二进制接口(ABI，Application Binary Interface)

• Node-API 的目标是解耦插件(addons)与JS引擎，因为JS引擎在不断地修改升级，允许Node-API为Node.js的一个主版本(major version)编译的模块可在更高的主版本上运行，无需重新编译

• 了解更多参考ABI稳定性指南

---

• 插件(addons)使用同样的方法/工具在 C++ Addons 章节中进行构建/打包

• 唯一的区别是本机代码使用的 API 集合

• 使用 Node-API 中本身可用的函数，取代了使用 V8 或 Node.js本机抽象 的API

• Node-API 暴露的 APIs 通常用于创建和操作 JavaScript 值

• 概念和操作通常映射到 ECMA-262语言规范 中指定的思想

• API具有以下属性：

  • 所有Node-API调用都返回 napi_status 类型的状态代码

    • napi_status指示API调用是成功还是失败

  • API的返回值通过out参数传递

  • 所有的JS值都抽象在一个名为 napi_value 的不透明类型后面

  • 如果出现错误状态代码，可使用 napi_get_last_error_info 获取其他信息

    • 更多详情参考错误处理部分

---

• Node API基于C API，因此可以确保跨越不同Node.js版本以及使用不同编译器级别时的ABI稳定性

• C++ API通常更易于使用，项目还维护一个C++包装模块(node-addon-api)以支持C++

  • 包装器 node-addon-api 提供一个可链接的 C++ API

  • 使用 node-addon-api 构建二进制文件取决于 node.js 导出的基于 Node-API C-based 函数的符号

  • node-addon-api 编写调用Node-API代码更高效，以下面的node-addon-api代码为例

    • 第一部分是 node-addon-api 代码

    • 第二部分是插件中实际使用的内容

    Object obj = Object::New(env);
    obj["foo"] = String::New(env, "bar");
    

    napi_status status;
    napi_value object, string;
    status = napi_create_object(env, &object);
    if (status != napi_ok) {
      napi_throw_error(env, ...);
      return;
    }
    
    status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
    if (status != napi_ok) {
      napi_throw_error(env, ...);
      return;
    }
    
    status = napi_set_named_property(env, object, "foo", string);
    if (status != napi_ok) {
      napi_throw_error(env, ...);
      return;
    }
    

---

• 最终结果是插件只使用导出的C API

  • 因此，它仍然可以受益于C API提供的ABI稳定性

• 当使用 node-addon-api 而不是 C APIs 时，请从 node-addon-api 的API文档开始

• Node-API的资源为使用 Node-API 和 node-addon-api 的新手开发者提供了很好的方向和提示