Node-API | Node.js API 文档

稳定性： 2 - 稳定

Node-API（前称 N-API）是用于构建原生插件的 API。它独立于底层 JavaScript 运行时（例如 V8），并作为 Node.js 的一部分进行维护。该 API 在 Node.js 的各个版本之间将保持应用二进制接口（ABI）稳定。其目的是将插件与底层 JavaScript 引擎的变化隔离开来，并允许为一个主要版本编译的模块在 Node.js 的后续主要版本上运行，而无需重新编译。ABI 稳定性指南提供了更深入的说明。

【Node-API (formerly N-API) is an API for building native Addons. It is independent from the underlying JavaScript runtime (for example, V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate addons from changes in the underlying JavaScript engine and allow modules compiled for one major version to run on later major versions of Node.js without recompilation. The ABI Stability guide provides a more in-depth explanation.】

插件的构建/打包采用了在标题为 C++ 插件的部分中概述的相同方法/工具。唯一的区别在于本地代码使用的 API 集。Node-API 中可用的函数取代了 V8 或 Node.js 的原生抽象 API。

【Addons are built/packaged with the same approach/tools outlined in the section titled C++ Addons. The only difference is the set of APIs that are used by the native code. Instead of using the V8 or Native Abstractions for Node.js APIs, the functions available in Node-API are used.】

Node-API 暴露的 API 通常用于创建和操作 JavaScript 值。其概念和操作通常对应于 ECMA-262 语言规范中指定的思想。这些 API 具有以下特性：

【APIs exposed by Node-API are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified in the ECMA-262 Language Specification. The APIs have the following properties:】

所有 Node-API 调用都会返回类型为 napi_status 的状态码。该状态码表示 API 调用是成功还是失败。
API 的返回值通过输出参数传递。
所有 JavaScript 值都被抽象为一个名为 napi_value 的不透明类型。
在出现错误状态码时，可以使用 napi_get_last_error_info 获取更多信息。更多信息可以在错误处理部分错误处理中找到。

Node-API 是一个 C 语言 API，可确保在不同的 Node.js 版本和不同的编译器级别之间保持 ABI 稳定性。C++ API 使用起来可能更简单。为了支持使用 C++，该项目维护了一个名为 node-addon-api 的 C++ 封装模块。该封装提供了可内联的 C++ API。使用 node-addon-api 构建的二进制文件将依赖于 Node.js 导出的基于 C 的 Node-API 函数符号。node-addon-api 是编写调用 Node-API 代码的一种更高效的方式。例如，下面的 node-addon-api 代码。第一部分显示了 node-addon-api 代码，第二部分显示了实际在插件中使用的内容。

【Node-API is a C API that ensures ABI stability across Node.js versions and different compiler levels. A C++ API can be easier to use. To support using C++, the project maintains a C++ wrapper module called node-addon-api. This wrapper provides an inlinable C++ API. Binaries built with node-addon-api will depend on the symbols for the Node-API C-based functions exported by Node.js. node-addon-api is a more efficient way to write code that calls Node-API. Take, for example, the following node-addon-api code. The first section shows the node-addon-api code and the second section shows what actually gets used in the 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_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 接口。因此，它仍然可以享受 C 接口提供的 ABI 稳定性带来的好处。

【The end result is that the addon only uses the exported C APIs. As a result, it still gets the benefits of the ABI stability provided by the C API.】

在使用 node-addon-api 而不是 C API 时，首先使用 node-addon-api 的 API 文档。

【When using node-addon-api instead of the C APIs, start with the API docs for node-addon-api.】

Node-API 资源为刚开始使用 Node-API 和 node-addon-api 的开发者提供了出色的入门指导和建议。更多的媒体资源可以在 Node-API 媒体页面找到。

【The Node-API Resource offers an excellent orientation and tips for developers just getting started with Node-API and node-addon-api. Additional media resources can be found on the Node-API Media page.】