張志成

誠邁科技高級技術專家

NAPI是什么

NAPI的概念源自Nodejs，為了實現javascript腳本與C++庫之間的相互調用，Nodejs對V8引擎的api做了一層封裝，稱為NAPI。可以在Nodejs官網（https://nodejs.org/dist/latest-v20.x/docs/api/n-api.html）上查看各種NAPI接口定義說明。

可以看到，NAPI接口本身是C++語言實現的，這些接口可以幫助C++代碼創建JS變量，或訪問JavaScript運行環境中的JS變量與方法。

OpenHarmony中的NAPI

OpenAtom?OpenHarmony（以下簡稱“OpenHarmony”）應用層基于javascript語言開發，而系統框架層則基于C++語言。它們之間需要一個橋梁來實現兩種語言代碼之間的相互調用，這個橋梁就是NAPI。

這里可能有的小伙伴有疑問了：OpenHarmony的NAPI和NodeJs的NAPI是一回事嗎？應該說，OpenHarmony系統沿用了NAPI的接口定義形式，但每個接口的內部實現都進行了重寫。這是因為NAPI接口的本質是幫助C++程序去跟Javascript引擎交互，因此對于不同的引擎需要有不同的實現方式。當用戶調用了NAPI接口?napi_create_int64()，?對于Nodejs而言，它會去訪問V8引擎的api創建一個js的數字變量，而對于OpenHarmony，則是去訪問ArkUI框架自己的js引擎(ArkNativeEngine)。在OpenHarmony源碼中搜索?napi_create_int64()?方法，你會得到一份頭文件定義：third_party\node\src\js_native_api.h以及兩份不同的實現代碼：third_party\node\src\js_native_api_v8.ccfoundation\arkui\napi\native_engine\native_api.cppnative_api.cpp是OpenHarmony版本的NAPI實現，想了解內部細節的可以從這里入手：

創建一個簡單的NAPI工程

可以通過DevEco?Studio的Native?C++模板創建一個包含簡單NAPI?實現的樣例工程。

該工程自帶一個hello.cpp，實現了一個能夠被javascript代碼調用的add()方法。

下面我們就基于這個簡單的例子，探究一下NAPI框架的實現原理。

應用如何調用NAPI接口

應用代碼導入對應的so庫后，就可以調用該庫實現的接口。

這里我們注意到，導入日志庫時使用的名稱是"@ohos.hilog"，應用代碼如果寫成??import?hilog?from?'libhilog.z.so'??其實也是可以成功導入的。實際上，ArkUI在運行時會將@ohos.hilog轉換為libhilog.z.so，然后到?/system/lib/module/?目錄下查找此庫并加載。系統實現的NAPI庫都放在/system/lib/module/目錄下，類似的：@ohos.wifiManager對應的是?/system/lib/module/libwifimanager.z.so；@ohos.deviceInfo?對應的是?/system/lib//module/libdeviceinfo.z.so

除了系統自帶的NAPI庫，應用也可以用C++開發自己的NAPI庫。上面例子中?import?testNapi?from?'libentry.so'?導入的就是應用自己實現的。應用開發的NAPI庫會隨著應用工程一起編譯打包到hap文件中，最終部署到/data目錄每個應用自己的文件夾下。

NAPI庫的導入原理

我們知道，應用的javascript代碼是由ArkUI的JS引擎解釋執行的。當JS引擎解讀?import?hilog?from?'@ohos.hilog';?這行代碼時，會通過dlopen()?將對應的libhilog.z.so加載到應用進程中。這一切是怎么做到的呢？每個應用進程在初始化時，都會創建一個引擎實例?ArkNativeEngineImpl，我們來看一下它的構造函數foundation\arkui\napi\native_engine\impl\ark\ark_native_engine_impl.cpp

也就是說，每個應用進程的JS引擎中，都注冊了一個"requireNapi"函數，當應用調用此方法時，JS引擎就會通過NAPI框架的moduleManager類去處理so庫的加載。moduleManager內部最終是找到了/system/lib/module下對應的so文件，并通過dlopen()的方式加載到應用進程中。想了解細節的小伙伴可以讀一下NativeModuleManager::LoadNativeModule()方法的內部實現。

這里可能會有個疑問：應用的javascript代碼中并沒有寫什么"requireNapi"的代碼，只有import?xxx，怎么觸發的導入處理函數？答案要到編譯后的js代碼中尋找。我們解開編譯后的hap包，找到ets文件對應的js文件：

可以看到，index.ets被編譯成index.js后，import關鍵字也被轉為了"requireNapi"，這樣JS引擎在執行這行代碼時，就會去調用注冊的導入處理函數了。

C++庫如何實現JS方法

前面解決了JS?導C++庫的問題，下一步就是JS如何調用C++庫里的方法了。先說結論：一個C++方法能否被應用調用，取決與C++代碼有沒有將這個方法注冊到JS引擎。

我們來看看hello.cpp是如何注冊add方法的：

我們可以從下往上看這段代碼：首先是?RegisterEntryModule(void)?方法。這是C++向JS引擎進行NAPI模塊與方法注冊的起始代碼。注意這個方法前面有個編譯修飾符?"__attribute__((constructor))"，它的作用是指導C++代碼的編譯，使得當so庫被加載到應用進程中時，RegisterEntryModule(void)?方法就會被自動調用到。該方法通過NAPI接口napi_module_register()?向JS引擎注冊了一個?napi_module。

然后是Init()方法。該方法實現了Add方法的注冊。也就是告訴JS引擎，將JS符號"add"?與C++方法"Add"?進行關聯映射。這樣后續當JS引擎解釋執行javascript代碼?"testNapi.add(2,?3)"時，就會找到C++?Add()方法的函數地址并調用。如下圖所示：

方法關聯調用的問題也解決了，最后就是JS運行環境與C++運行環境的相互切換了。當C++的Add方法被JS引擎調用到后，引擎會將javascript下發的參數變量傳遞給C++。所有從JS運行環境傳遞過來的變量都是用napi_value類型來表示的。需要通過NAPI接口轉為C++語言的變量類型。詳見下圖每行代碼的注釋：

napi_value不是一個具體的類型，它類似于void*，表示的是JS變量在JS引擎內部存儲區內的地址。需要通過對應的NAPI方法實現，例如：napi_get_value_int32()??---?js變量轉為c++整形napi_get_value_string_utf8()?---?js變量轉為c++字符串napi_get_value_bool()?---?js變量轉為c++布爾值

這些接口的具體用法和使用場景，可以參考NodeJs官方文檔（https://nodejs.org/dist/latest-v20.x/docs/api/n-api.html）

C++程序鏈接NAPI庫

OpenHarmony的NAPI接口實現都封裝在libace_napi.z.so中，C++程序編譯時需鏈接此庫。對于DevEco?Studio應用開發的cpp代碼，在對應的CMakeLists.txt中鏈接。該庫文件在SDK目錄下可以找到。

對于設備側開發，系統框架中的C++程序，則通過BUILD.gn文件定義依賴關系。

總結

NAPI是JavaScript與C++交互的橋梁。在OpenHarmony中，Javascript代碼在運行時由ArkUI的JS引擎解釋執行，C++代碼則通過NAPI接口訪問JS引擎中的Javascript上下文，從而實現與JS變量、方法之間的相互調用。

參考鏈接

以下是源碼倉庫地址

arkui_napi: Development framework for extending the JS Native Module | 原生模塊擴展開發框架

third_party_node: Third-party open-source software node | 三方開源軟件node