组件模型：wit-bindgen 详解

Wasm 组件模型

核心组件（Core Wasm）的局限

传统的 WebAssembly 模块（Core Wasm）只支持数值类型（i32/i64/f32/f64）的导入导出。要传递字符串、列表、结构体等复杂类型，必须手动约定内存布局，既繁琐又容易出错。

Wasm 组件模型（Component Model）是对 Core Wasm 的高层封装，它引入了丰富的接口类型系统，让不同语言编写的 Wasm 模块可以直接互相调用，就像调用普通函数一样。

组件模型的核心概念

WIT：WebAssembly Interface Types

WIT 语言简介

WIT（WebAssembly Interface Types）是专为组件模型设计的接口定义语言（IDL），用于描述组件的导入和导出接口。

// adder.wit
package example:adder;

world adder {
  export add: func(a: s32, b: s32) -> s32;
}

// 更复杂的接口
package example:image-processor;

interface types {
  type pixel = tuple<u8, u8, u8, u8>;  // RGBA
  record image {
    width: u32,
    height: u32,
    data: list<pixel>,
  }
}

world processor {
  use types.{image, pixel};
  export grayscale: func(img: image) -> image;
  export blur: func(img: image, radius: f32) -> image;
}

wit-bindgen：自动生成绑定代码

# 安装 wit-bindgen CLI
cargo install wit-bindgen-cli

# 为 Rust 生成 Guest 绑定
wit-bindgen rust --world adder adder.wit

// 使用 wit-bindgen 宏（Rust guest）
wit_bindgen::generate!({
    path: "adder.wit",
    world: "adder",
});

struct MyAdder;

impl Guest for MyAdder {
    fn add(a: i32, b: i32) -> i32 {
        a + b
    }
}

export!(MyAdder);

用 jco 在 JavaScript 中使用组件

# 安装 jco（JavaScript Component 工具）
npm install -g @bytecodealliance/jco

# 将 Wasm 组件转译为 JS 模块
jco transpile adder.component.wasm -o ./transpiled

// 使用转译后的组件
import { add } from './transpiled/adder.js';
console.log(add(3, 4));  // 7 — 类型安全，无需手动内存管理

为什么需要组件模型？

Core Wasm 的三大局限

传统 WebAssembly（Core Module）在跨语言互操作方面有根本性缺陷：

组件模型（Component Model）通过 WIT（接口定义语言）+ 高级类型系统 + 标准化 ABI 解决了这三个问题，实现了真正的跨语言「即插即用」。

WIT 类型系统全览

// 完整的 WIT 类型系统示例
package example:types@1.0.0;

interface all-types {
  // ==================== 基础类型 ====================
  // 有符号整数：s8, s16, s32, s64
  // 无符号整数：u8, u16, u32, u64
  // 浮点数：f32, f64
  // 布尔：bool
  // 字符：char（Unicode 标量值）
  // 字符串：string（UTF-8）

  // ==================== 复合类型 ====================

  // tuple：固定长度的值序列
  type rgb = tuple<u8, u8, u8>;

  // list：动态长度的同类型序列
  type byte-array = list<u8>;
  type strings = list<string>;

  // option：可选值（对应 Rust 的 Option, JS 的 null）
  type maybe-int = option<s32>;

  // result：成功或错误（对应 Rust 的 Result）
  type parse-result = result<s32, string>;
  // result<_> = result<(), ()>

  // ==================== 自定义类型 ====================

  // record：命名字段结构体
  record user {
    id: u64,
    name: string,
    email: string,
    roles: list<string>,
    metadata: option<string>,  // 可选字段
  }

  // variant：带数据的枚举（类似 Rust 的 enum）
  variant shape {
    circle(f64),               // 圆：半径
    rectangle(tuple<f64, f64>),  // 矩形：宽×高
    point,                     // 点：无关联数据
  }

  // enum：简单枚举（不带关联数据）
  enum log-level { trace, debug, info, warn, error }

  // flags：位掩码组合标志
  flags permissions {
    read,
    write,
    execute,
  }

  // ==================== 函数签名 ====================
  create-user: func(name: string, email: string) -> result<user, string>;
  get-user: func(id: u64) -> option<user>;
  calculate-area: func(s: shape) -> f64;
  check-permission: func(user: borrow<user>, perm: permissions) -> bool;
}

Resource 类型：管理对象生命周期

Resource 是组件模型中最重要的高级类型，它允许将有状态的 C++ 类或 Rust 结构体安全地暴露给其他语言，同时保持所有权和生命周期管理。

// resource 类型示例：数据库连接
package example:database@1.0.0;

interface db {
  resource connection {
    // constructor：创建新实例
    constructor(url: string);

    // 方法：操作此资源
    query: func(sql: string) -> result<list<list<string>>, string>;
    execute: func(sql: string) -> result<u64, string>;
    close: func();
  }
}

// Rust 实现 WIT resource
wit_bindgen::generate!({
    path: "database.wit",
    world: "db",
});

use exports::example::database::db::*;

struct MyConnection {
    url: String,
    // 实际数据库客户端...
}

impl GuestConnection for MyConnection {
    fn new(url: String) -> Self {
        MyConnection { url }
    }

    fn query(&self, sql: String) -> Result<Vec<Vec<String>>, String> {
        // 执行查询...
        Ok(vec![])
    }

    fn execute(&self, sql: String) -> Result<u64, String> {
        // 执行非查询语句...
        Ok(0)
    }

    fn close(&self) { /* 关闭连接 */ }
}

Canonical ABI：字符串和 list 的内存表示

理解 Canonical ABI 是理解组件模型性能特性的关键。当 Wasm 组件 A 调用组件 B 的函数并传递字符串时，底层发生以下步骤：

// 接口定义（两个组件都同意的契约）
package example:greeting;
world greeter {
  export greet: func(name: string) -> string;
}

// Canonical ABI 的字符串传递原理（简化）
// 当 JS/Rust 调用者传递 "Alice" 给组件 B 的 greet() 时：
// 
// 1. 调用者（组件 A）：
//    - 调用组件 B 暴露的 cabi_realloc() 分配内存
//    - 将 "Alice"（UTF-8 字节）写入分配的内存
//    - 调用 greet(ptr=42, len=5)（Core Wasm 层面，数值参数）
//
// 2. 被调用者（组件 B，Rust 实现）：
//    - wit-bindgen 生成的包装代码从 (ptr, len) 重建 &str
//    - 调用用户的 greet(&str) → String Rust 函数
//    - 将返回的 String 写入输出内存区域
//    - 返回 (out_ptr, out_len) 给调用者
//
// 关键：内存拷贝发生在组件边界（每次调用传递复杂类型都有拷贝开销）
// 对于高频调用，应批量传递数据以摊薄开销
pub fn greet(name: String) -> String {
    format!("Hello, {}!", name)  // 用户只需关注业务逻辑
}

cargo-component：Rust 组件开发工具

从零开始创建 Wasm 组件

# 安装 cargo-component（Bytecode Alliance 官方工具）
cargo install cargo-component

# 创建新的 Wasm 组件项目
cargo component new my-component --lib
cd my-component

# 目录结构：
# my-component/
# ├── Cargo.toml
# ├── src/lib.rs          ← 实现代码
# └── wit/world.wit       ← 接口定义（自动生成基础模板）

# 编译为 Wasm 组件（.wasm 组件格式，不是普通 .wasm 模块）
cargo component build --release

# 用 wasm-tools 检查组件结构
wasm-tools component wit target/wasm32-wasip1/release/my_component.wasm

// wit/world.wit — 定义组件接口
// package my:component;
// world my-world {
//   export calculate: func(data: list<f64>) -> result<f64, string>;
// }

// src/lib.rs — cargo-component 生成的绑定基础
mod bindings;

use bindings::exports::my::component::my_world::Guest;

struct Component;

impl Guest for Component {
    // 实现 WIT 中声明的 calculate 函数
    fn calculate(data: Vec<f64>) -> Result<f64, String> {
        if data.is_empty() {
            return Err("输入数据不能为空".to_string());
        }
        // 计算平均值
        let sum: f64 = data.iter().sum();
        Ok(sum / data.len() as f64)
    }
}

bindings::export!(Component with _bindings);

组件的组合（Composition）

用 wac 工具组合多个组件

# 安装 wac（WebAssembly Composition 工具）
cargo install wac-cli

# 假设有两个组件：
# - image-decoder.wasm（解码图像，输出像素数据）
# - image-filter.wasm（接受像素数据，输出处理后的像素数据）

# 用 WAC 脚本组合它们
cat > pipeline.wac <<'EOF'
let decoder = new image:decoder;
let filter = new image:filter;

// 将 decoder 的输出连接到 filter 的输入
let result = filter.apply(decoder.decode(input));
EOF

wac compose pipeline.wac -o pipeline.wasm
# 生成的 pipeline.wasm 是组合后的单一组件

跨语言互操作完整示例

# 场景：Python 代码调用 Rust 编写的图像处理算法

# 1. 定义 WIT 接口
cat > image.wit <<'EOF'
package example:image-proc;
world processor {
  export process: func(pixels: list<u8>, width: u32, height: u32) -> list<u8>;
}
EOF

# 2. Rust 实现（编译为 Wasm 组件）
# cargo component build --release

# 3. 用 componentize-py 从 Python 调用
pip install componentize-py
componentize-py --wit-path image.wit --world processor componentize app.py -o app.wasm

# 4. 用 wac 将两个组件组合
# wac compose pipeline.wac -o pipeline.wasm

# 5. 用 wasmtime 运行最终组件
# wasmtime run pipeline.wasm

本章小结