Node-Addon-API 中处理 Promise 返回时的异常捕获问题解析

在 Node.js 原生扩展开发中，使用 Node-Addon-API 处理 JavaScript Promise 时，开发者可能会遇到一个微妙的异常处理问题。本文深入分析这个问题背后的原理，并提供正确的解决方案。

问题现象

当从 C++ 代码接收并处理 JavaScript 函数返回的 rejected Promise 时，即使开发者已经添加了 catch 处理程序，仍然会触发 Node.js 的 unhandledRejection 事件。通过调试可以发现，系统实际上在处理两个不同的 Promise 对象：一个是开发者显式创建的，另一个则是隐式生成的"幽灵 Promise"。

问题根源分析

问题的核心在于 C++ 代码中对 Promise 的处理方式。在原始示例中，开发者分别调用了 Promise 的 catch 和 then 方法：

r.ToObject().Get("catch").As<Function>().Call(r, 1, &js_catch);
r.ToObject().Get("then").As<Function>().Call(r, 1, &js_then);

这种方式相当于 JavaScript 中的：

promise.catch(onCaught);
promise.then(onFulfill);

这种写法会产生两个独立的 Promise 链，其中第二个 then 调用创建的 Promise 没有被正确处理，导致 Node.js 的事件循环检测到未处理的 rejection。

正确解决方案

正确的做法是使用 then 方法的两个参数一次性注册 fulfillment 和 rejection 处理程序：

napi_value args[] = {js_then, js_catch};
r.ToObject().Get("then").As<Function>().Call(r, 2, args);

这等同于 JavaScript 中的：

promise.then(onFulfill, onCaught);

这种方式只创建一个 Promise 链，确保所有可能的路径都被正确处理，不会留下未处理的 rejection。

技术细节深入

1. Promise 链式调用机制：每次调用 then/catch 都会返回一个新的 Promise，原始代码实际上创建了分支的 Promise 链。

2. Node.js 的 rejection 处理机制：Node.js 会跟踪所有未处理的 Promise rejection，通过微任务队列检测未被捕获的异常。

3. 跨语言边界处理：在 C++ 和 JavaScript 之间传递 Promise 需要特别注意生命周期管理和异常传播。

最佳实践建议

1. 在 Node-Addon-API 中处理 Promise 时，尽量保持与 JavaScript 相同的处理模式。

2. 对于复杂的异步流程，考虑在 JavaScript 侧封装逻辑，减少跨语言边界的 Promise 处理。

3. 使用 Node-Addon-API 提供的 Promise 工具函数简化代码。

4. 在开发过程中启用 Node.js 的 --trace-warnings 标志，帮助诊断 Promise 相关问题。

总结

正确处理跨语言边界的 Promise 需要开发者深入理解 JavaScript 异步机制和 Node-Addon-API 的工作方式。通过本文的分析，开发者可以避免常见的 Promise 处理陷阱，编写出更健壮的 Node.js 原生扩展代码。记住，在异步编程中，细节决定成败，特别是在跨语言交互的场景下。