DIV CSS 佈局教程網

Node.js 插件(Addon)的正確編寫方式完整教學
編輯:關於JavaScript     

Node.js 在運用 JavaScript 撰寫後端方面表現出色,值得多加嘗試。不過,當我們需要某些無法直接實現、甚至根本無從著手的功能時,能否從 C/C++ 函式庫中引入這類成果呢?答案是肯定的——透過編寫插件(Addon),我們就能在自己的 JavaScript 程式碼中調用其它函式庫的資源。本文將以「為標準 std::string 建立封裝」為例,帶讀者走完整個流程。

介紹

正如 Node.js 官方文件所述,插件是以動態方式連結的共享物件,能把 JavaScript 程式碼與 C/C++ 函式庫接駁起來。這意味著我們可以引用任何來自 C/C++ 函式庫的內容,並透過建立插件將其納入 Node.js。

準備工作

在開始之前,請先確保已備妥後續編譯所需的素材,也就是 node-gyp 及其全部依賴。可用以下命令安裝:

npm install -g node-gyp

在 Unix 系統上,還需要:Python(需 2.7 版本,3.x 無法正常運作)、make,以及一套 C++ 編譯器工具鏈(如 gpp 或 g++)。以 Ubuntu 為例,可用以下命令一次安裝(Python 2.7 通常已預裝):

sudo apt-get install build-essentials

在 Windows 上則需要:Python(2.7.3 版本,3.x 無法正常運作)、微軟 Visual Studio C++ 2010(適用於 XP/Vista)或 Visual Studio C++ 2012 for Windows Desktop(適用於 7/8)。此外,Visual Studio 的 Express 版本也能正常運作。

binding.gyp 文件

此文件由 node-gyp 使用,用來為插件產生合適的 build 文件。我們的範例相當簡單,只需以下內容即可:

{
  "targets": [
    {
      "target_name": "stdstring",
      "sources": [ "addon.cc", "stdstring.cc" ]
    }
  ]
}

其中 target_name 可設為任意名稱,sources 陣列則包含該插件所需的所有原始檔。範例中的 addon.cc 用來容納編譯插件所必需的程式碼,stdstring.cc 則是封裝類的實作。

STDStringWrapper 類

第一步,在 stdstring.h 中定義我們的類。以下是標準的 include guard:

#ifndef STDSTRING_H
#define STDSTRING_H

接著需要納入兩個 header:一個面向 std::string 類,另一個則涵蓋所有與 Node 及 V8 相關的內容。

完成後即可宣告類別。對於所有打算包含在插件中的類,都必須擴充 node::ObjectWrap:

class STDStringWrapper : public node::ObjectWrap {

接著定義 private 屬性:

private:
  std::string* s_;
  explicit STDStringWrapper(std::string s = "");
  ~STDStringWrapper();

除了建構子與解構子,我們還為 std::string 定義一個指標。這是整項技術的核心——為 C/C++ 類定義一個私有指標,並在後續所有方法中透過它進行操作,藉此把 C/C++ 程式碼與 Node 相對接。

接著宣告 constructor 靜態屬性,它將為我們在 V8 中建立的類提供函式:

static v8::Persistent<v8::Function> constructor;

接著需要一個 New 方法,它會被指派給 constructor,由 V8 呼叫以初始化我們的類:

static v8::Handle<v8::Value> New(const v8::Arguments& args);

作用於 V8 的每個函式都必須遵循此慣例:接受指向 v8::Arguments 物件的參考,並回傳一個 v8::Handle<v8::Value>——這正是強型別的 C++ 處理弱型別 JavaScript 的一貫方式。

之後,我們再把另外兩個方法插入物件的原型中:

static v8::Handle<v8::Value> add(const v8::Arguments& args);
static v8::Handle<v8::Value> toString(const v8::Arguments& args);

其中 toString() 讓我們在把物件與普通 JavaScript 字串一起使用時,能取得 s_ 的值,而非 [Object object]。

最後引入初始化方法並關閉 include guard:

public:
  static void Init(v8::Handle<v8::Object> exports);
};
#endif

其中 exports 物件在 JavaScript 模組中的作用等同於 module.exports。

stdstring.cc、建構子與解構子

現在建立 stdstring.cc,先 include 我們的 header:

#include "stdstring.h"

接著為 constructor 定義屬性(因為它是靜態函式):

v8::Persistent<v8::Function> STDStringWrapper::constructor;

服務於類別的建構子會配置 s_ 屬性:

STDStringWrapper::STDStringWrapper(std::string s) {
  s_ = new std::string(s);
}

而解構子則對其進行 delete,以避免記憶體洩漏:

STDStringWrapper::~STDStringWrapper() {
  delete s_;
}

請務必 delete 掉所有以 new 配置的內容,因為每次都可能造成異常,請牢記這一點,或改用共享指標。

Init 方法

此方法由 V8 呼叫,用來初始化我們的類(配置 constructor,並把打算在 JavaScript 中使用的內容安置到 exports 物件):

void STDStringWrapper::Init(v8::Handle<v8::Object> exports) {

首先為 New 方法建立一個函式模板:

  v8::Local<v8::FunctionTemplate> tpl = v8::FunctionTemplate::New(New);

這有點類似 JavaScript 中的 new Function,讓我們得以準備好自己的 JavaScript 類。

接著可依需求為該函式設定名稱(若省略,建構子將處於匿名狀態):

  tpl->SetClassName(v8::String::NewSymbol("STDString"));

我們用 v8::String::NewSymbol() 建立一個用於屬性名稱的特殊字串類型,能為引擎運作節省一點時間。

之後設定類別實例包含多少個欄位:

  tpl->InstanceTemplate()->SetInternalFieldCount(2);

由於我們有 add() 與 toString() 兩個方法,因此設為 2。接著把方法加入函式原型:

  tpl->PrototypeTemplate()->Set(v8::String::NewSymbol("add"), v8::FunctionTemplate::New(add)->GetFunction());
  tpl->PrototypeTemplate()->Set(v8::String::NewSymbol("toString"), v8::FunctionTemplate::New(toString)->GetFunction());

這段程式碼看似龐大,但規律很清晰:透過 tpl->PrototypeTemplate()->Set() 逐一添加方法,並用 v8::String::NewSymbol() 提供名稱與 FunctionTemplate。

最後把建構子安置到 exports 物件中:

  constructor = v8::Persistent<v8::Function>::New(tpl->GetFunction());
  exports->Set(v8::String::NewSymbol("STDString"), constructor);
}

New 方法

接著定義一個與 JavaScript Object.prototype.constructor 效果相同的方法:

v8::Handle<v8::Value> STDStringWrapper::New(const v8::Arguments& args) {

首先為它建立一個 Scope:

  v8::HandleScope scope;

之後可用 args 物件的 IsConstructCall() 檢查該建構子是否能以 new 關鍵字呼叫:

  if (args.IsConstructCall()) {

如果可以,先把參數傳遞給 std::string:

    v8::String::Utf8Value str(args[0]->ToString());
    std::string s(*str);

再把它傳入封裝類的建構子:

    STDStringWrapper* obj = new STDStringWrapper(s);

接著用先前物件的 Wrap() 方法(繼承自 node::ObjectWrap)把它配置給 this:

    obj->Wrap(args.This());

最後回傳這個新建立的物件:

    return args.This();

若函式無法以 new 呼叫,也可直接呼叫建構子。先設定參數計數的常數:

  } else {
    const int argc = 1;

用參數建立一個陣列:

    v8::Local<v8::Value> argv[argc] = { args[0] };

再把 constructor->NewInstance 的結果傳入 scope.Close,讓物件得以在後續發揮作用:

    return scope.Close(constructor->NewInstance(argc, argv));
  }
}

add 方法

接著建立 add 方法,讓使用者能向物件的內部 std::string 追加內容:

v8::Handle<v8::Value> STDStringWrapper::add(const v8::Arguments& args) {

首先建立 Scope,並像之前那樣把參數轉換到 std::string:

  v8::HandleScope scope;
  v8::String::Utf8Value str(args[0]->ToString());
  std::string s(*str);

接著對物件進行拆包(Unwrap),從 this 取得指向物件的指標:

  STDStringWrapper* obj = ObjectWrap::Unwrap<STDStringWrapper>(args.This());

然後存取 s_ 屬性並使用其 append() 方法:

  obj->s_->append(s);

最後回傳 s_ 的目前值(再次使用 scope.Close)。由於 v8::String::New() 只能接受 char pointer,因此需用 obj->s_->c_str() 取得:

  return scope.Close(v8::String::New(obj->s_->c_str()));
}

測試

此時插件資料夾中應已產生一個 build 目錄。接著在插件目錄建立 test.js:

var addon = require('./build/Release/addon');

為物件建立一個新實例:

var test = new addon.STDString('test');

再對它進行操作,例如添加內容或轉為字串:

test.add('!');
console.log('test\'s contents: %s', test);

運行後,控制台應會顯示 test 物件的內容。

結論

希望讀者在讀完本教學後,能把「建立並測試以 C/C++ 函式庫為基礎的客製化 Node.js 插件」視為一項難度不高的任務。運用這種技術,幾乎任何 C/C++ 函式庫都能被引入 Node.js。若想更進一步,還可依需求為插件添加更多功能——std::string 本身就提供了大量方法,正好可作為練習素材。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved