簡介：?來一起為 Node.js 的 add-on 生態(tài)做貢獻(xiàn)吧~

作者 | 吳成忠(昭朗)

這篇文章是由 Chengzhong Wu (@legendecas)，Gabriel Schulhof (@gabrielschulhof) ，Jim Schlight (@jimschlight)，Kevin Eady，Michael Dawson (@mhdawson1)，Nicola Del Gobbo (@NickNaso) 等人編寫的，首發(fā)在 Node.js Medium 博客。

關(guān)于N-API

N-API 為 Node.js 帶來了一個(gè) ABI 穩(wěn)定的 add-on API，簡化了構(gòu)建和開發(fā)支持跨 Node.js 版本的 add-on 的負(fù)擔(dān)。

目前 N-API 的 C++ 封裝 node-addon-api 每周的下載量已經(jīng)超過了 250萬次，并且所有 Node.js LTS（長期支持版本）都已經(jīng)支持了 N-API v3 或者更高版本 ，Node.js 15.x 更已經(jīng)開始支持最新的 N-API v7。所以我們認(rèn)為這是一個(gè)非常好的時(shí)間點(diǎn)來回頭看一看目前 Node.js add-on 的開發(fā)體驗(yàn)。

當(dāng)我們在 2016 年開始投入 N-API 的工作（最開始的提案是在 2016 年 12 月 12 日提出的），我們就知道這會(huì)是一個(gè)非常長期的任務(wù)。Node.js 社區(qū)生態(tài)中已經(jīng)有非常多現(xiàn)存的包，所以這個(gè)遷移過程將會(huì)持續(xù)相當(dāng)長的一段時(shí)間。

不過好消息是，從最初的想法，到現(xiàn)在這段路程我們已經(jīng)走過了非常長的路途。許許多多的困難已經(jīng)由多位 Node.js Collaborator、N-API 團(tuán)隊(duì)和模塊包作者們攻克。目前，N-API 已經(jīng)成為了默認(rèn)、推薦的編寫 Node.js add-on 的方式。

隨著 N-API 的發(fā)展，不斷有新的 API 加入到 N-API 中去來滿足 Node.js 模塊包作者將他們的庫向 N-API 遷移中提出新需求，當(dāng)然這個(gè)過程也按照我們預(yù)先的設(shè)計(jì) N-API 一直保持著穩(wěn)定、向前兼容性。

我們也非常高興地看到這些模塊包作者們的積極反饋，比如?https://twitter.com/mafintosh/status/1256180505210433541

不多說，我們先來看看過去幾年被添加到 N-API 中的新特性吧。

新特性

越來越多的開發(fā)者們開始使用 N-API 與 node-addon-api 開發(fā) Node.js add-on，我們也不斷地為 N-API 和 node-addon-api 添加新的關(guān)鍵特性和改進(jìn) add-on 開發(fā)體驗(yàn)。

這些改進(jìn)可以分為 3 個(gè)主要的類別，我們下文將一一介紹。

多線程與異步編程

隨著 Node.js 的使用在開發(fā)者群體中越來越顯著，需要與 OS 接口、異步事件打交道的需求也越來越旺盛。Node.js 是一個(gè) JavaScript 單線程模型的實(shí)現(xiàn)，一個(gè) Node.js 環(huán)境只會(huì)有一個(gè)主線程可以訪問 JavaScript 值。

因此，在主線程執(zhí)行重 CPU 的任務(wù)就會(huì)導(dǎo)致 JavaScript 程序被阻塞，導(dǎo)致事件與回調(diào)都堆積在事件隊(duì)列中。為了改進(jìn)程序的跨線程數(shù)據(jù)完整性的開發(fā)體驗(yàn)，我們收集了非常多的真實(shí)案例的需求，在 N-API 和 N-API 的 C++ 封裝 node-addon-api 中都帶來了多種機(jī)制來解決工作線程回調(diào)回 JavaScript 線程的問題。根據(jù)使用場景，可以分為：

• AsyncWorker，提供單向、單次的回調(diào)任務(wù)封裝，可以通知 JavaScript 這個(gè)任務(wù)的最終執(zhí)行結(jié)果或者異常信息；
• AsyncProgressWorker，與 AsyncWorker 類似，提供單向、單次的回調(diào)任務(wù)封裝，不過增加了向 JavaScript 異步傳遞進(jìn)度信息的機(jī)制；
• Thread-safe functions，提供了從任意線程、任意數(shù)量的線程、任意時(shí)間點(diǎn)向 Node.js JavaScript 線程回調(diào)的機(jī)制。

多 Node.js 上下文支持

Node.js 近期最讓人興奮的特性之一就是 [worker_threads]，它提供了一個(gè)完整的、但是獨(dú)立于 Node.js 主 JavaScript 線程的并發(fā)執(zhí)行的 Node.js JavaScript 執(zhí)行線程。這也意味著 Node.js 的 add-on 也同樣可以在這些 worker 線程中隨著這些 worker 的啟動(dòng)與銷毀被多次加載、卸載。

不過因?yàn)檫@些同一個(gè)進(jìn)程中的 worker 線程是共享了同一個(gè)內(nèi)存空間的，多個(gè) add-on 的實(shí)例必須考慮到多個(gè) worker 線程的同時(shí)存在的可能性。另外，每一個(gè) Node.js 進(jìn)程只會(huì)加載了一次這些 add-on 的動(dòng)態(tài)庫，這意味著這些 add-on 線程不安全的全局屬性（比如全局靜態(tài)變量）可以被多個(gè)線程同時(shí)訪問，也就不能再這么簡單粗暴地存儲了。

類似的，C++ 類的靜態(tài)數(shù)據(jù)成員也是通過線程不安全的方式存儲的，所以這個(gè)方式也需要被避免。另外，其實(shí)對于 add-on 來說，Node.js 也不保證單個(gè)線程只會(huì)用來執(zhí)行一個(gè) worker，所以 thread-local 也應(yīng)該被避免。

在 N-API v6 中，我們?yōu)槊恳粋€(gè) Node.js 實(shí)例（主線程 JavaScript 實(shí)例、worker 實(shí)例等）都引入了一個(gè)用來給 add-on 使用的存儲空間。這樣，add-on 在一個(gè)進(jìn)程中就可以獲得對于單個(gè) Node.js 實(shí)例唯一的存儲空間了。同時(shí)我們也提供了一些輔助方法來幫助 add-on 開始使用這個(gè)特性：

• NAPI_MODULE_INIT()?宏，會(huì)將 add-on 標(biāo)記為可以被 Node.js 在同一個(gè)進(jìn)程中可以多次加載、卸載的模塊。
• napi_get_instance_data()?和?napi_set_instance_data()?用來安全地訪問單個(gè) Node.js 實(shí)例給 add-on 創(chuàng)建的全局唯一存儲空間；
• node-addon-api 還提供了?Addon<T>?類，這個(gè)類包裝了上面說所的方法，以 C++ 友好的方式封裝了這個(gè)給予 add-on 可以在不同的 worker 線程中使用的存儲空間。因此，add-on 開發(fā)者可以將 add-on 的數(shù)據(jù)比如全局變量通過?Addon<T>?來存儲并創(chuàng)建，而 Node.js 則會(huì)負(fù)責(zé)在當(dāng)前線程使用這個(gè) add-on 的時(shí)候創(chuàng)建這片空間。

其他輔助函數(shù)

除了以上幾個(gè)重要功能之外，我們也發(fā)現(xiàn)了許多在維護(hù) Node.js add-on 的過程中經(jīng)常會(huì)使用到的類型方法與函數(shù)，包括：

• Date 對象；
• BigInts；
• 從 JavaScript 對象上獲取任意鍵（如 Symbol 等）；
• 將 Add-on 創(chuàng)建的 ArrayBuffer 底層存儲從 ArrayBuffer 上脫離；

構(gòu)建

構(gòu)建工作流對于 Node.js add-on 維護(hù)者與 add-on 使用者來說是非常重要的一個(gè)環(huán)節(jié)，也是N-API 團(tuán)隊(duì)其中一個(gè)工作重心，比如 CMake.js, node-pre-gyp 和 prebuild。

曾經(jīng) Node.js add-on 只能使用 node-gyp 來構(gòu)建。對于一些已經(jīng)在使用 CMake 的庫來說，CMake.js 就是除了 node-gyp 依賴用來構(gòu)建 add-on 的一個(gè)非常吸引人的選項(xiàng)。我們也已經(jīng)發(fā)布了一個(gè)使用 CMake 構(gòu)建 add-on 的例子。

其他關(guān)于如何將 CMake.js 與 N-API add-on 一起使用的詳細(xì)信息可以在 N-API Resource 獲取到。

開發(fā) Node.js add-on 之后一個(gè)重要的現(xiàn)實(shí)問題就是在 npm install 時(shí)，add-on 的 C/C++ 代碼必須在本地編譯、鏈接。這個(gè)編譯過程需要本地安裝有一個(gè)可以正常使用的 C/C++ 工具鏈。而這個(gè)依賴通常會(huì)成為沒有安裝這些工具鏈的 add-on 用戶使用這個(gè) add-on 的一個(gè)阻礙。現(xiàn)行的方案對于這個(gè)問題一般都是預(yù)先構(gòu)建二進(jìn)制包，然后在安裝時(shí)直接下載這些預(yù)先構(gòu)建的包。

有許多工具可以用來預(yù)先構(gòu)建二進(jìn)制包。node-pre-gyp 通常會(huì)將構(gòu)建出來的二進(jìn)制包上傳到 AWS S3。prebuild 也類似，不過是將包上傳到 GitHub Release。

prebuildify 則是另外一個(gè)可選項(xiàng)。而 prebuildify 相比于上述的工具來說，優(yōu)點(diǎn)在于在 npm install 安裝好時(shí)，本地就已經(jīng)有這些二進(jìn)制包了，而不需要再次從第三方服務(wù)上下載。雖然安裝的 npm 包可能會(huì)更大，不過在實(shí)際實(shí)踐中因?yàn)椴恍枰俅螐?AWS 或者 GitHub 上下載，整個(gè)安裝過程會(huì)相對更加快速。

開始上手

我們已經(jīng)在 GitHub 上準(zhǔn)備了非常多的 node-addon-examples 來給開發(fā)者快速了解常見場景該如何使用 N-API 和 node-addon-api 來開發(fā) Node.js add-on。這個(gè)倉庫的根目錄包含了許多的文件夾，這些文件夾就代表了不同的使用場景，比如從簡單的 Hello World add-on，到復(fù)雜的多線程 add-on。每一個(gè)樣例目錄會(huì)包含 3 個(gè)子目錄，分別代表了傳統(tǒng)的 NAN，N-API，和 node-addon-api 開發(fā) add-on 的例子。我們可以直接運(yùn)行下面的命令，立刻從 Hello World 的例子開始使用 node-addon-api：

$ git clone https://github.com/nodejs/node-addon-examples.git $ cd node-addon-examples/1_hello_world/node-addon-api/ $ npm i $ node .

另一個(gè)重要的資源就是 N-API Resource。這個(gè)網(wǎng)站包含了開發(fā)、構(gòu)建 Node.js add-on 的從入門到深入的許多信息與資料，比如

• 上手所需的工具；
• 從 NAN 向 N-API 的遷移導(dǎo)引；
• 不同構(gòu)建系統(tǒng)的對比（node-gyp，CMake 等等）；
• 多 Node.js 上下文支持和線程安全。

結(jié)語

從 Node.js 誕生之初，Node.js 就支持通過 C/C++ 代碼來給 JavaScript 暴露更多的特性接口。隨著時(shí)間積累，我們也認(rèn)識到實(shí)現(xiàn)、維護(hù)、分發(fā)這些 add-on 一直存在許許多多的難點(diǎn)。而 N-API 就被 add-on 維護(hù)者們認(rèn)為是解決這些難點(diǎn)的一個(gè)非常核心的領(lǐng)域。所以整個(gè)N-API 團(tuán)隊(duì)和社區(qū)都開始為 Node.js 核心建立起這樣一套 ABI 穩(wěn)定的 add-on API。

而代表了 N-API 的這些 C API 現(xiàn)在已經(jīng)是每一個(gè) Node.js 發(fā)布版本的一部分，并且我們也有了可以通過 npm 安裝的 node-addon-api 來提供這些 C API 的 C++ 封裝。N-API 在誕生之初，就是以在不同 Node.js 版本之間，甚至是 Major 版本之間保證 ABI 與 API 兼容性為目標(biāo)，而這也已經(jīng)可以證明能夠提供更多額外的好處：

• 我們不再需要在切換 Node.js 大版本之后重新編譯 add-on 模塊；
• 我們可以在除了使用 V8 作為 JavaScript 引擎的 Node.js 之外的運(yùn)行環(huán)境實(shí)現(xiàn) N-API，也意味著這些為 Node.js 開發(fā)的 add-on 無需修改任何代碼即可兼容這些運(yùn)行環(huán)境，比如 Babylon Native，IoT.js 和 Electron。
• N-API 是單純的 C API，這意味著我們可以使用 C/C++ 之外的語言、運(yùn)行時(shí)開發(fā) Node.js add-on，比如 Go 或者是 Rust。

N-API 從 Node.js v8.0.0 開始以實(shí)驗(yàn)性功能發(fā)布到現(xiàn)在，雖然廣泛應(yīng)用的過程比較緩慢，但是模塊開發(fā)者們也不斷地給我們提交反饋與貢獻(xiàn)，這也幫助我們不斷地增加新特性和開發(fā)新的工具來幫助開發(fā)者們構(gòu)建一個(gè)更好的 add-on 生態(tài)。

今天，N-API 在 add-on 的開發(fā)中使用已經(jīng)非常廣泛。比如一些使用非常多的 add-on 模塊都已經(jīng)遷移至基于 N-API 開發(fā)：

• sharp (每周 ~900k 下載量)
• bcrypt (每周 ~500k 下載量)
• sqlite3 (每周 ~300k 下載量)

在過去的幾年中，N-API 獲得了非常多的改進(jìn)。而對于 add-on 開發(fā)者與用戶來說，這也給他們帶來了接近于原生 JavaScript 模塊的開發(fā)、使用體驗(yàn)。

開始貢獻(xiàn)

我們在持續(xù)不斷地改進(jìn) N-API 和 Node.js 的 add-on 生態(tài)，但是我們也一直非常需要幫助。你可以在以下途徑在多種場景幫助 N-API 做的更好：

• 將你的 add-on 遷移到 N-API；
• 幫助你的應(yīng)用依賴的 add-on 遷移到 N-API；
• 為 N-API 提出、實(shí)現(xiàn)新的特性；
• 為 node-addon-api 提出、實(shí)現(xiàn)新的基于 N-API 的特性；
• 為 node-addon-api 修復(fù)問題、增加測試用例；
• 為 node-addon-examples 修復(fù)問題、增加測試用例；

原文鏈接
本文為阿里云原創(chuàng)內(nèi)容，未經(jīng)允許不得轉(zhuǎn)載。

總結(jié)

以上是生活随笔為你收集整理的如何开发 Node.js Native Add-on？的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。