如何基于 Napi-rs 打造 Rust 前端工具鏈?
大家好,我是三元同學(xué)。
我們知道,隨著 SWC、Rspack 等 Rust 前端工具鏈的出現(xiàn),Rust 逐漸成為了前端基建的重要一環(huán)。作為一門(mén)系統(tǒng)級(jí)別的語(yǔ)言,Rust 可以編譯出高性能的二進(jìn)制文件,并且相比于 Node.js 可以做到高度地并發(fā),從而讓前端工具鏈的性能達(dá)到了一個(gè)新的高度。而在這背后,你有沒(méi)有想過(guò),Rust 是如何和 Node.js 進(jìn)行交互的呢?
答案就是 napi-rs[1]。這個(gè)庫(kù)可以說(shuō)是 Rust 前端工具鏈的基石,搭建了 Node.js 和 Rust 之間語(yǔ)言通信的橋梁。在這篇文章中,我們將會(huì)使用 napi-rs 來(lái)編寫(xiě)一個(gè) Rust 的前端工具,來(lái)感受一下 Rust 和 Node.js 中間的交互,最終將這個(gè)工具發(fā)布到 npm 上,當(dāng)然也會(huì)分享一些我的實(shí)戰(zhàn)經(jīng)驗(yàn)。
前置環(huán)境
在開(kāi)始之前,我們需要先安裝好 Rust 的開(kāi)發(fā)環(huán)境。Rust 的安裝可以參考 Rust 官網(wǎng)[2],安裝完成之后,我們可以通過(guò)以下命令來(lái)檢查環(huán)境是否安裝成功:
$ rustc --version
在安裝完成之后,Rust 會(huì)自動(dòng)安裝 Cargo,這是 Rust 的包管理工具,類(lèi)似于 Node.js 中的 npm。
創(chuàng)建項(xiàng)目
在安裝好 Rust 環(huán)境之后,我們就可以開(kāi)始創(chuàng)建項(xiàng)目了。我們可以使用 napi-rs 官方腳手架,首先通過(guò)以下命令安裝腳手架:
yarn global add @napi-rs/cli
# 或者
npm install -g @napi-rs/cli
# 或者
pnpm add -g @napi-rs/cli
然后通過(guò)以下命令創(chuàng)建項(xiàng)目:
napi new
先輸入項(xiàng)目的名字,建議加上 scope(比如 @islandjs/napi-rs-example),這是因?yàn)槲覀冏罱K會(huì)將不同平臺(tái)的二進(jìn)制產(chǎn)物發(fā)布到 npm 上,而一旦這些包不在同一個(gè) scope,就可能會(huì)觸發(fā) npm 的 spam detection(垃圾包檢測(cè)),導(dǎo)致發(fā)布失敗。
你需要在 npm 上創(chuàng)建一個(gè) scope,比如 @islandjs,然后將這個(gè) scope 添加到你的 npm 賬號(hào)上,具體可以參考 npm 官方文檔[3]。
napi new
? Package name: (The name filed in your package.json)
然后選擇目錄名:
napi new
? Package name: (The name filed in your package.json) @napi-rs/cool
? Dir name: (cool)
下一步是選擇你想支持哪個(gè)平臺(tái)。如果想要支持所有平臺(tái),可以按 A 全選,然后按 enter:
napi new
? Package name: (The name filed in your package.json) @napi-rs/cool
? Dir name: cool
? Choose targets you want to support aarch64-apple-darwin, aarch64-linux-android, aarch64-unknown-linux-gnu
, aarch64-unknown-linux-musl, aarch64-pc-windows-msvc, armv7-unknown-linux-gnueabihf, x86_64-apple-darwin,
x86_64-pc-windows-msvc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl, x86_64-unknown-freebsd, i686-p
c-windows-msvc, armv7-linux-androideabi
? Enable github actions? (Y/n)
下一步是是否啟用 Github Actions,由于我們后續(xù)需要將其發(fā)布到 npm 上,所以這里選擇 Y。
接下來(lái) napi-rs 會(huì)自動(dòng)幫助我們安裝好項(xiàng)目的依賴(lài),這樣我們就完成了項(xiàng)目的初始化。
目錄結(jié)構(gòu)說(shuō)明
在項(xiàng)目初始化完成之后,我們可以看到項(xiàng)目的目錄結(jié)構(gòu)如下:
.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── __test__
│ └── index.spec.mjs
├── build.rs
├── index.d.ts
├── index.js
├── npm
│ ├── darwin-arm64
│ │ ├── README.md
│ │ └── package.json
│ ├── darwin-x64
│ │ ├── README.md
│ │ └── package.json
│ ├── linux-x64-gnu
│ │ ├── README.md
│ │ └── package.json
│ └── win32-x64-msvc
│ ├── README.md
│ └── package.json
├── package.json
├── rustfmt.toml
├── src
│ └── lib.rs
├── tutorial.md
└── yarn.lock
你需要關(guān)心的目錄和文件主要有下面幾個(gè):
- src: 這個(gè)目錄下是 Rust 代碼,我們的核心邏輯都會(huì)在這里實(shí)現(xiàn)。
- index.js: 這個(gè)文件是我們的入口文件,也就是說(shuō),外部調(diào)用我們的包的時(shí)候,實(shí)際上是調(diào)用了這個(gè)文件。
- build.rs: napi-rs 會(huì)在編譯的時(shí)候自動(dòng)調(diào)用這個(gè)腳本文件,用來(lái)生成一些編譯時(shí)需要的代碼。
- npm: 這個(gè)目錄下存放我們的二進(jìn)制文件,napi-rs 會(huì)在 GitHub Actions 上自動(dòng)幫我們編譯出不同平臺(tái)的二進(jìn)制文件,并且將其放在這個(gè)目錄下。這些平臺(tái)在初始化項(xiàng)目的時(shí)候我們已經(jīng)選擇好了。
當(dāng)然,還有 .github 目錄,這個(gè)目錄下存放的是 GitHub Actions 的配置文件,我們可以在這里配置一些自動(dòng)化的流程,比如自動(dòng)編譯二進(jìn)制文件、自動(dòng)發(fā)布到 npm 等等,這部分的流程配置代碼 napi-rs 腳手架已經(jīng)幫我們寫(xiě)好了,無(wú)需修改。
內(nèi)部調(diào)用機(jī)制
在完成項(xiàng)目的初始化之后,我們通過(guò)以下命令來(lái)編譯項(xiàng)目:
yarn build
這個(gè)命令會(huì)自動(dòng)調(diào)用 build.rs 腳本,生成一些編譯時(shí)需要的代碼,然后再調(diào)用 cargo build 來(lái)編譯 Rust 代碼,最終會(huì)將編譯產(chǎn)物(.node 結(jié)尾的文件)放在項(xiàng)目根目錄下。我使用的是 M1 Mac,所以編譯出來(lái)的文件是 napi-rs-example.darwin-arm64.node。
接下來(lái)我們來(lái)分析一下 index.js 文件,這個(gè)文件是我們的入口文件,也就是說(shuō),外部調(diào)用我們的包的時(shí)候,實(shí)際上是調(diào)用了這個(gè)文件。簡(jiǎn)化后的邏輯如下:
switch (platform) {
case "android":
// ...
break;
case "win32":
// ...
break;
case "darwin":
switch (arch) {
case "x64":
// 本地直接使用根目錄下 `napi-rs-example.linux-arm64-gnu.node`
// 發(fā)布時(shí),這個(gè) .node 文件會(huì)被 `@islandjs/napi-rs-example-darwin-arm64` 這個(gè)包發(fā)布到 npm 上
localFileExisted = existsSync(
join(__dirname, "napi-rs-example.darwin-arm64.node")
);
try {
if (localFileExisted) {
nativeBinding = require("./napi-rs-example.darwin-arm64.node");
} else {
nativeBinding = require("@islandjs/napi-rs-example-darwin-arm64");
}
} catch (e) {
loadError = e;
}
break;
}
break;
case "freebsd":
// ...
break;
case "linux":
switch (arch) {
case "x64":
// ...
break;
case "arm64":
// ...
case "arm":
// ...
break;
default:
throw new Error(`Unsupported architecture on Linux: ${arch}`);
}
break;
default:
throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`);
}
const { sum } = nativeBinding;
module.exports.sum = sum;
這個(gè)入口會(huì)根據(jù)操作系統(tǒng)和 CPU 架構(gòu)來(lái)加載不同的二進(jìn)制文件,值得注意的是,本地開(kāi)發(fā)階段和發(fā)布到 npm 后的調(diào)用策略是不一樣的:
- 本地開(kāi)發(fā)階段,當(dāng)你執(zhí)行 yarn build 時(shí),會(huì)直接使用根目錄下的二進(jìn)制文件,也就是 napi-rs-example.darwin-arm64.node,這個(gè)文件是通過(guò) cargo build 生成的。
- 發(fā)布到 npm 后,當(dāng)用戶(hù)執(zhí)行 yarn add @islandjs/napi-rs-example 時(shí),會(huì)自動(dòng)下載 @islandjs/napi-rs-example-darwin-arm64 這個(gè)包,這個(gè)包里面包含了編譯好的二進(jìn)制文件,也就是 napi-rs-example.darwin-arm64.node。這時(shí)候入口文件會(huì)去加載這個(gè)包里面的二進(jìn)制文件。
你可能會(huì)問(wèn)了,在本地 yarn build 之后,并沒(méi)有發(fā)現(xiàn) npm 目錄下有 .node 產(chǎn)物呀,這樣發(fā)布出去豈不是沒(méi)有產(chǎn)物了?
不用擔(dān)心,在 GitHub 腳本中,napi-rs 會(huì)自動(dòng)執(zhí)行編譯和產(chǎn)物移動(dòng)的操作,將所有的 .node 文件移動(dòng)到 npm 目錄下對(duì)應(yīng)平臺(tái)的子目錄中,從而最終能夠保證發(fā)布到 npm 后,用戶(hù)能夠正常使用。GitHub CI 總體流程如下:
最后,index.js 的調(diào)用邏輯可以簡(jiǎn)化為下面這張圖:
編寫(xiě) Rust 側(cè)代碼
接下來(lái)我們把目光轉(zhuǎn)移到 Rust 側(cè),我們的核心邏輯都會(huì)在這里實(shí)現(xiàn)。在 src/lib.rs 中,我們可以看到這樣一段代碼:
#[napi]
pub fn sum(a: i32, b: i32) -> i32 {
a + b
}
通過(guò) #[napi] 宏,我們可以將 Rust 函數(shù)暴露給 JavaScript 使用。這個(gè)宏會(huì)自動(dòng)幫我們生成一些代碼,使得我們的 Rust 函數(shù)能夠被 JavaScript 調(diào)用。
在執(zhí)行 yarn build 之后,我們會(huì)發(fā)現(xiàn)根目錄增加了index.d.ts,也就是說(shuō),napi-rs 已經(jīng)幫我們生成了類(lèi)型聲明文件,類(lèi)型文件的內(nèi)容如下:
export function sum(a: number, b: number): number;
可以看到,Rust 中的 i32 類(lèi)型被轉(zhuǎn)換成了 JavaScript 中的 number 類(lèi)型。而對(duì)于其它的諸多數(shù)據(jù)類(lèi)型,napi-rs 也都做了相應(yīng)的轉(zhuǎn)換,具體可以參考官方文檔[4]。
下面我們以幾個(gè)典型的例子來(lái)實(shí)操一下。
1、傳遞字符串
在 lib.rs 中添加如下的代碼:
#[napi]
pub fn concat_str(a: String, b: String) -> String {
format!("{}{}", a, b)
}
執(zhí)行 yarn build,我們發(fā)現(xiàn) index.js 多出了 concatStr 方法,這個(gè)方法就是我們剛剛在 Rust 中定義的方法,只不過(guò)在 JavaScript 中,方法名被自動(dòng)轉(zhuǎn)換成了駝峰式命名。并且你也能發(fā)現(xiàn)類(lèi)型聲明文件也被更新了,內(nèi)容如下:
export function sum(a: number, b: number): number;
export function concatStr(a: string, b: string): string;
然后我們?cè)?nbsp;__test__/index.spec.mjs 中增加對(duì)應(yīng)的測(cè)試代碼:
import test from "ava";
import { sum, concatStr } from "../index.js";
test("sum from native", (t) => {
t.is(sum(1, 2), 3);
});
// 增加測(cè)試
test("concatStr from native", (t) => {
t.is(concatStr("Hello", "World"), "HelloWorld");
});
執(zhí)行 yarn test,測(cè)試通過(guò)。
2、傳遞對(duì)象
在 lib.rs 中添加如下的代碼:
#[napi]
pub fn get_options(options: ToolOptions) -> ToolOptions {
println!("id: {}, name: {}", options.id, options.name);
options
}
執(zhí)行 yarn build,我們發(fā)現(xiàn) index.js 多出了 getOptions 方法,我們還是在 __test__/index.spec.mjs 中增加對(duì)應(yīng)的測(cè)試代碼:
import { getOptions } from "../index.js";
test("getOptions from native", (t) => {
const options = {
id: 1,
name: "napi-rs",
};
t.deepEqual(getOptions(options)).toEqual(options);
});
3、導(dǎo)出為異步函數(shù)
默認(rèn)情況下,napi-rs 會(huì)將 Rust 函數(shù)導(dǎo)出為同步函數(shù),如果我們想要導(dǎo)出異步函數(shù)給 Node.js 側(cè)使用,可以通過(guò)下面的方式來(lái)實(shí)現(xiàn)。
我們?cè)?nbsp;lib.rs 中添加如下的代碼:
use napi::{Task, Env, Result, JsNumber};
struct AsyncFib {
input: u32,
}
impl Task for AsyncFib {
type Output = u32;
type JsValue = JsNumber;
fn compute(&mut self) -> Result<Self::Output> {
Ok(fib(self.input))
}
fn resolve(&mut self, env: Env, output: u32) -> Result<Self::JsValue> {
env.create_uint32(output)
}
}
pub fn fib(n: u32) -> u32 {
match n {
0 | 1 => n,
_ => fib(n - 1) + fib(n - 2),
}
}
// 指定 JS 側(cè)的返回值類(lèi)型為 Promise<number>
#[napi(ts_return_type="Promise<string>")]
fn async_fib(input: u32) -> AsyncTask<AsyncFib> {
AsyncTask::new(AsyncFib { input })
}
要返回一個(gè)異步的函數(shù),我們需要實(shí)現(xiàn) Task trait,這個(gè) trait 有兩個(gè)關(guān)聯(lián)類(lèi)型,Output 和 JsValue,分別表示 Rust 函數(shù)的返回值類(lèi)型和 JavaScript 中對(duì)應(yīng)的類(lèi)型。在 compute 方法中,我們實(shí)現(xiàn)了具體的計(jì)算邏輯,而在 resolve 方法中,我們將計(jì)算結(jié)果轉(zhuǎn)換成了 JavaScript 中的 JsNumber 類(lèi)型。然后我們?cè)?nbsp;async_fib 函數(shù)中,通過(guò) AsyncTask::new 來(lái)創(chuàng)建一個(gè)異步任務(wù),這個(gè)函數(shù)的返回值類(lèi)型是 AsyncTask<AsyncFib>,這個(gè)類(lèi)型會(huì)被 napi-rs 自動(dòng)轉(zhuǎn)換成 JavaScript 中的 Promise 類(lèi)型。
最后導(dǎo)出對(duì)應(yīng)的類(lèi)型聲明如下:
export function asyncFib(input: number): Promise<number>;
我們?cè)?nbsp;__test__/index.spec.mjs 中增加對(duì)應(yīng)的測(cè)試代碼:
import { asyncFib } from "../index.js";
test("asyncFib from native", async (t) => {
t.is(await asyncFib(10), 55);
});
4、把 JS 函數(shù)放到 Rust 中執(zhí)行
還有一種比較常見(jiàn)的場(chǎng)景,就是我們需要把 JavaScript 中的函數(shù)傳遞到 Rust 中執(zhí)行,這個(gè)時(shí)候我們可以使用 napi-rs 中的 ThreadSafeFunction 來(lái)實(shí)現(xiàn)。
我們?cè)?nbsp;lib.rs 中添加如下的代碼:
use std::thread;
use napi::{
bindgen_prelude::*,
threadsafe_function::{ErrorStrategy, ThreadsafeFunction, ThreadsafeFunctionCallMode},
};
// 強(qiáng)制指定參數(shù)類(lèi)型
#[napi(ts_args_type = "callback: (err: null | Error, result: number) => void")]
pub fn call_threadsafe_function(callback: JsFunction) -> Result<()> {
let tsfn: ThreadsafeFunction<u32, ErrorStrategy::CalleeHandled> = callback
// ctx.value 即 Rust 調(diào)用 JS 函數(shù)時(shí)傳遞的入?yún)?,封裝成 Vec 傳遞給 JS 函數(shù)
.create_threadsafe_function(0, |ctx| ctx.env.create_uint32(ctx.value).map(|v| vec![v]))?;
for n in 0..100 {
let tsfn = tsfn.clone();
thread::spawn(move || {
// 通過(guò) tsfn.call 來(lái)調(diào)用 JS 函數(shù)
tsfn.call(Ok(n), ThreadsafeFunctionCallMode::Blocking);
});
}
Ok(())
}
接著我們執(zhí)行 yarn build,我們發(fā)現(xiàn) index.js 多出了 callThreadsafeFunction 方法,我們還是在 __test__/index.spec.mjs 中增加對(duì)應(yīng)的測(cè)試代碼:
import { callThreadsafeFunction } from "../index.js";
test("callThreadsafeFunction from native", async (t) => {
t.is(
callThreadsafeFunction((err, ...args) => {
console.log("Get the result from rust", args);
})
);
});
執(zhí)行 yarn test,我們可以發(fā)現(xiàn)控制臺(tái)成功輸出:
Get the result from rust [ 0 ]
Get the result from rust [ 1 ]
Get the result from rust [ 2 ]
...
Get the result from rust [ 99 ]
這樣我們就成功地把 JavaScript 中的函數(shù)傳遞到 Rust 中執(zhí)行了,大大豐富了 Rust 和 Node.js 交互的能力。
工程化
以上我們介紹了 napi-rs 的基本使用,但是在實(shí)際的開(kāi)發(fā)場(chǎng)景中,我們?nèi)绾我罱ㄒ粋€(gè)真實(shí)可用的 Rust 前端工具,應(yīng)該怎么做呢?
1、crate 組織
我們可以把整個(gè)工具拆分成多個(gè) crate,每個(gè) crate 有各自的職責(zé),這樣可以提高代碼的復(fù)用性,同時(shí)也方便我們進(jìn)行單元測(cè)試。
而 Rust 中的包管理是天生的 Monorepo 結(jié)構(gòu),我們可以把所有的 crate 都放到一個(gè)倉(cāng)庫(kù)中,然后通過(guò) Cargo.toml 中的 workspace 字段來(lái)管理:
[workspace]
members = ["crates/*"]
然后將所有的 crate 放到 crates 目錄下,這樣我們就可以通過(guò) cargo build/test 來(lái)同時(shí)構(gòu)建/測(cè)試所有的 crate 了。
在實(shí)際的工程項(xiàng)目中,我們一般會(huì)新建一個(gè) binding crate,用來(lái)做 napi-rs 的導(dǎo)出,核心的邏輯放到其它的 crate 中完成,細(xì)節(jié)可以參考我曾經(jīng)搭建的 Rust 版 MDX 編譯工具,倉(cāng)庫(kù)地址: https://github.com/web-infra-dev/mdx-rs-binding.
2、測(cè)試
在實(shí)際的開(kāi)發(fā)中,我們需要編寫(xiě)單元測(cè)試來(lái)保證代碼的正確性。而 Rust 中的單元測(cè)試工具是天生自帶的,我們只需要在對(duì)應(yīng)的文件中編寫(xiě)測(cè)試代碼即可,然后通過(guò) cargo test 來(lái)執(zhí)行測(cè)試,成本非常低。比如:
// src/lib.rs
fn fib(n: u32) -> u32 {
match n {
0 | 1 => n,
_ => fib(n - 1) + fib(n - 2),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_fib() {
assert_eq!(fib(10), 55);
}
}
3、GitHub Actions CI
由于 napi-rs 已經(jīng)幫助我們初始化了 CI 腳本,當(dāng)你往 main 分支提交代碼時(shí),會(huì)自動(dòng)觸發(fā) GitHub Actions 的操作,執(zhí)行構(gòu)建、測(cè)試、發(fā)布等步驟。
值得注意的是,在默認(rèn)的腳本中,會(huì)根據(jù)當(dāng)前的 commit 信息來(lái)判斷是否需要發(fā)布,具體的判斷邏輯如下:
- case 1: 如果當(dāng)前的 commit 信息只有 x.x.x(x 為數(shù)字),則發(fā)布正式版本到 npm 上
- case 2: 如果當(dāng)前的 commit 信息在 case 1 的基礎(chǔ)上增加了一些后綴內(nèi)容,則發(fā)布 beta 版本到 npm 上
- 其它情況不會(huì)發(fā)布。
當(dāng)然,你也可以通過(guò)修改.github/workflows/CI.yml來(lái)自定義發(fā)布的邏輯。
下面是發(fā)布成功的截圖:
總結(jié)
本文主要介紹了如何使用 napi-rs 來(lái)開(kāi)發(fā) Rust 前端工具,也分享我的一些實(shí)戰(zhàn)經(jīng)驗(yàn),希望能夠幫助到大家。
本文示例倉(cāng)庫(kù)地址: https://github.com/sanyuan0704/napi-rs-example。
最后,給大家推薦一些值得關(guān)注的 Rust 前端工具,供大家參考和學(xué)習(xí):
- mdx-rs-binding[5]: Rust 版 MDX 編譯工具。
- swc-plugins[6]: swc 的插件集合。
- Rspack[7]: 基于 Rust 的 Web Bundler。
- svgr-rs[8]: 基于 Rust 的 SVG 轉(zhuǎn) React 組件工具。
參考資料
[1]napi-rs: https://napi.rs。
[2]Rust 官網(wǎng): https://www.rust-lang.org/tools/install。
[3]npm 官方文檔: https://docs.npmjs.com/creating-and-publishing-scoped-public-packages#publishing-scoped-public-packages-to-the-public-npm-registry。
[4]官方文檔: https://napi.rs/docs/concepts/function。
[5]mdx-rs-binding: https://github.com/web-infra-dev/mdx-rs-binding。
[6]swc-plugins: https://github.com/web-infra-dev/swc-plugins。
[7]Rspack: https://github.com/web-infra-dev/rspack。
[8]svgr-rs: https://github.com/svg-rust/svgr-rs。