现代 Node.js Addon 的异常处理
Node.js Addon 是 Node.js 生态不可或缺的一部分，它让大量的现存库可以通哦简单的包装即可被 Node.js 程序所调用。而作为 Node.js ABI 稳定计划的一部分，node-addon-api 即将要发布 v4.1.0 版本，我们来看看这次版本更新中对于 JavaScript 异常处理的机制更新吧。
我们先从 JavaScript 异常机制开始讲起吧。
JavaScript 异常
熟悉 JavaScript 的同学都知道，通过 throw 语句我们能够提前中断函数执行、并且给调用者返回一个异常值。而调用者可以通过 try...catch 语句捕获这个异常，并且处理异常值：
try {
throw new Error()
} catch (error) {
// 处理 error...
}除了普通函数之外，在 JavaScript 中还会有许许多多操作都可能引发异常。比如对象属性访问器异常：
const obj = {
get foo() {
throw new Error();
},
};
obj.foo; // => Error如Proxy handler 异常：
// Proxy handler 异常
const proxy = new Proxy({}, {
ownKeys(target) {
throw new Error();
},
});
for (let _ in proxy) {} // => Error甚至是赋值语句也可能发生异常：
// const 赋值异常
const foo = 'bar';
foo = '!!'; // => TypeError对象属性赋值也可能抛出异常：
// globalThis 中非 writable 属性赋值异常
function it() {
'use strict';
Object.defineProperty(globalThis, 'globalFoo', { value: 'foo' });
globalFoo = 'bar';
}
it(); // => TypeError由此可见，在 JavaScript 中，我们编码时需要注意任意一句 JavaScript 语句都有可能发生异常。当然有些异常是编码错误，如通常情况下上述的几例赋值异常；而有些异常是运行时异常，比如 Node.js 中常见的访问文件出现 ENOENT 文件不存在错误。这些异常通常有不同的处理方式。
现在，也有很多模块是通过 Native Addon 的方式给 Node.js 拓展能力的。这些模块中也常常会调用到各种 JavaScript 逻辑中去，比如 Native 函数获取传入的 JavaScript 对象中的值、异步任务结束后调用 JavaScript 回调通知状态等等。那么在 Node.js Native Addon 中，我们该如何处理异常呢？
Native/C++ 异常
C++ 异常
在现代 C++ 中，同样有类似于我们熟悉的 JavaScript 的异常处理机制：
#include <stdexcept>
#include <iostream>
void fn() {
throw std::runtime_error("bang!");
}
int main() {
try {
fn();
} catch (std::runtime_error err) {
std::cout << "Caught: " << err.what() << std::endl;
}
}通过外层的 try...catch 我们可以让程序捕获异常并且输出 Caught: bang!。而如果没有这个 try...catch 的话，程序就会直接因为这个未捕获异常而崩溃：
libc++abi: terminating with uncaught exception of type std::runtime_error: bang!Node.js Addon 的编译产物是一个动态库，这个动态库会将其初始化函数注册到 Node.js 环境中。
#include <node_api.h>
#include <stdexcept>
static napi_value
DoSomething(napi_env env, napi_callback_info info) {
throw std::runtime_error("bang!");
}
NAPI_MODULE_INIT() {
// 这个函数会在 Node.js 环境第一次加载这个 addon 的时候执行
napi_value exported_function;
napi_create_function(env,
"DoSomething",
NAPI_AUTO_LENGTH,
DoSomething,
NULL,
&exported_function);
napi_set_named_property(env,
exports,
"DoSomething",
exported_function);
}Node.js 和他使用的 JavaScript 引擎 V8 因为历史原因，都是不启用现代 C++ 异常的特性的。那么如果我们在 addon 中使用了 C++ 异常并且未处理这个异常，那么 Node.js 程序同样的会在直接崩溃：
const addon = require('./build/Release/addon.node');
addon.DoSomething(); // libc++abi: terminating with uncaught exception of type std::runtime_error: bang!那么，我们该如何在 Addon 中统一处理 JavaScript 异常与 C++ 异常呢？
V8 的异常处理
我们刚刚提到，Node.js 和他使用的 JavaScript 引擎 V8 因为历史原因，都是不启用现代 C++ 异常的特性的。那么在 V8 中我们需要如何处理 JavaScript 异常呢？在 V8 API 中，我们可以通过 v8::TryCatch 来拦截异常，就像我们在 JavaScript 中写一个 try...catch 代码块一样。
void DoSomething(v8::Local<v8::Context> context, v8::Local<v8::Function> fn) {
v8::HandleScope handle_scope(context->GetIsolate());
v8::TryCatch try_catch(context->GetIsolate()); // 在当前作用域声明一个 TryCatch
fn->Call(context, fn, 0, {});
if (try_catch.HasCaught()) {
// 捕获到了异常
v8::Local<v8::Value> exception = try_catch.Exception();
}
}不过，v8::TryCatch 并不会打断当前 C++ 代码的执行流程，而只是让一个对象的状态设置为了“异常已捕获”。这种情况下，如果编码的同学没有多加小心，就有可能让代码在异常状态下进入正常流程：
void DoSomething(v8::Local<v8::Context> context, v8::Local<v8::Function> fn) {
...
Local<Value> value = fn->Call(context, fn, 0, {});
value.As<Object>()->Get(context, 0); // 即使发生了异常，这行代码同样会执行
...
}这将会导致非常大的编码隐患。对于这种问题，V8 将所有可能出现 JavaScript 异常的 API 返回值都定义为了 Maybe 型，比如 v8::MaybeLocal<v8::Value> v8::Function::Call(v8::Local<v8::Context>, v8::Local<v8::Value> recv, int argc, v8::Local<v8::Value> argv[])，v8::MaybeLocal<v8::Value> v8::Object::Get(v8::Local<v8::Context>, uint32_t index) 等等。这些 Maybe/MaybeLocal 起到了什么作用？我们再来看上面这段代码
void DoSomething(v8::Local<v8::Context> context, v8::Local<v8::Function> fn) {
...
MaybeLocal<Value> value = fn->Call(context, fn, 0, {});
value.As<Object>()->Get(context, 0); // 编译失败！MaybeLocal<Value> 需要先转换为 Local<Value>
...
}因为 MaybeLocal<Value> 类型并不等同于 Local<Value>，我们无法直接将 MaybeLocal<Value> 作为 Local<Value> 类型使用，而将 MaybeLocal<Value> 转换为 Local<Value> 则需要妥当的处理，比如先检查异常值、断言 MaybeLocal<Value> 不为空等等。这与现代语言中常见的 Optional<> 类似，如 Rust 中的 Option<T>、Swift 中的 Optional<Wrapped>。
对于没有任何 JavaScript try...catch 处理、也没有 Native 代码通过 v8::TryCatch 处理的异常，v8 会将这个异常路由到在 v8::Isolate::AddMessageListener 注册的消息监听中去。在 Node.js 中，就代表这个异常最终可以通过 process.on('uncaughtException', err => {}); 监听到。
node-addon-api
在 Node.js 发布了稳定 ABI 的 Node-API 支持后，我们的 Addon 二进制终于可以在多个 Node.js 版本之间通用了。不过 Node-API 是纯 C 接口，为了让开发者们能够便捷地使用 C++ 开发 Addon，Node.js 还官方维护了一个 C++ 库 node-addon-api 来让开发者以 C++ 接口调用 Node-API。那么，在这个 C++ Addon 写法中，我们该如何处理 JavaScript 异常呢？
在 v4.0.0 及之前的版本，node-addon-api 有两种方式可以处理 JavaScript 异常。
第一种，即是通过类似于 v8::TryCatch 的方式，通过检查当前的 JavaScript 引擎状态来确认是否存在异常；
#include <napi.h>
#include <iostream>
void Hello(const Napi::CallbackInfo& info) {
Napi::Env env = info.Env();
Napi::Object target = info[0].As<Napi::Object>();
Napi::String name = target.Get("name").As<Napi::String>();
if (env.IsExceptionPending()) {
Napi::Error e = env.GetAndClearPendingException();
std::cout << "caught: " + e.Message() << std::endl;
return;
}
std::cout << "hello " << name.Utf8Value() << std::endl;
}
Napi::Object Init(Napi::Env env, Napi::Object exports) {
exports.Set(Napi::String::New(env, "hello"),
Napi::Function::New(env, Hello));
return exports;
}
NODE_API_MODULE(hello, Init)如果我们通过以下 JavaScript 代码调用这个 Addon：
const addon = require('./build/Release/addon.node');
addon.hello({
get name() {
throw new Error('foo');
},
});那么程序会输出 caught: foo。
我们可以发现，这个方式就如同我们上面提到的一样，JavaScript 异常并不会中断 C++ 代码逻辑的执行，我们需要人工添加检查点避免遗漏异常处理而导致程序逻辑异常，而人工的添加与检查必然导致异常的遗漏处理。这非常繁琐、不可靠。
第二种更加可靠的方式，是启用 C++ 异常，那么这些 JavaScript 异常就会直接以 C++ 异常的方式抛出、处理。我们可以写成这样：
#include <napi.h>
#include <iostream>
void Hello(const Napi::CallbackInfo& info) {
Napi::Env env = info.Env();
Napi::Object target = info[0].As<Napi::Object>();
try {
Napi::String name = target.Get("name").As<Napi::String>();
std::cout << "hello " << name.Utf8Value() << std::endl;
} catch (Napi::Error e) {
std::cout << "caught: " << e.what() << std::endl;
}
}
Napi::Object Init(Napi::Env env, Napi::Object exports) {
exports.Set(Napi::String::New(env, "hello"),
Napi::Function::New(env, Hello));
return exports;
}
NODE_API_MODULE(hello, Init)通过同样的 JavaScript 调用，我们可以得到同样的输出。相比与第一种方式，这种方式我们不需要每一个语句都判断是否发生了异常，只需要在我们需要异常处理的语句上做异常处理即可，就如同 JavaScript 一般。而未被处理的 JavaScript 异常则会被抛回到 JavaScript 中，JavaScript 代码同样可以通过 try...catch 代码块捕获、处理。
并且，如果启用了 C++ 异常，我们还可以通过 throw Napi::Error::New(env, "bang!"); 的方式直接抛出 JavaScript 异常。
这看起来非常棒，难道不是吗？
遗憾的是，就如同 Node.js 和 V8 一样存在历史性原因不能启用 C++ 异常一样，同样会有许许多多的项目对于启用 C++ 异常有所顾虑或者负担。为此，我们在 node-addon-api 中也引入了 Maybe 类型，这个特性可以通过宏定义 NODE_ADDON_API_ENABLE_MAYBE 启用。
Napi::Maybe 类型与 V8 的 Maybe、各种现代语言中如 Rust 中的 Option<T>、Swift 中的 Optional<Wrapped> 一样，都包含了两种状态 Just<T> 和 Nothing。其中 Just<T> 代表了没有发生异常，并且返回一个一个 T；而 Nothing 就表示发生了异常，这个 Maybe 盒子中没有任何值。
我们可以通过 T Napi::Maybe::Unwrap() 方便地断言这个 Maybe 盒子中必定存在值并且获取这个值。也可以通过 bool Napi::Maybe::IsNothing() 等方法来条件性地处理各种可能的情况。
我们将所有可能调用进入 JavaScript 代码的 API 做了返回类型标记，避免开发者遗漏 JavaScript 的异常处理：
#define NODE_ADDON_API_ENABLE_MAYBE
#include <napi.h>
#include <iostream>
void Hello(const Napi::CallbackInfo& info) {
Napi::Env env = info.Env();
Napi::Object target = info[0].As<Napi::Object>();
Napi::Maybe<Napi::String> maybe_name = target.Get("name").As<Napi::String>();
if (maybe_name.IsNothing()) {
Napi::Error e = env.GetAndClearPendingException();
std::cout << "caught: " + e.Message() << std::endl;
return;
}
Napi::String name = maybe_name.Unwrap(); // 已经处理了异常，这里我们解包 Maybe（如果此时 Maybe 为空则会导致程序奔溃）
std::cout << "hello " << name.Utf8Value() << std::endl;
std::cout << "caught: " << e.what() << std::endl;
}这样，我们需要以明确、显式地方式处理所有 JavaScript 异常。如果一个 Napi::Maybe<> 类型没有被妥善地转换成需要的类型就直接被使用了，编译器会直接替我们检查出有可能没有处理的异常。也就是说，这个特性利用了编译器的类型检查帮助我们发现潜在的代码缺陷。
这给没有启用 C++ 异常的 Addon 增加了编码可靠性。这个特性将在 node-addon-api 下一次版本发布 v4.1.0 中发行。
作为 Node.js 项目与 node-addon-api 项目的维护者，我们也非常期待使用 Node.js 与 node-addon-api 的小伙伴们与我们分享与反馈 Node.js Addon 开发过程中碰到的问题噢！下期再见