深入理解rvagg/nan中的对象包装机制

深入理解rvagg/nan中的对象包装机制

前言

在Node.js原生扩展开发中，将C++对象暴露给JavaScript使用是一个常见需求。rvagg/nan项目提供了Nan::ObjectWrap类来简化这一过程，本文将详细介绍如何使用它来包装C++对象。

什么是对象包装

对象包装(Object Wrapping)是一种将C++对象与JavaScript对象关联起来的技术。通过这种技术，我们可以在JavaScript中创建、访问和操作C++对象，就像操作普通JavaScript对象一样。

Nan::ObjectWrap基础

Nan::ObjectWrap是rvagg/nan提供的一个基础类，用于简化C++对象的包装过程。它实际上是Node.js原生node::ObjectWrap的改进版本，提供了更一致的API接口。

核心方法解析

class ObjectWrap {
 public:
  ObjectWrap();
  virtual ~ObjectWrap();

  // 从JavaScript对象中解包出C++对象
  template <class T>
  static inline T* Unwrap(v8::Local<v8::Object> handle);

  // 获取关联的JavaScript对象句柄
  inline v8::Local<v8::Object> handle();

  // 获取持久化句柄引用
  inline Nan::Persistent<v8::Object>& persistent();

 protected:
  // 将C++对象与JavaScript对象关联
  inline void Wrap(v8::Local<v8::Object> handle);

  // 将对象标记为弱引用
  inline void MakeWeak();

  // 增加引用计数，防止被垃圾回收
  virtual void Ref();

  // 减少引用计数，允许被垃圾回收
  virtual void Unref();

  int refs_;  // 引用计数
};

基本使用示例

让我们通过一个简单的例子来理解如何使用Nan::ObjectWrap。

定义C++类

class MyObject : public Nan::ObjectWrap {
 public:
  static NAN_MODULE_INIT(Init) {
    // 创建函数模板
    v8::Local<v8::FunctionTemplate> tpl = Nan::New<v8::FunctionTemplate>(New);
    tpl->SetClassName(Nan::New("MyObject").ToLocalChecked());
    tpl->InstanceTemplate()->SetInternalFieldCount(1);

    // 添加原型方法
    Nan::SetPrototypeMethod(tpl, "getHandle", GetHandle);
    Nan::SetPrototypeMethod(tpl, "getValue", GetValue);

    // 保存构造函数
    constructor().Reset(Nan::GetFunction(tpl).ToLocalChecked());
    Nan::Set(target, Nan::New("MyObject").ToLocalChecked(),
      Nan::GetFunction(tpl).ToLocalChecked());
  }

 private:
  explicit MyObject(double value = 0) : value_(value) {}
  ~MyObject() {}

  // 构造函数实现
  static NAN_METHOD(New) {
    if (info.IsConstructCall()) {
      // 作为构造函数调用
      double value = info[0]->IsUndefined() ? 0 : Nan::To<double>(info[0]).FromJust();
      MyObject *obj = new MyObject(value);
      obj->Wrap(info.This());  // 关键步骤：关联C++对象和JS对象
      info.GetReturnValue().Set(info.This());
    } else {
      // 作为普通函数调用，转换为构造函数调用
      const int argc = 1;
      v8::Local<v8::Value> argv[argc] = {info[0]};
      v8::Local<v8::Function> cons = Nan::New(constructor());
      info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
    }
  }

  // 其他方法实现...
  
  double value_;
};

JavaScript中使用

var obj = new MyObject(5);
console.log(obj.getValue());  // 输出: 5

对象工厂模式

有时我们需要创建对象的工厂函数，而不是直接暴露构造函数。

实现工厂

class MyFactoryObject : public Nan::ObjectWrap {
 public:
  static NAN_METHOD(NewInstance) {
    v8::Local<v8::Function> cons = Nan::New(constructor());
    double value = info[0]->IsNumber() ? Nan::To<double>(info[0]).FromJust() : 0;
    const int argc = 1;
    v8::Local<v8::Value> argv[1] = {Nan::New(value)};
    info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
  }

  // 其他实现...
};

// 模块初始化
NAN_MODULE_INIT(Init) {
  MyFactoryObject::Init(target);
  Nan::Set(target,
    Nan::New<v8::String>("newFactoryObjectInstance").ToLocalChecked(),
    Nan::GetFunction(
      Nan::New<v8::FunctionTemplate>(MyFactoryObject::NewInstance)).ToLocalChecked()
  );
}

JavaScript中使用工厂

var obj = wrappedobjectfactory.newFactoryObjectInstance(10);
console.log(obj.getValue());  // 输出: 10

对象传递与操作

包装后的对象可以在JavaScript函数间传递，也可以在C++中操作。

操作多个包装对象

static NAN_METHOD(Sum) {
  // 获取JavaScript对象
  Nan::MaybeLocal<v8::Object> maybe1 = Nan::To<v8::Object>(info[0]);
  Nan::MaybeLocal<v8::Object> maybe2 = Nan::To<v8::Object>(info[1]);

  if (maybe1.IsEmpty() || maybe2.IsEmpty()) {
    return;  // 返回undefined
  }

  // 解包出C++对象
  MyFactoryObject* obj1 = Nan::ObjectWrap::Unwrap<MyFactoryObject>(maybe1.ToLocalChecked());
  MyFactoryObject* obj2 = Nan::ObjectWrap::Unwrap<MyFactoryObject>(maybe2.ToLocalChecked());

  // 操作C++对象
  info.GetReturnValue().Set(Nan::New<v8::Number>(obj1->value() + obj2->value()));
}

JavaScript中使用

var obj1 = myaddon.newFactoryObjectInstance(5);
var obj2 = myaddon.newFactoryObjectInstance(10);
console.log(myaddon.sum(obj1, obj2));  // 输出: 15

最佳实践与注意事项

1. Holder() vs This():

   • 在方法调用时，优先使用info.Holder()来获取包装对象
   • 在访问器中，如果定义在原型上，应该使用info.This()并验证其有效性

2. 内存管理:

   • 使用Ref()和Unref()来管理对象生命周期
   • 注意不要在析构函数中调用Unref()

3. 错误处理:

   • 在使用Unwrap前，应该验证对象类型
   • 使用Nan::MaybeLocal来处理可能的转换失败

4. 多版本兼容:

   • Nan::ObjectWrap确保在不同Node.js版本中行为一致
   • 避免直接使用node::ObjectWrap

总结

通过rvagg/nan的Nan::ObjectWrap，我们可以轻松地将C++对象暴露给JavaScript环境。本文介绍了基本用法、工厂模式、对象传递等核心概念，并提供了最佳实践建议。掌握这些技术后，开发者可以更高效地开发Node.js原生扩展模块。