WebAssembly 跨语言互操作：Rust 与 JS 的高效数据传递与类型桥接

WebAssembly 跨语言互操作：Rust 与 JS 的高效数据传递与类型桥接

一、WASM 不是"把 Rust 编译成 JS"，是两种语言的握手协议

刚开始学 WASM 的时候，我以为就是把 Rust 代码编译成 JS 能调用的函数，像写一个普通的库一样。实际写起来才发现，Rust 和 JS 之间的数据传递是最大的坑——Rust 用 UTF-8 字符串，JS 用 UTF-16；Rust 有丰富的类型系统，JS 只有 number/string/object；Rust 的内存由所有权管理，JS 的内存由 GC 管理。两种语言的内存模型完全不同，WASM 线性内存是唯一的桥梁。

这篇文章记录我在 Rust + WASM + JS 跨语言互操作方面的踩坑经验，重点是数据传递和类型桥接——这是 WASM 开发中 80% 的难点所在。

二、Rust-WASM-JS 互操作的架构与数据流

flowchart TB
    subgraph Rust 侧
        A[Rust 函数<br/>#[wasm_bindgen]]
        B[WASM 线性内存<br/>ArrayBuffer]
        C[ wasm_bindgen<br/>胶水代码]
    end

    subgraph JavaScript 侧
        D[JS 函数调用]
        E[TypedArray<br/>Uint8Array / Float32Array]
        F[JS 对象<br/>wasm_bindgen 包装]
    end

    D --> C --> A
    A --> C --> D

    B <--> E

    subgraph 数据传递方式
        G[简单类型<br/>i32/f64 直接传递]
        H[字符串<br/>UTF-8 编码拷贝]
        I[数组/Buffer<br/>共享线性内存]
        J[复杂对象<br/>JS 侧持有引用]
    end

    G --> C
    H --> C
    I --> B
    J --> F

    style C fill:#e3f2fd
    style B fill:#fff3e0
    style I fill:#e8f5e9

Rust 和 JS 之间的数据传递有四种方式：简单类型（i32/f64）直接通过 WASM 栈传递、字符串通过 UTF-8 编码拷贝、数组/Buffer 通过共享 WASM 线性内存传递、复杂对象在 JS 侧持有引用。性能关键路径是数组和 Buffer 的传递——避免拷贝，直接操作线性内存。

三、代码实现与分析

3.1 基本类型桥接

use wasm_bindgen::prelude::*;

/// 简单类型：直接传递，零拷贝
#[wasm_bindgen]
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

#[wasm_bindgen]
pub fn compute_f64(x: f64, y: f64) -> f64 {
    x * x + y * y
}

/// 布尔类型
#[wasm_bindgen]
pub fn is_positive(value: f64) -> bool {
    value > 0.0
}

/// 字符串传递：需要编码/解码拷贝
/// 性能注意：大字符串不要频繁传递
#[wasm_bindgen]
pub fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
}

/// 字符串处理：避免返回大字符串
#[wasm_bindgen]
pub fn count_words(text: &str) -> usize {
    text.split_whitespace().count()
}

3.2 高效数组传递

use wasm_bindgen::prelude::*;
use js_sys::Float32Array;
use wasm_bindgen::JsCast;

/// 方式1：通过 Vec 传递（有拷贝）
/// 适合小数组（< 10KB）
#[wasm_bindgen]
pub fn normalize_vec(data: Vec<f32>) -> Vec<f32> {
    let max = data.iter().cloned().fold(f32::NEG_INFINITY, f32::max);
    if max == 0.0 {
        return data;
    }
    data.into_iter().map(|x| x / max).collect()
}

/// 方式2：通过 JS TypedArray 直接操作线性内存（零拷贝）
/// 适合大数组（> 10KB）
#[wasm_bindgen]
pub fn normalize_inplace(data: &Float32Array) -> Result<(), JsValue> {
    // 获取 TypedArray 的视图，直接操作 WASM 线性内存
    let length = data.length() as usize;
    if length == 0 {
        return Ok(());
    }

    // 分配 WASM 线性内存
    let mut buffer = vec![0.0f32; length];
    data.copy_to(&mut buffer);

    // 在 Rust 侧处理
    let max = buffer.iter().cloned().fold(f32::NEG_INFINITY, f32::max);
    if max != 0.0 {
        for val in buffer.iter_mut() {
            *val /= max;
        }
    }

    // 写回 JS 侧
    data.copy_from(&buffer);

    Ok(())
}

/// 方式3：返回新的 TypedArray（避免修改输入）
#[wasm_bindgen]
pub fn compute_features(input: &Float32Array) -> Float32Array {
    let length = input.length() as usize;
    let mut data = vec![0.0f32; length];
    input.copy_to(&mut data);

    // 计算特征
    let mean = data.iter().sum::<f32>() / length as f32;
    let variance = data.iter().map(|&x| (x - mean).powi(2)).sum::<f32>() / length as f32;
    let std = variance.sqrt();

    // 返回新的 TypedArray
    let result = vec![mean, std, data[0], data[length - 1]];
    Float32Array::new_with_length(4)
        .copy_from(&result)
}

/// 方式4：使用 wasm_bindgen 的 Box<[T]> 支持
#[wasm_bindgen]
pub fn process_matrix(
    data: Box<[f32]>,
    rows: usize,
    cols: usize,
) -> Box<[f32]> {
    // 矩阵转置
    let mut result = vec![0.0f32; rows * cols];
    for i in 0..rows {
        for j in 0..cols {
            result[j * rows + i] = data[i * cols + j];
        }
    }
    result.into_boxed_slice()
}

3.3 复杂对象桥接

use wasm_bindgen::prelude::*;
use serde::{Deserialize, Serialize};

/// 用 serde 序列化复杂对象
#[derive(Serialize, Deserialize)]
pub struct ModelConfig {
    pub learning_rate: f64,
    pub epochs: u32,
    pub batch_size: u32,
    pub optimizer: String,
}

/// 从 JS 对象反序列化
#[wasm_bindgen]
pub fn create_model(config_json: &str) -> Result<WasmModel, JsValue> {
    let config: ModelConfig = serde_json::from_str(config_json)
        .map_err(|e| JsValue::from_str(&format!("配置解析失败: {}", e)))?;

    Ok(WasmModel {
        config,
        weights: vec![0.0; 100],
        trained: false,
    })
}

/// WASM 侧持有的对象
#[wasm_bindgen]
pub struct WasmModel {
    config: ModelConfig,
    weights: Vec<f64>,
    trained: bool,
}

#[wasm_bindgen]
impl WasmModel {
    /// 训练一步
    pub fn train_step(&mut self, input: &Float32Array, target: f32) -> f64 {
        let mut data = vec![0.0f32; input.length() as usize];
        input.copy_to(&mut data);

        // 简化的训练逻辑
        let loss = self.weights.iter()
            .zip(data.iter())
            .map(|(w, x)| (w - x as f64).powi(2))
            .sum::<f64>();

        // 更新权重
        for (w, x) in self.weights.iter_mut().zip(data.iter()) {
            *w -= self.config.learning_rate * (*w - *x as f64);
        }

        self.trained = true;
        loss
    }

    /// 获取模型状态（序列化为 JSON）
    pub fn to_json(&self) -> String {
        serde_json::json!({
            "trained": self.trained,
            "weight_count": self.weights.len(),
            "learning_rate": self.config.learning_rate,
        }).to_string()
    }

    /// 导出权重为 Float64Array
    pub fn export_weights(&self) -> Float64Array {
        let array = js_sys::Float64Array::new_with_length(self.weights.len() as u32);
        array.copy_from(&self.weights);
        array
    }
}

3.4 JavaScript 侧调用

import init, {
    add,
    greet,
    normalize_inplace,
    compute_features,
    create_model,
} from './pkg/wasm_bridge.js';

async function demo() {
    await init();

    // 简单类型
    console.log(add(3, 5));  // 8

    // 字符串
    console.log(greet("WASM"));  // "Hello, WASM!"

    // 大数组：零拷贝操作
    const data = new Float32Array(10000);
    for (let i = 0; i < data.length; i++) {
        data[i] = Math.random();
    }
    normalize_inplace(data);  // 原地归一化

    // 复杂对象
    const config = JSON.stringify({
        learning_rate: 0.01,
        epochs: 100,
        batch_size: 32,
        optimizer: "sgd",
    });
    const model = create_model(config);

    const input = new Float32Array(100);
    for (let i = 0; i < input.length; i++) {
        input[i] = Math.random();
    }
    const loss = model.train_step(input, 1.0);
    console.log(`Loss: ${loss.toFixed(4)}`);

    // 导出权重
    const weights = model.export_weights();
    console.log(`权重数量: ${weights.length}`);
}

四、跨语言互操作的边界与权衡

字符串传递的性能陷阱：每次从 JS 传递字符串到 WASM，都需要 UTF-8 编码 + 内存拷贝。对于大文本（> 1MB），这个开销不可忽略。建议：如果需要频繁传递大文本，考虑在 WASM 侧维护一个字符串池，JS 侧只传递索引。

线性内存的生命周期：WASM 线性内存由 Rust 侧管理，JS 侧的 TypedArray 视图在 Rust 释放内存后变成悬垂指针。建议：避免在 JS 侧长期持有 TypedArray 视图，每次使用时重新获取。如果必须持有，用 Float32Array.prototype.slice() 拷贝一份。

serde 的开销：用 serde_json 序列化/反序列化复杂对象很方便，但 JSON 解析有性能开销。对高频调用的接口，建议用 wasm_bindgen 的原生类型支持（js_sys::Object、js_sys::Array）手动桥接，避免 JSON 中间表示。

错误处理的跨语言传播：Rust 的 Result<T, E> 通过 wasm_bindgen 转换为 JS 的异常。但 Rust 的错误类型信息在传播到 JS 后可能丢失（只保留 toString() 的结果）。建议在 Rust 侧将错误信息格式化为字符串，确保 JS 侧能获取有意义的错误描述。

五、总结

Rust + WASM + JS 跨语言互操作的核心是理解两种语言的内存模型差异，选择合适的数据传递方式。本文的关键实践为：简单类型直接传递、大数组通过 TypedArray 共享线性内存、复杂对象用 serde JSON 序列化、字符串传递注意编码开销。WASM 不是"把 Rust 编译成 JS"，而是两种语言通过线性内存的握手协议——理解这个协议，才能写出高效的跨语言代码。