从c++ addon看napi的实现

Node.js的napi极大地方便了c++ addon的编写，使得用户不再那么需要面对复杂的v8。本文通过一个例子来分析一下napi的使用和napi到底做了什么。

1 导出给js使用的功能

#include <node_api.h>
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

上面的代码是使用napi时的通用模式，我们只需要实现Init函数就行（当然也可以叫其他名字）。接下来我们看看Init的实现。

napi_value Init(napi_env env, napi_value exports) {
  napi_value func;
  // 创建一个函数并且设置为exports对象的getArray属性的值
  napi_create_function(env,
                      NULL,
                      NAPI_AUTO_LENGTH,
                      newArray,
                      NULL,
                      &func);
  napi_set_named_property(env, exports, "getArray", func);
  return exports;
}

napi_create_function也是napi提供的api，他的作用是创建一个函数，具体可以参考napi的文档。接着把这个函数导出给js使用，名字是getArray。当js执行getArray的时候就会执行newArray函数。

2 newArray的实现

static napi_value newArray(napi_env env, napi_callback_info info) {
   size_t argc = 1;
   napi_value args[1];
   // 拿到js层的入参，这里是一个
   napi_get_cb_info(env, info, &argc, args, NULL, NULL);
   int len;
   // js传入的是一个数字，v8转成了对象，这里再次把入参转成int型
   napi_get_value_int32(env, args[0], &len);
   napi_value ret;
   // 创建一个数组
   napi_create_array(env, &ret);
   // 根据js入参设置数组的初始值
   for (int i = 0; i < len; i++) {
     napi_value num;
     napi_create_int32(env, i, &num);
     napi_set_element(env, ret, i, num);
   }

  return ret;
}

3 使用c++ addon

const { getArray } = require('./build/Release/test.node');
console.log(getArray(20)); 

执行上面代码最后输出

[
   0,  1,  2,  3,  4,  5,  6,
   7,  8,  9, 10, 11, 12, 13,
  14, 15, 16, 17, 18, 19
]

4 分析

上面的代码并不复杂，本文主要是分析napi提供的api，看看napi到底做了什么。很多api的原理是类似的，这里只以数组的api为例子。因为v8的api中，使用的参数基本都是v8提供的对象。napi做的事情其实就是帮我们处理这些对象的转换。我们首先看看napi_create_array的实现。

// 创建一个数组，对应js的数组
napi_status napi_create_array(napi_env env, napi_value* result) {
  // 调用v8接口v8::Array::New创建一个数组对象，然后转成napi的类型，并设置返回值
  *result = v8impl::JsValueFromV8LocalValue(
      v8::Array::New(env->isolate));
  return napi_clear_last_error(env);
}

我们看到napi_create_array的实现非常简单，就是对v8接口的封装，然后转换成napi的类型，最后清除错误信息。这是napi典型的api使用方式。主要包括下面几个
1 入参需要传入env对象，并传入一个二级指针napi_value *，用于保存接口返回值。napi的返回值不是通过函数体的return返回的，return返回的是api的执行状态（成功或失败）。
2 处理v8的api
3 清除或返回错误信息
每次执行napi提供的api时，如果执行出错则通过napi_set_last_error设置到env中并返回错误码，如果没有则通过napi_clear_last_error清除错误信息并返回napi_ok。我们看一下实现

// 设置当前函数调用的错误信息
static inline napi_status napi_set_last_error(napi_env env, napi_status error_code,
                                uint32_t engine_error_code = 0,
                                void* engine_reserved = nullptr) {
  env->last_error.error_code = error_code;
  env->last_error.engine_error_code = engine_error_code;
  env->last_error.engine_reserved = engine_reserved;
  return error_code;
}

// 清除上次调用的错误信息
static inline napi_status napi_clear_last_error(napi_env env) {
  env->last_error.error_code = napi_ok;

  // TODO(boingoing): Should this be a callback?
  env->last_error.engine_error_code = 0;
  env->last_error.engine_reserved = nullptr;
  return napi_ok;
}

调用方在调用完api后，如果产生了错误，则可以通过napi_get_last_error_info接口获取执行api的错误信息。

// 获取上一个调用函数的错误信息
napi_status napi_get_last_error_info(napi_env env,
                                     const napi_extended_error_info** result) {
  // 初始化为非法值
  const int last_status = napi_detachable_arraybuffer_expected;
  // 根据错误码设置错误描述信息（每次调用api后调用结果存到env中）
  env->last_error.error_message =
      error_messages[env->last_error.error_code];

  *result = &(env->last_error);
  return napi_ok;
}

言归正传，调用napi_create_array后，我们拿到一个返回值，比如下面的ret。

napi_value ret;
napi_create_array(env, &ret);

之前分析过napi_value本质上是一个一级指针。接着我们看如何使用从napi中拿到的数组。我们可以通过napi_set_element设置数组的内容。

// ret是数组，i是索引，num是一个napi_value变量，本质是一个v8对象，即索引对应的值
napi_set_element(env, ret, i, num);

下面我们看看napi_set_element的实现。

// 设置key对应的值，key是数字
napi_status napi_set_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value value) {
  v8::Local<v8::Context> context = env->context();
  v8::Local<v8::Object> obj;
  // 把napi_value object转成v8的Object，数组继承Object
  CHECK_TO_OBJECT(env, context, obj, object);
  // 把值napi_value value转成v8对象
  v8::Local<v8::Value> val = v8impl::V8LocalValueFromJsValue(value);
  // 调用v8 Object对象的Set方法设置对象的属性，即数组的元素
  auto set_maybe = obj->Set(context, index, val);
  // 执行结果处理
  RETURN_STATUS_IF_FALSE(env, set_maybe.FromMaybe(false), napi_generic_failure);

  return GET_RETURN_STATUS(env);
}

从上面的分析中，我们大致可以看到napi实现中的一些规律，get的api的逻辑是调用v8接口拿到v8类型的对象，然后转成napi_value类型返回给调用方，set的api是传入napi_value类型，然后转成v8类型的对象。

napi的实现几乎都在js_native_api_v8.cc中，有兴趣的同学可以看一下，大多数api的实现并不复杂，了解js_native_api_v8.cc的实现，不仅让我们更好地使用napi，也让我们更加了解v8的使用和原理。