N-API
N-API(N是一个字母,然后是API)是用于构建本机插件的API。它独立于底层JavaScript运行时(例如V8)。并作为Node.js本身的一部分。此API将作为跨Node.js版本已编译的应用程序接口(Application Binary Interface)的稳定版,简称(ABI)。它是为了将Addons插件和底层JavaScript引擎的改动隔离开来,并且允许在一个版本编译的模块不需要重新编译就可以在更高版本的Node.js上运行。ABI稳定版指南中提供了更深入的说明。
Addons插件使用和C++ Addons章节中提到的相同的方法和工具进行编译和打包。唯一的区别是原始代码使用的API集。不使用V8或Native Abstractions for Node.js API,而是使用N-API中可用的功能。
N-API暴露的API通常是用来创建和操作JavaScript的values。概念和操作通常映射到ECMA262语言规范中指定的思想。这些API具有以下属性:
- 所有N-API调用都返回一个 napi_status 类型的状态代码。此状态表示API调用是成功还是失败。
- API的返回值通过一个out参数传递。
- 所有javascript的值都抽象成一个隐晦的 napi_value 类型。
- 如果出现错误状态代码,使用napi_get_last_error_info可以获得额外的错误信息。
- 在错误处理章节中能找到更多的错误处理信息。
N-API是一个C语言的API,它确保了node.js版本和不同编译器级别之间应用程序接口(ABI)的稳定性。C++ API可以更容易使用。为了支持使用C++,这个项目使用了一个C++包装器模块叫做node-addon-api。这个包装器提供了一个可内联的C++ API。使用node-addon-api构建的二进制文件将依赖于Node.js导出的基于C函数符号的N-API接口。node-addon-api是一种更有效写代码的方法,用来编写调用N-API。举个例子,根据下面的 node-addon-api代码。第一部分展示了node-addon-api代码,第二部分
展示了addon插件中实际上的调用。
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_crate_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;
}
最终结果是,addon插件只使用导出的C的API。因此,它仍然获得了C API提供的ABI稳定性的好处。
当使用node-addon-api而不是C API时,可以阅读node-addon-api的API文档。