Rust 編譯為 WebAssembly 在前端項目中的使用

作者：前端柒八九 2023-10-27 10:16:17

為了保持構建速度非常快，web-sys?將每個Web接口都封裝在一個Cargo特性后面。在API文檔中找到我們要使用的類型或方法；它將列出必須啟用的特性才能訪問該API。

前言

最近，加大了對Rust相關文章的輸出。在評論區或者私信區有一些不同的聲音說：“Rust沒有前途，然后...."。其實呢，看一個技術是否有需要學習的動力。想必大家的底層理由都是「一切都是向錢看」，畢竟在國內大家都是業務為主，想自己純手搞一套符合自己的技術框架和范式，這是不切實際的。（當然也不能一桿子打死，還是有很多技術大牛的）現在大家糾結或者對這個技術屬于觀望態度，無非就是在平時開發工作中沒有涉及到的點。

同時，由于國內技術的「滯后性」，有一些應用場景其實還是處于蠻荒的狀態。（不是崇洋媚外，事實確實如此）。所以，在一些可以用到新的技術點的方向上，國內還是處于藍海階段。

所以，本著對該技術的獨有關注度，我還是選擇義無反顧的投身到學習和實際中。「沖破黎明之前的黑暗，你會擁有太陽，而晨曦中第一縷陽光也是為你而耀眼」。

圖片

而具體，Rust到底能給你帶來點啥，我們之前有文章講過，這里就不在贅述了。

Last but not leaset，由于現在本人暫時專注于前端領域居多，所以我更多關注Rust能為前端帶來點啥。而說到Rust和前端，第一點的聯想就是：WebAssembly。（如果，不了解何為WebAssembly，可以參考我們之前的文章瀏覽器第四種語言-WebAssembly,里面的例子是用Emscripten寫的）

其實，我們之前寫過如何用C寫wasm，也寫過WebAssembly-C與JS互相操作等文章。但是，由于一些不可言喻的原因擱置了。

我們今天將使用Rust創建一個WebAssembly Hello World程序。我們將深入了解由wasm-bindgen生成的代碼，以及它們如何共同協作來幫助我們進行開發。我們還將使用wabt來探索生成的wasm代碼。這將使我們更好地理解Rust WebAssembly，并為我們的開發奠定良好的基礎。

好了，天不早了，干點正事哇。

我們能所學到的知識點

前置知識點
項目搭建
原理探析
內容拓展

1. 前置知識點

「前置知識點」，只是做一個概念的介紹，不會做深度解釋。因為，這些概念在下面文章中會有出現，為了讓行文更加的順暢，所以將本該在文內的概念解釋放到前面來。「如果大家對這些概念熟悉，可以直接忽略」同時，由于閱讀我文章的群體有很多，所以有些知識點可能「我視之若珍寶，爾視只如草芥，棄之如敝履」。以下知識點，請「酌情使用」。

安裝Rust

如果是你一個Rust萌新，我們也給你提供Rust環境配置和入門指南。

如果，想獨立完成安裝，可以到Rust 安裝頁面跟著教程安裝。

在安裝成功Rust后，它會安裝一個名為rustup的工具，這個工具能讓我們管理多個不同版本的 Rust。默認情況下，它會安裝用于慣常 Rust 開發的 stable 版本 Rust Release。

Rustup 會安裝

Rust 的編譯器 rustc
Rust 的包管理工具 cargo
Rust 的標準庫 rust-std
以及一些有用的文檔 rust-docs

因為，我本機已經安裝好了Rust。我們可以通過rustup --version來查看rustup的版本。以下是我本機的rustup版本信息。下文中所有的代碼，都基于該版本。

rustup --version
rustup 1.26.0 (5af9b9484 2023-04-05)

安裝WebAssembly二進制工具包（wabt）

圖片

這些工具旨在用于開發工具鏈或其他系統，這些系統希望「操作WebAssembly文件」。與WebAssembly規范解釋器不同（該解釋器旨在盡可能簡單、聲明性和“規范性”），這些工具是用C/C++編寫的，并設計成更容易集成到其他系統中。這些工具不旨在提供優化平臺或更高級的編譯目標；相反，它們旨在實現與規范的完全適應和遵從。

我們可以利用brew來在Mac環境下安裝。

圖片

2. 項目搭建

2.1 安裝wasm-bindgen

我們可以通過cargo install --list來查看在$HOME/.cargo/bin位置安裝過的Rust二進制文件。

在一些其他的教程中可以不使用wasm-bindgen構建Hello World程序，但是在本文中，我們將使用它，因為它在Rust WebAssembly開發中是必不可少的。

cargo install wasm-bindgen-cli

Rust WebAssembly允許我們將WebAssembly模塊有針對性地插入到現有的JavaScript應用程序中，尤其是在「性能關鍵的代碼路徑」中。我們可以將wasm-bindgen視為一種工具，它通過生成用于JavaScript和WebAssembly之間高效交互的「粘合代碼」和綁定來幫助我們實現絲滑的交互體驗。

2.2 創建Rust WebAssembly項目

巴拉拉小魔仙，念誦如下咒語，構建一個Rust WebAssembly項目。

cargo new hello_world --lib

上面的代碼是使用Cargo工具創建一個新的Rust項目，項目的名稱是hello_world，并且指定它是一個庫（--lib）。這將創建一個包含基本項目結構的文件夾，其中包括一個Cargo.toml文件和一個src文件夾。

+-- Cargo.toml
+-- src
    +-- lib.rs

Cargo.toml文件用于管理項目的依賴和配置
src文件夾包含項目的Rust源代碼文件
項目名稱hello_world是一個示例名稱，我們可以根據自己的需求為項目指定不同的名稱。

2.3 修改Cargo.toml配置項

使用宇宙最強IDE -VScode，打開Cargo.toml文件。我們應該會看到以下內容。

[package]
name = "hello_world"
version = "0.1.0"
authors = ["789"]
edition = "2021"

[dependencies]

將其修改成下面的內容

[package]
name = "hello_world"
version = "0.1.0"
authors = ["789"]
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-bindgen = "0.2"

上面的大部分字段大家都能看懂，其中lib項的配置，這里稍微解釋一下：

crate-type = ["cdylib"]: 這一行「指定了生成的庫的類型」。在這里，crate-type 設置為["cdylib"]，這表示我們正在創建一個動態鏈接庫（C-compatible dynamic library）。這用于編譯一個供其他編程語言加載的動態庫。此輸出類型將在Linux上創建*.so文件，在macOS上創建*.dylib文件，在Windows上創建*.dll文件。

這種類型的庫可以被其他編程語言調用，因為它們與C語言兼容。這對于與WebAssembly（Wasm）互操作性很重要，因為Wasm通常需要與C語言接口進行交互。因此，cdylib 表示該庫是一個可供其他語言使用的動態鏈接庫。

2.4 編輯lib.rs

打開src/lib.rs文件。將其更改為以下內容：

extern crate wasm_bindgen;
use wasm_bindgen::prelude::*;

// 導入 'window.alert'
#[wasm_bindgen]
extern "C" {
    fn alert(s: &str);
}

// 導出一個 'helloworld' 函數
#[wasm_bindgen]
pub fn helloworld(name: &str) {
    alert(&format!("Hello World : {}!", name));
}

我們簡單解釋一下核心代碼:

extern crate wasm_bindgen;: 這一行聲明了對wasm_bindgen庫的依賴。wasm_bindgen是一個Rust庫，用于構建Wasm模塊并提供與JavaScript的互操作性。在 Rust 當中，庫被稱為crates，因為我們使用的是一個外部庫，所以有 extern。
use wasm_bindgen::prelude::*;: 這一行導入了wasm_bindgen庫的預導出（prelude）模塊中的所有內容，以便在后續代碼中使用。

在 Rust 中調用來自 JavaScript 的外部函數

#[wasm_bindgen]
extern "C" {
    fn alert(s: &str);
}

#[wasm_bindgen]: 在 #[] 中的內容叫做 "屬性"，并以某種方式改變下面的語句。#[wasm_bindgen]是一個「屬性標記」，用于指定與WebAssembly互操作相關的特性。

extern "C" { fn alert(s: &str); }: 這里聲明了一個「外部函數」alert，它使用extern "C" 指定了C ABI（應用二進制接口），這意味著它「可以與C語言進行交互」。「這個alert函數沒有在Rust中實現，而是在JavaScript中實現，用于在瀏覽器中顯示警告框」。

在 JavaScript 中調用的 Rust 函數

#[wasm_bindgen]
pub fn helloworld(name: &str) {
    alert(&format!("Hello World : {}!", name));
}

#[wasm_bindgen] pub fn helloworld(name: &str): 這是一個Rust函數helloworld，它被標記為wasm_bindgen，這意味著它「可以被JavaScript調用」。這個函數接受一個「字符串參數」name，然后調用「之前聲明」的alert函數，以顯示帶有Hello World消息的彈框，并在消息中包括name參數的內容。

2.5 編譯代碼

在命令行中輸入以下命令：

cargo build --target wasm32-unknown-unknown

如果未安裝對應的庫，控制臺會給出提示。

圖片

那我們就照貓畫虎的操作一下：

rustup target add wasm32-unknown-unknown?

cargo build: 這是 Cargo 工具的命令，用于構建 Rust 項目。它會編譯項目的源代碼并生成可執行文件或庫文件，具體取決于項目的類型。
--target wasm32-unknown-unknown: 這部分是構建的目標參數。--target 標志用于指定要構建的目標平臺。在這里，wasm32-unknown-unknown 是指定了 WebAssembly 目標平臺。這告訴 Cargo 生成「適用于 WebAssembly 的二進制文件」，而不是生成本地平臺的二進制文件。

當運行這個命令后，Cargo 會使用 Rust 編譯器（Rustc）以及與 WebAssembly 相關的工具鏈，將 Rust 代碼編譯為 WebAssembly 格式的二進制文件。這個生成的 Wasm 文件可以在瀏覽器中運行，或與其他支持 WebAssembly 的環境一起使用。

運行結果如下：

cargo build --target wasm32-unknown-unknown 命令的「默認輸出位置」是在項目的 target 目錄下，具體位置是：

target/wasm32-unknown-unknown/debug/

在這個目錄下，我們會找到生成的 WebAssembly 文件（通常是一個 .wasm 文件），以及其他與編譯過程相關的文件。

圖片

2.6 構建 Web服務器

既然，我們通過上述的魔法，將Rust程序編譯為了可以在瀏覽器環境下引用執行的格式。「為了這口醋，我們還專門包頓餃子」。

我們需要一個Web服務器來測試我們的WebAssembly程序。我們將使用Webpack，我們需要創建三個文件：index.js、package.json和webpack.config.js。

下面的代碼，我們最熟悉不過了，就不解釋了。

index.js

// 直接引入了，剛才編譯后的文件
const rust = import('./pkg/hello_world.js');

rust
  .then(m => m.helloworld('World!'))
  .catch(console.error);

package.json

{
  "scripts": {
    "build": "webpack",
    "serve": "webpack-dev-server"
  },

  "devDependencies": {
    "@wasm-tool/wasm-pack-plugin": "0.4.2",
    "text-encoding": "^0.7.0",
    "html-webpack-plugin": "^3.2.0",
    "webpack": "^4.29.4",
    "webpack-cli": "^3.1.1",
    "webpack-dev-server": "^3.1.0"
  }
}

webpack.config.js

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const webpack = require('webpack');
const WasmPackPlugin = require("@wasm-tool/wasm-pack-plugin");

module.exports = {
    entry: './index.js',
    output: {
        path: path.resolve(__dirname, 'dist'),
        filename: 'index.js',
    },
    plugins: [
        new HtmlWebpackPlugin(),
        new WasmPackPlugin({
            crateDirectory: path.resolve(__dirname, ".")
        }),
        // 讓這個示例在不包含`TextEncoder`或`TextDecoder`的Edge瀏覽器中正常工作。
        new webpack.ProvidePlugin({
            TextDecoder: ['text-encoding', 'TextDecoder'],
            TextEncoder: ['text-encoding', 'TextEncoder']
        })
    ],
    mode: 'development'
};

安裝指定的依賴。

npm install webpack --save-dev
npm install webpack-cli --save-dev
npm install webpack-dev-server --save-dev
npm install html-webpack-plugin --save-dev
npm install @wasm-tool/wasm-pack-plugin --save-dev
npm install text-encoding --save-dev

2.7 構建&運行程序

使用npm run build構建程序。

使用npm run serve運行Hello World程序

在瀏覽器中打開localhost:8080,我們將看到一個顯示 Hello World! 的彈窗。

圖片

到目前為止，我們已經構建了一個wasm并且能夠和js實現功能交互的項目。其實，到這里已經完成了，我們這篇文章的使命。但是，在這里戛然而止，感覺缺失點啥。所以，我們繼續深挖上面的項目的實現原理。

3. 原理探析

在使用cargo和wasm_bindgen編譯源代碼時，會在pkg文件中「自動生成」以下文件：

"hello_world_bg.wasm"
"hello_world.js"
"hello_world.d.ts"
"package.json"

這些文件也可以通過使用以下wasm-bindgen命令手動生成：

wasm-bindgen target/wasm32-unknown-unknown/debug/hello_world.wasm --out-dir ./pkg

瀏覽器調用順序

以下顯示了當我們在瀏覽器中訪問localhost:8080時發生的函數調用序列。

index.js
hello_world.js (調用hello_world_bg.js)
helloworld_bg.wasm

index.js

const rust = import('./pkg/hello_world.js');

rust
  .then(m => m.helloworld('World!'))
  .catch(console.error);

index.js 導入了 hello_world.js 并調用其中的 helloworld 函數。

hello_world.js

下面是hello_world.js的內容，在其中它調用了helloworld_bg.wasm

import * as wasm from "./hello_world_bg.wasm";
import { __wbg_set_wasm } from "./hello_world_bg.js";
__wbg_set_wasm(wasm);
export * from "./hello_world_bg.js";

hello_world_bg.js

// ...省去了部分代碼
export function helloworld(name) {
    const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
    const len0 = WASM_VECTOR_LEN;
    wasm.helloworld(ptr0, len0);
}

hello_world_bg.js 文件是由wasm-bindgen自動生成的，它包含了用于將DOM和JavaScript函數導入到Rust中的JavaScript粘合代碼。它還在生成的WebAssembly函數上向JavaScript公開了API。

Rust WebAssembly專注于將WebAssembly與現有的JavaScript應用程序集成在一起。為了實現這一目標，我們需要在JavaScript和WebAssembly函數之間「傳遞不同的值、對象或結構。這并不容易，因為需要協調兩個不同系統的不同對象類型」。

更糟糕的是，當前WebAssembly僅支持「整數」和「浮點數」，不支持字符串。這意味著我們不能簡單地將字符串傳遞給WebAssembly函數。

要將字符串傳遞給WebAssembly，我們需要「將字符串轉換為數字」（請注意在webpack.config.js中指定的TextEncoderAPI），將這些數字放入WebAssembly的內存空間中，最后「返回一個指向字符串的指針」給WebAssembly函數，以便在JavaScript中使用它。在最后，我們需要釋放WebAssembly使用的字符串內存空間。

如果我們查看上面的JavaScript代碼，這正是自動執行的操作。helloworld函數首先調用passStringToWasm。

這個函數在WebAssembly中「創建一些內存空間」，將我們的字符串轉換為數字，將數字寫入內存空間，并返回一個指向字符串的指針。

圖片

然后將指針傳遞給wasm.helloworld來執行JavaScript的alert。最后，wasm.__wbindgen_free釋放了內存。

如果只是傳遞一個簡單的字符串，我們可能可以自己處理，但考慮到當涉及到更復雜的對象和結構時，這個工作會很快變得非常復雜。這說明了wasm-bindgen在Rust WebAssembly開發中的重要性。

反編譯wasm到txt

在前面的步驟中，我們注意到wasm-bindgen生成了一個hello_world.js文件，其中的函數調用到我們生成的hello_world_bg.wasm中的WebAssembly代碼。

基本上，hello_world.js充當其他JavaScript（如index.js）與生成的WebAssembly的helloworld_bg.wasm之間的橋梁。

我們可以通過輸入以下命令進一步探索helloworld_bg.wasm：

wasm2wat hello_world_bg.wasm > hello_world.txt

這個命令使用wabt將WebAssembly轉換為WebAssembly文本格式，并將其保存到一個hello_world.txt文件中。打開helloworld.txt文件，然后查找$helloworld函數。這是我們在src/lib.rs中定義的helloworld函數的生成WebAssembly函數。

$helloworld函數

圖片

在helloworld.txt中查找以下行：

(export "helloworld" (func $helloworld))

這一行導出了wasm.helloworld供宿主調用的WebAssembly函數。我們通過hello_world_bg.js中的wasm.helloworld來調用這個WebAssembly函數。

圖片

接下來，查找以下行：

(import "./hello_world_bg.js" "__wbg_alert_9ea5a791b0d4c7a3" (func $hello_world::alert::__wbg_alert_9ea5a791b0d4c7a3::h93c656ecd0e94e40 (type 4)))

這對應于在hello_world_bg.js中生成的以下JavaScript函數：

export function __wbg_alert_9ea5a791b0d4c7a3() { return logError(function (arg0, arg1) {
    alert(getStringFromWasm0(arg0, arg1));
}, arguments) };

這是wasm-bindgen提供的「粘合部分」，幫助我們在WebAssembly中使用JavaScript函數或DOM。

最后，讓我們看看wasm-bindgen生成的其他文件。

hello_world.d.ts

這個.d.ts文件包含JavaScript粘合的TypeScript類型聲明，如果我們的現有JavaScript應用程序正在使用TypeScript，它會很有用。我們可以對調用WebAssembly函數進行「類型檢查」，或者讓我們的IDE提供自動完成。如果我們不使用TypeScript，可以安全地忽略這個文件。

package.json

package.json文件包含有關生成的JavaScript和WebAssembly包的元數據。它會自動從我們的Rust代碼中填充所有npm依賴項，并使我們能夠發布到npm。

4. 內容拓展

再次看一下以下代碼：

hello_world_bg.js

function helloworld(name) {
    const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
    const len0 = WASM_VECTOR_LEN;
    wasm.helloworld(ptr0, len0);
}

該代碼用于分配和釋放內存，這一切都是「由程序自動處理」的。不需要垃圾回收器或完整的框架引擎，使得使用Rust編寫的WebAssembly應用程序或模塊變得小巧且優化。其他需要垃圾回收器的語言將需要包含用于其底層框架引擎的wasm代碼。因此，無論它們有多么優化，其大小都不會小于Rust提供的大小。這使得Rust WebAssembly成為一個不錯的選擇，如果我們需要將小型WebAssembly模塊集成或注入到JavaScript Web應用程序中。

除了Hello World之外，還有一些其他需要注意的事項：

web-sys

使用wasm-bindgen，我們可以通過使用extern在Rust WebAssembly中調用JavaScript函數。請記住src/lib.rs中的以下代碼：

#[wasm_bindgen]
extern "C" {
    fn alert(s: &str);
}

Web具有大量API，從DOM操作到WebGL再到Web Audio等等。因此，如果我們的Rust WebAssembly程序增長，并且我們需要對Web API進行多次不同的調用，我們將需要花時間編寫大量的extern代碼。

?
web-sys充當wasm-bindgen的前端，為所有Web API提供原始綁定。
?

這意味著如果我們使用web-sys，可以節省時間，而不必編寫extern代碼。

圖片

引入web-sys

將web-sys添加為Cargo.toml的依賴項：

[dependencies]
wasm-bindgen = "0.2"

[dependencies.web-sys]
version = "0.3"
features = [
]

為了保持構建速度非常快，web-sys將每個Web接口都封裝在一個Cargo特性后面。在API文檔中找到我們要使用的類型或方法；它將列出必須啟用的特性才能訪問該API。

例如，如果我們要查找window.resizeTo函數，我們會在API文檔中搜索resizeTo。我們將找到web_sys::Window::resize_to函數，它需要啟用Window特性。要訪問該函數，我們在Cargo.toml中啟用Window特性：

[dependencies.web-sys]
version = "0.3"
features = [
  "Window"
]

調用這個方法：

use wasm_bindgen::prelude::*;
use web_sys::Window;

#[wasm_bindgen]
pub fn make_the_window_small() {
    // 調整窗口大小為500px x 500px。
    let window = web_sys::window().unwrap();
    window.resize_to(500, 500)
        .expect("無法調整窗口大小");
}

這段代碼的目的是調整瀏覽器窗口的大小為500x500像素，并演示了如何使用web-sys和啟用的Cargo特性來調用Web API。

責任編輯：武曉燕來源：前端柒八九

前端項目 Rust