大家好，我是三元同學。

我們知道，隨著 SWC、Rspack 等 Rust 前端工具鏈的出現(xiàn)，Rust 逐漸成為了前端基建的重要一環(huán)。作為一門系統(tǒng)級別的語言，Rust 可以編譯出高性能的二進制文件，并且相比于 Node.js 可以做到高度地并發(fā)，從而讓前端工具鏈的性能達到了一個新的高度。而在這背后，你有沒有想過，Rust 是如何和 Node.js 進行交互的呢？

答案就是 napi-rs^[1]。這個庫可以說是 Rust 前端工具鏈的基石，搭建了 Node.js 和 Rust 之間語言通信的橋梁。在這篇文章中，我們將會使用 napi-rs 來編寫一個 Rust 的前端工具，來感受一下 Rust 和 Node.js 中間的交互，最終將這個工具發(fā)布到 npm 上，當然也會分享一些我的實戰(zhàn)經(jīng)驗。

前置環(huán)境

在開始之前，我們需要先安裝好 Rust 的開發(fā)環(huán)境。Rust 的安裝可以參考 Rust 官網(wǎng)[2]，安裝完成之后，我們可以通過以下命令來檢查環(huán)境是否安裝成功：

$ rustc --version

在安裝完成之后，Rust 會自動安裝 Cargo，這是 Rust 的包管理工具，類似于 Node.js 中的 npm。

創(chuàng)建項目

在安裝好 Rust 環(huán)境之后，我們就可以開始創(chuàng)建項目了。我們可以使用 napi-rs 官方腳手架，首先通過以下命令安裝腳手架：

yarn global add @napi-rs/cli
# 或者
npm install -g @napi-rs/cli
# 或者
pnpm add -g @napi-rs/cli

然后通過以下命令創(chuàng)建項目：

napi new

先輸入項目的名字，建議加上 scope（比如 @islandjs/napi-rs-example），這是因為我們最終會將不同平臺的二進制產(chǎn)物發(fā)布到 npm 上，而一旦這些包不在同一個 scope，就可能會觸發(fā) npm 的 spam detection(垃圾包檢測)，導致發(fā)布失敗。

你需要在 npm 上創(chuàng)建一個 scope，比如 @islandjs，然后將這個 scope 添加到你的 npm 賬號上，具體可以參考 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)

下一步是選擇你想支持哪個平臺。如果想要支持所有平臺，可以按 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。

接下來 napi-rs 會自動幫助我們安裝好項目的依賴，這樣我們就完成了項目的初始化。

目錄結構說明

在項目初始化完成之后，我們可以看到項目的目錄結構如下：

.
├── 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

你需要關心的目錄和文件主要有下面幾個:

• src: 這個目錄下是 Rust 代碼，我們的核心邏輯都會在這里實現(xiàn)。
• index.js: 這個文件是我們的入口文件，也就是說，外部調(diào)用我們的包的時候，實際上是調(diào)用了這個文件。
• build.rs: napi-rs 會在編譯的時候自動調(diào)用這個腳本文件，用來生成一些編譯時需要的代碼。
• npm: 這個目錄下存放我們的二進制文件，napi-rs 會在 GitHub Actions 上自動幫我們編譯出不同平臺的二進制文件，并且將其放在這個目錄下。這些平臺在初始化項目的時候我們已經(jīng)選擇好了。

當然，還有 .github 目錄，這個目錄下存放的是 GitHub Actions 的配置文件，我們可以在這里配置一些自動化的流程，比如自動編譯二進制文件、自動發(fā)布到 npm 等等，這部分的流程配置代碼 napi-rs 腳手架已經(jīng)幫我們寫好了，無需修改。

內(nèi)部調(diào)用機制

在完成項目的初始化之后，我們通過以下命令來編譯項目：

yarn build

這個命令會自動調(diào)用 build.rs 腳本，生成一些編譯時需要的代碼，然后再調(diào)用 cargo build 來編譯 Rust 代碼，最終會將編譯產(chǎn)物(.node 結尾的文件)放在項目根目錄下。我使用的是 M1 Mac，所以編譯出來的文件是 napi-rs-example.darwin-arm64.node。

接下來我們來分析一下 index.js 文件，這個文件是我們的入口文件，也就是說，外部調(diào)用我們的包的時候，實際上是調(diào)用了這個文件。簡化后的邏輯如下:

switch (platform) {
  case "android":
    // ...
    break;
  case "win32":
    // ...
    break;
  case "darwin":
    switch (arch) {
      case "x64":
        // 本地直接使用根目錄下 `napi-rs-example.linux-arm64-gnu.node`
        // 發(fā)布時，這個 .node 文件會被 `@islandjs/napi-rs-example-darwin-arm64` 這個包發(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;

這個入口會根據(jù)操作系統(tǒng)和 CPU 架構來加載不同的二進制文件，值得注意的是，本地開發(fā)階段和發(fā)布到 npm 后的調(diào)用策略是不一樣的：

• 本地開發(fā)階段，當你執(zhí)行 yarn build 時，會直接使用根目錄下的二進制文件，也就是 napi-rs-example.darwin-arm64.node，這個文件是通過 cargo build 生成的。
• 發(fā)布到 npm 后，當用戶執(zhí)行 yarn add @islandjs/napi-rs-example 時，會自動下載 @islandjs/napi-rs-example-darwin-arm64 這個包，這個包里面包含了編譯好的二進制文件，也就是 napi-rs-example.darwin-arm64.node。這時候入口文件會去加載這個包里面的二進制文件。

你可能會問了，在本地 yarn build 之后，并沒有發(fā)現(xiàn) npm 目錄下有 .node 產(chǎn)物呀，這樣發(fā)布出去豈不是沒有產(chǎn)物了？

不用擔心，在 GitHub 腳本中，napi-rs 會自動執(zhí)行編譯和產(chǎn)物移動的操作，將所有的 .node 文件移動到 npm 目錄下對應平臺的子目錄中，從而最終能夠保證發(fā)布到 npm 后，用戶能夠正常使用。GitHub CI 總體流程如下:

最后，index.js 的調(diào)用邏輯可以簡化為下面這張圖:

編寫 Rust 側(cè)代碼

接下來我們把目光轉(zhuǎn)移到 Rust 側(cè)，我們的核心邏輯都會在這里實現(xiàn)。在 src/lib.rs 中，我們可以看到這樣一段代碼:

#[napi]
pub fn sum(a: i32, b: i32) -> i32 {
  a + b
}

通過 #[napi] 宏，我們可以將 Rust 函數(shù)暴露給 JavaScript 使用。這個宏會自動幫我們生成一些代碼，使得我們的 Rust 函數(shù)能夠被 JavaScript 調(diào)用。

在執(zhí)行 yarn build 之后，我們會發(fā)現(xiàn)根目錄增加了index.d.ts，也就是說，napi-rs 已經(jīng)幫我們生成了類型聲明文件，類型文件的內(nèi)容如下：

export function sum(a: number, b: number): number;

可以看到，Rust 中的 i32 類型被轉(zhuǎn)換成了 JavaScript 中的 number 類型。而對于其它的諸多數(shù)據(jù)類型，napi-rs 也都做了相應的轉(zhuǎn)換，具體可以參考官方文檔^[4]。

下面我們以幾個典型的例子來實操一下。

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 方法，這個方法就是我們剛剛在 Rust 中定義的方法，只不過在 JavaScript 中，方法名被自動轉(zhuǎn)換成了駝峰式命名。并且你也能發(fā)現(xiàn)類型聲明文件也被更新了，內(nèi)容如下：

export function sum(a: number, b: number): number;
export function concatStr(a: string, b: string): string;

然后我們在 __test__/index.spec.mjs 中增加對應的測試代碼:

import test from "ava";

import { sum, concatStr } from "../index.js";

test("sum from native", (t) => {
  t.is(sum(1, 2), 3);
});

// 增加測試
test("concatStr from native", (t) => {
  t.is(concatStr("Hello", "World"), "HelloWorld");
});

執(zhí)行 yarn test，測試通過。

2、傳遞對象

在 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 中增加對應的測試代碼:

import { getOptions } from "../index.js";

test("getOptions from native", (t) => {
  const options = {
    id: 1,
    name: "napi-rs",
  };
  t.deepEqual(getOptions(options)).toEqual(options);
});

3、導出為異步函數(shù)

默認情況下，napi-rs 會將 Rust 函數(shù)導出為同步函數(shù)，如果我們想要導出異步函數(shù)給 Node.js 側(cè)使用，可以通過下面的方式來實現(xiàn)。

我們在 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è)的返回值類型為 Promise<number>
#[napi(ts_return_type="Promise<string>")]
fn async_fib(input: u32) -> AsyncTask<AsyncFib> {
  AsyncTask::new(AsyncFib { input })
}

要返回一個異步的函數(shù)，我們需要實現(xiàn) Task trait，這個 trait 有兩個關聯(lián)類型，Output 和 JsValue，分別表示 Rust 函數(shù)的返回值類型和 JavaScript 中對應的類型。在 compute 方法中，我們實現(xiàn)了具體的計算邏輯，而在 resolve 方法中，我們將計算結果轉(zhuǎn)換成了 JavaScript 中的 JsNumber 類型。然后我們在 async_fib 函數(shù)中，通過 AsyncTask::new 來創(chuàng)建一個異步任務，這個函數(shù)的返回值類型是 AsyncTask<AsyncFib>，這個類型會被 napi-rs 自動轉(zhuǎn)換成 JavaScript 中的 Promise 類型。

最后導出對應的類型聲明如下:

export function asyncFib(input: number): Promise<number>;

我們在 __test__/index.spec.mjs 中增加對應的測試代碼:

import { asyncFib } from "../index.js";

test("asyncFib from native", async (t) => {
  t.is(await asyncFib(10), 55);
});

4、把 JS 函數(shù)放到 Rust 中執(zhí)行

還有一種比較常見的場景，就是我們需要把 JavaScript 中的函數(shù)傳遞到 Rust 中執(zhí)行，這個時候我們可以使用 napi-rs 中的 ThreadSafeFunction 來實現(xiàn)。

我們在 lib.rs 中添加如下的代碼:

use std::thread;

use napi::{
  bindgen_prelude::*,
  threadsafe_function::{ErrorStrategy, ThreadsafeFunction, ThreadsafeFunctionCallMode},
};

// 強制指定參數(shù)類型
#[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ù)時傳遞的入?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 || {
      // 通過 tsfn.call 來調(diào)用 JS 函數(shù)
      tsfn.call(Ok(n), ThreadsafeFunctionCallMode::Blocking);
    });
  }
  Ok(())
}

接著我們執(zhí)行 yarn build，我們發(fā)現(xiàn) index.js 多出了 callThreadsafeFunction 方法，我們還是在 __test__/index.spec.mjs 中增加對應的測試代碼:

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)控制臺成功輸出:

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 的基本使用，但是在實際的開發(fā)場景中，我們?nèi)绾我罱ㄒ粋€真實可用的 Rust 前端工具，應該怎么做呢？

1、crate 組織

我們可以把整個工具拆分成多個 crate，每個 crate 有各自的職責，這樣可以提高代碼的復用性，同時也方便我們進行單元測試。

而 Rust 中的包管理是天生的 Monorepo 結構，我們可以把所有的 crate 都放到一個倉庫中，然后通過 Cargo.toml 中的 workspace 字段來管理:

[workspace]
members = ["crates/*"]

然后將所有的 crate 放到 crates 目錄下，這樣我們就可以通過 cargo build/test 來同時構建/測試所有的 crate 了。

在實際的工程項目中，我們一般會新建一個 binding crate，用來做 napi-rs 的導出，核心的邏輯放到其它的 crate 中完成，細節(jié)可以參考我曾經(jīng)搭建的 Rust 版 MDX 編譯工具，倉庫地址: https://github.com/web-infra-dev/mdx-rs-binding.

2、測試

在實際的開發(fā)中，我們需要編寫單元測試來保證代碼的正確性。而 Rust 中的單元測試工具是天生自帶的，我們只需要在對應的文件中編寫測試代碼即可，然后通過 cargo test 來執(zhí)行測試，成本非常低。比如：

// 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 腳本，當你往 main 分支提交代碼時，會自動觸發(fā) GitHub Actions 的操作，執(zhí)行構建、測試、發(fā)布等步驟。

值得注意的是，在默認的腳本中，會根據(jù)當前的 commit 信息來判斷是否需要發(fā)布，具體的判斷邏輯如下:

• case 1: 如果當前的 commit 信息只有 x.x.x(x 為數(shù)字)，則發(fā)布正式版本到 npm 上
• case 2: 如果當前的 commit 信息在 case 1 的基礎上增加了一些后綴內(nèi)容，則發(fā)布 beta 版本到 npm 上
• 其它情況不會發(fā)布。

當然，你也可以通過修改.github/workflows/CI.yml來自定義發(fā)布的邏輯。

下面是發(fā)布成功的截圖:

總結

本文主要介紹了如何使用 napi-rs 來開發(fā) Rust 前端工具，也分享我的一些實戰(zhàn)經(jīng)驗，希望能夠幫助到大家。

本文示例倉庫地址: https://github.com/sanyuan0704/napi-rs-example。

最后，給大家推薦一些值得關注的 Rust 前端工具，供大家參考和學習:

• 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。