NodeJs使用Addon调用C++

本文介绍的是NodeJs使用node-addon-api调用C++的方法
node-addon-api是一个C++封装，基于N-API构建，目的是提供一个更高级和更易用的接口，但它仍然依赖N-API。
官方参考文档

开发环境

必须具备NodeJs环境
Window配置NodeJs环境（绅士版）
VSCode开发nodejs-c/c++必备插件

npm init -y
npm install node-addon-api
npm install node-gyp

下面介绍的调用C++函数，类，回调，promise，输出二进制等，都需要创建一个 binding.gyp配置文件。
binding.gyp 是一个配置文件，Node.js 使用 node-gyp 工具来编译原生（Native）添加模块时需要用到它，这个文件定义了如何生成原生模块的构建过程和配置。

一个基本的 binding.gyp 通常包含以下内容：

 {"targets": [{"target_name": "addon", //可执行目标的名称，可以在 JavaScript 中使用 require 来引用"sources": ["addon.cc"], //源文件列表，包含你要编译的C++源文件"include_dirs": ["<!@(node -p \"require('node-addon-api').include\")"], //动态地包含 node-addon-api 的头文件目录"dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"], //动态地包括 node-addon-api 的GYP文件//下面这两个代表禁用异常处理。这可以减少一些特性以提高性能或减小生成文件的大小。"cflags!": ["-fno-exceptions"], "cflags_cc!": ["-fno-exceptions"],"defines": ["NAPI_CPP_EXCEPTIONS"] //定义预处理器宏，用于启用 node-addon-api 中的C++异常处理支持}]
}

NodeJs调用c++函数

一个简单的C++加法函数接口
创建C++源文件add.cc

#include <napi.h>Napi::Value Add(const Napi::CallbackInfo& info) //定义一个C++函数Add，返回类型是Napi::Number，参数是Napi::CallbackInfo&，它提供了对JavaScript调用此函数时传递的参数的访问
{Napi::Env env = info.Env();// 检查参数数量和类型if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber()) {Napi::TypeError::New(env, "Number expected").ThrowAsJavaScriptException();return Napi::Number::New(env, 0);}//参数提取和运算double arg0 = info[0].As<Napi::Number>().DoubleValue();double arg1 = info[1].As<Napi::Number>().DoubleValue();double sum = arg0 + arg1;return Napi::Number::New(env, sum); //将C++的double变成JavaScript的数字返回。
}Napi::Object Init(Napi::Env env, Napi::Object exports) 
{//使用 exports.Set 方法将 C++ 函数 Add 导出为JavaScript可调用的函数。exports.Set(Napi::String::New(env, "add"), Napi::Function::New(env, Add)); //"add"是JavaScript中调用这个方法的名称。return exports;
}//使用 NODE_API_MODULE 宏来指定模块的名称 (add) 和初始化函数 (Init)。
//它告诉Node.js在加载模块时应该调用哪个初始化函数。
NODE_API_MODULE(add, Init)

创建index.js文件来调用C++ add函数接口

const a=require("./build/Release/add.node");
console.log(a.add(1,3));

编译与运行

node-gyp rebuild
node index.js

NodeJs调用c++类

一个简单的C++ get/set类
创建c++文件myclass.cc

#include <napi.h>// 定义一个简单的C++类MyClass，用于存储一个整数值
class MyClass {
public:MyClass(int value) : value_(value) {}  // 构造函数，用给定值初始化int getValue() { return value_; }      // 返回当前存储的值void setValue(int value) { value_ = value; }  // 设置新的值
private:int value_;  // 存储的整数值
};// 定义一个包装类Wrapper，用于将MyClass与JavaScript对象关联
class Wrapper : public Napi::ObjectWrap<Wrapper> {
public:// 初始化JavaScript包装类static Napi::Object Init(Napi::Env env, Napi::Object exports);// 构造函数，通过JavaScript调用Wrapper(const Napi::CallbackInfo &info);private:static Napi::FunctionReference constructor;  // 用于JavaScript构造此对象Napi::Value GetValue(const Napi::CallbackInfo &info);  // JavaScript访问函数void SetValue(const Napi::CallbackInfo &info);  // JavaScript修改函数MyClass* myClass_;  // 指向被包装的MyClass实例
};Napi::FunctionReference Wrapper::constructor;// 初始化Wrapper类，定义类函数并设置到exports对象
Napi::Object Wrapper::Init(Napi::Env env, Napi::Object exports) {Napi::HandleScope scope(env);Napi::Function func = DefineClass(env, "MyClass", {InstanceMethod("getValue", &Wrapper::GetValue),  // 绑定到JS对象的成员函数InstanceMethod("setValue", &Wrapper::SetValue)   // 绑定到JS对象的成员函数});constructor = Napi::Persistent(func);constructor.SuppressDestruct();  // 防止垃圾回收exports.Set("MyClass", func);  // 将构造函数导出为模块的一部分return exports;
}// 构造函数实现，用于初始化Wrapper对象，此时创建MyClass实例
Wrapper::Wrapper(const Napi::CallbackInfo &info) : Napi::ObjectWrap<Wrapper>(info) {Napi::Env env = info.Env();Napi::HandleScope scope(env);int value = info[0].As<Napi::Number>().Int32Value();  // 从JavaScript参数中获取整数myClass_ = new MyClass(value);  // 创建MyClass实例
}// 实现getValue，将C++中存储的值返回给JavaScript环境
Napi::Value Wrapper::GetValue(const Napi::CallbackInfo &info) {Napi::Env env = info.Env();Napi::HandleScope scope(env);int value = myClass_->getValue();return Napi::Number::New(env, value);  // 返回值作为JavaScript数字
}// 实现setValue，从JavaScript获取新值并设置到C++类中
void Wrapper::SetValue(const Napi::CallbackInfo &info) {Napi::Env env = info.Env();Napi::HandleScope scope(env);int val = info[0].As<Napi::Number>().Int32Value();myClass_->setValue(val);
}// 初始化模块，将Wrapper类注册到Node.js环境中
Napi::Object InitAll(Napi::Env env, Napi::Object exports) {return Wrapper::Init(env, exports);
}// 定义模块入口，让Node.js在加载时调用InitAll函数
NODE_API_MODULE(mytestclass, InitAll)

创建index.js文件来调用C++ 类

// 导入用C++编写的本地模块，生成的addon在build/Release目录中
const myclass = require('./build/Release/mytestclass');
// 创建MyClass的一个实例，并传递初始值100
const myClassInstance = new myclass.MyClass(100);
// 调用getValue方法，输出当前值（100）
console.log(myClassInstance.getValue());
// 调用setValue方法，将实例的值设置为200
myClassInstance.setValue(200);
// 再次调用getValue方法，输出更新后的值（200）
console.log(myClassInstance.getValue());

编译与运行

node-gyp rebuild
node index.js

NodeJs调用C++输入输出二进制流数据

一个简单的从JS传输二进制数据到C++，C++那边反转处理后传回到JS
创建C++文件bytearray.cc

#include <napi.h>
#include <vector>
#include <iostream>// 获取传入的ArrayBuffer或Buffer对象并将其反转
Napi::Value GetByteArray(const Napi::CallbackInfo& info) {Napi::Env env = info.Env();// 定义一个vector来存储二进制数据std::vector<uint8_t> binaryData;// 检查传入参数是否为Bufferif (info[0].IsBuffer()) {Napi::Buffer<uint8_t> inputBuffer = info[0].As<Napi::Buffer<uint8_t>>();// 将Buffer数据复制到vectorbinaryData.assign(inputBuffer.Data(), inputBuffer.Data() + inputBuffer.ByteLength());std::cout << "IsBuffer" << std::endl;}// 检查传入参数是否为ArrayBufferelse if (info[0].IsArrayBuffer()) {Napi::ArrayBuffer inputArrayBuffer = info[0].As<Napi::ArrayBuffer>();// 将ArrayBuffer数据复制到vectorbinaryData.assign(static_cast<uint8_t*>(inputArrayBuffer.Data()), static_cast<uint8_t*>(inputArrayBuffer.Data()) + inputArrayBuffer.ByteLength());std::cout << "IsArrayBuffer" << std::endl;}// 数据反转操作std::reverse(binaryData.begin(), binaryData.end());// 返回反转后的数据作为新的Buffer对象给JavaScript调用return Napi::Buffer<uint8_t>::Copy(env, binaryData.data(), binaryData.size());
}// 初始化模块，将GetByteArray函数导出为Node.js可用函数
Napi::Object InitAll(Napi::Env env, Napi::Object exports) {exports.Set(Napi::String::New(env, "getByteArray"), Napi::Function::New(env, GetByteArray));return exports;
}// 定义模块，这样Node.js可以在加载时调用InitAll函数
NODE_API_MODULE(bytearrary, InitAll)

**创建index.js文件来调用C++ **

const bytearrary = require('./build/Release/bytearrary');
const { Buffer } = require('node:buffer');const binaryData = Buffer.from([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A]);// 获取底层 ArrayBuffer
const arrayBuffer = binaryData.buffer.slice(binaryData.byteOffset, binaryData.byteOffset + binaryData.byteLength);
//不能直接拿binaryData.buffer，会拿到整个buffer分配ArrayBuffer的内存池大小，通常为8192
//const arrayBuffer = binaryData.buffer;console.log(arrayBuffer);
console.log(arrayBuffer.byteLength); // 输出 ArrayBuffer 的字节长度const initialArray = new Uint8Array([1, 2, 3, 4, 5]); // 创建并初始化一个 Uint8Array
const buffer = initialArray.buffer;const byteArray = bytearrary.getByteArray(buffer);
console.log(byteArray); // 输出
console.log(byteArray.length); // 输出

编译与运行

node-gyp rebuild
node index.js

NodeJs调用C++ promise实现异步

一个简单C++封装promise提供给JS使用
创建C++文件promise.cc

#include <napi.h>
#include <chrono>
#include <thread>// 自定义的异步任务类，继承自Napi::AsyncWorker
class AsyncWorker : public Napi::AsyncWorker {
public:// 构造函数接收一个Promise的Deferred对象用于后续的resolve/reject操作AsyncWorker(Napi::Promise::Deferred deferred): Napi::AsyncWorker(Napi::Function::New(deferred.Env(), [](const Napi::CallbackInfo&) {})),deferred(deferred) {}// 此函数在后台线程中执行长时间的操作void Execute() override {// 模拟一个耗时操作，例如网络请求或I/Ostd::this_thread::sleep_for(std::chrono::seconds(2));// 假设操作得到的结果为42result_ = 42;}// 当Execute执行完成成功时，调用此函数void OnOK() override {// 使用deferred对象将结果传递回JavaScript，标记为resolved状态deferred.Resolve(Napi::Number::New(Env(), result_));}// 如果Execute过程中产生错误，调用此函数void OnError(const Napi::Error& e) override {// 使用deferred对象将错误传递回JavaScript，标记为rejected状态deferred.Reject(e.Value());}private:Napi::Promise::Deferred deferred; // 用于操作JavaScript中的Promise对象int result_; // 任务的计算结果
};// 在JavaScript中调用的函数，启动异步任务并返回Promise
Napi::Value AsyncFunction(const Napi::CallbackInfo& info) {Napi::Env env = info.Env();// 创建一个Promise的Deferred对象，供异步操作使用Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(env);// 创建并启动异步任务AsyncWorker* worker = new AsyncWorker(deferred);worker->Queue();// 返回Promise给JavaScript调用方return deferred.Promise();
}// 初始化模块，将asyncFunction导出为Node.js中的可用函数
Napi::Object InitAll(Napi::Env env, Napi::Object exports) {exports.Set(Napi::String::New(env, "asyncFunction"), Napi::Function::New(env, AsyncFunction));return exports;
}// 定义模块，在Node.js加载模块时调用InitAll函数
NODE_API_MODULE(promise, InitAll)

**创建index.js文件来调用C++ **

const addon = require('./build/Release/promise');async function test() {try {const result = await addon.asyncFunction();console.log(result); // 等待两秒输出: 42} catch (err) {console.error(err);}
}test();

编译与运行

node-gyp rebuild
node index.js

NodeJs调用C++回调

一个简单的C++回调提供给js使用
创建C++文件callback.cc

#include <napi.h>// 这个函数将在C++代码中被当作回调函数调用
void CallJsCallback(const Napi::CallbackInfo& info) {Napi::Env env = info.Env();// 获取传入的第一个参数，即JavaScript中的回调函数if (!info[0].IsFunction()) {Napi::TypeError::New(env, "Expecting a function as first argument").ThrowAsJavaScriptException();return;}Napi::Function callback = info[0].As<Napi::Function>();// 执行回调并传递参数// 这里我们传回数字42给JavaScriptcallback.Call(env.Global(), { Napi::Number::New(env, 42) });
}// 初始化模块，将CallJsCallback函数导出为Node.js中的可用函数
Napi::Object InitAll(Napi::Env env, Napi::Object exports) {exports.Set(Napi::String::New(env, "callJsCallback"), Napi::Function::New(env, CallJsCallback));return exports;
}// 定义模块，在Node.js加载模块时调用InitAll函数
NODE_API_MODULE(callbacke, InitAll)

**创建index.js文件来调用C++ **

const addon = require('./build/Release/callbacke');// 定义一个回调函数，将在C++代码中被调用
function myCallback(number) {console.log('Callback called with value:', number);
}// 调用本地模块的函数，并传递JavaScript的回调函数
addon.callJsCallback(myCallback);

编译与运行

node-gyp rebuild
node index.js

更多代码示例：
demo