第 27 篇把 Sprout 的标量子集编译成了一个独立的 .wasm 核心模块。模块能在 Wasmtime 里跑起来，但它的边界只有导出函数的数字签名——调用者必须自己知道哪个参数是长度、哪个是指针偏移、返回值代表什么。换句话说，核心模块没有类型化的接口描述，就像 C 的 .o 文件没有头文件。

WIT（WebAssembly Interface Types）正是给 Wasm 组件补上的这层头文件。它用一种独立的接口定义语言描述组件的导入和导出：函数签名、参数类型、返回类型、记录、枚举、列表。两个组件通过 WIT 约定的接口互相调用，运行时在边界处自动完成类型验证和数据格式转换。组件之间不共享线性内存，也不需要知道对方的内部布局。

这篇要做的事情：给 Sprout 的统计函数写一份 WIT 接口定义，用工具把核心模块封装成组件，再把它和一个提供文件读取能力的宿主组件接到一起。

WIT 的基本结构

第 27 篇使用 wasm32-wasi（WASI preview 1）编译核心模块。本篇切换到 wasm32-wasip2（WASI preview 2），因为组件模型是 WASI preview 2 的核心特性——preview 1 只有核心模块，没有类型化的组件边界。

一份 WIT 文件由 package、interface 和 world 三层组成。

在使用列表接口之前，我们先用一个最简单的标量接口验证组件化流程：

1
2
3
4
5
6
7
8
9
package sprout:math@0.1.0;

interface calc {
    add: func(a: s64, b: s64) -> s64;
}

world calculator {
    export calc;
}

这个接口不涉及线性内存布局——两个 s64 参数直接映射为 Wasm 的 i64，返回值同理。走通这个最小例子后，再扩展到 list<s64> 时就能清楚地看到 Canonical ABI 为复杂类型增加了什么。

下面看一个使用列表类型的完整例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
package sprout:stats@0.1.0;

interface statistics {
    sort: func(data: list<s64>) -> list<s64>;
    min:  func(data: list<s64>) -> s64;
    max:  func(data: list<s64>) -> s64;
    mean: func(data: list<s64>) -> s64;
}

interface file-io {
    read-numbers: func(path: string) -> result<list<s64>, string>;
}

world stats-app {
    import file-io;
    export statistics;
}

package 声明命名空间和版本号，格式是 namespace:name@semver。interface 块定义一组带类型签名的函数。world 把多个 interface 组合在一起，用 import 和 export 区分组件需要什么、提供什么。

WIT 的类型系统比核心 Wasm 丰富得多。核心 Wasm 只认识 i32、i64、f32、f64；WIT 增加了 string、list<T>、option<T>、result<T, E>、record、enum、variant、tuple、flags 等。这些高级类型最终会被拆解成核心 Wasm 能处理的整数和内存操作——这个拆解过程叫 Canonical ABI。

WIT 的语法参考见 Component Model 官方文档。注意 WIT 中的标识符用 kebab-case（如 read-numbers），不用下划线或驼峰。

组件模型：核心模块加类型外壳

核心 Wasm 模块（.wasm）只有低级类型签名。Wasm 组件在核心模块外面包了一层类型信息，这层信息来自 WIT 定义。组件的结构大致是：

1
2
3
4
5
6
7
8
9
10
11
Wasm Component
├── Component Type (from WIT)
│   ├── imports: file-io.read-numbers
│   └── exports: statistics.sort, .min, .max, .mean
├── Core Module (第 27 篇的 .wasm)
│   ├── core export: _sort(ptr, len) -> (ptr, len)
│   ├── core export: _min(ptr, len) -> i64
│   └── ...
└── Canonical ABI adapters
    ├── lift: core (_sort) -> component (sort)
    └── lower: component (read-numbers) -> core (_read_numbers)

关键区别：核心模块的 _sort 接受内存指针和长度，返回指针和长度；组件的 sort 接受 list<s64>，返回 list<s64>。Canonical ABI adapter 负责在两者之间转换——把宿主传来的列表数据复制到核心模块的线性内存，把核心模块输出的内存区域包装成列表交还宿主。

组件之间不共享线性内存。每个组件拥有自己的内存空间，数据通过 Canonical ABI 在边界处复制。这消除了一类安全问题：一个组件不能意外或恶意地修改另一个组件的内部状态。

这种隔离在传统的动态链接库中是做不到的。共享库（.so/.dll）和主程序共享地址空间，一个越界写入就能破坏另一个库的数据结构。组件模型从架构层面阻止了这种情况。代价是边界处的数据复制——每次跨组件调用传递列表时，数据会被序列化到调用者的线性内存中再反序列化到被调用者的线性内存中。对于大量数据的高频传递，这个开销不可忽略。但对 Sprout 的统计场景（一次性传入一个数组，计算后返回结果），复制成本远低于计算本身。

Canonical ABI 的转换规则是确定性的，不依赖运行时协商。编译时就能确定每种类型在线性内存中的布局：s64 占 8 字节，list<s64> 用一个指针加一个长度表示，string 是 UTF-8 字节序列加长度，record 的字段按声明顺序排列并遵循对齐规则。这些规则在组件模型规范中有完整定义，工具链（wit-bindgen、wasm-tools）替你处理所有细节。开发者需要理解的核心概念只有一个：WIT 类型是语义层面的类型，核心 Wasm 类型是机器层面的类型，Canonical ABI 是两者之间的确定性映射。掌握了这三层关系，组件模型的大部分行为就能预测了。后续如果需要调试边界处的数据不一致问题，也知道该从哪一层入手排查。

定义 Sprout 统计组件的接口

在项目中创建 wit/ 目录，放入上面的 WIT 定义：

1
2
3
examples/build-a-compiler/
└── wit/
    └── stats.wit

stats.wit 的内容就是前面给出的那份。world stats-app 说的是：这个组件需要外部提供 file-io 接口中的 read-numbers 函数，自身导出 statistics 接口中的四个统计函数。

这份 WIT 做了一个设计选择：统计函数接受 list<s64> 而不是文件路径。读文件的职责交给宿主通过 file-io 提供。这样 Sprout 组件本身是纯计算的——它不需要文件系统权限，只操作传入的数据。权限最小化是组件模型的一个核心设计目标。

从 WIT 生成 Rust 胶水代码

有了 WIT 定义，下一步是生成 Rust 代码，把 Sprout 编译出来的核心 Wasm 函数包装成符合 WIT 签名的组件导出。这里使用 wit-bindgen 工具。

在 Cargo.toml 中加入依赖：

1
2
[dependencies]
wit-bindgen = "0.36.0"  # 2024-11-27 发布

本篇示例使用 wit-bindgen = "0.36.0"（2024-11-27 发布）。wit-bindgen 的 API 在版本间变化较大，建议读者使用与所安装 wasmtime 版本匹配的 wit-bindgen 版本。最新版本号见 crates.io。

在 Rust 源码中使用 generate! 宏：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
wit_bindgen::generate!({
    world: "stats-app",
    path: "wit/stats.wit",
});

struct SproutStats;

impl Guest for SproutStats {
    fn sort(data: Vec<i64>) -> Vec<i64> {
        // 调用 Sprout 编译出的排序函数
        // 胶水层负责：Vec<i64> -> 线性内存 (ptr, len) -> 调用核心函数 -> 结果 -> Vec<i64>
        let mut buf = data;
        sprout_core::insertion_sort(&mut buf);
        buf
    }

    fn min(data: Vec<i64>) -> i64 {
        sprout_core::find_min(&data)
    }

    fn max(data: Vec<i64>) -> i64 {
        sprout_core::find_max(&data)
    }

    fn mean(data: Vec<i64>) -> i64 {
        sprout_core::compute_mean(&data)
    }
}

export!(SproutStats);

generate! 宏读取 WIT 文件，生成 Guest trait，里面的方法签名直接对应 WIT 中 statistics 接口的函数。实现者填入具体逻辑，export! 宏生成 Canonical ABI 所需的低级导出函数。

生成的底层代码大致做这些事情：

  1. Lifting（提升）：把核心模块的 (ptr, len) 返回值读出线性内存，构造成 list<s64>。
  2. Lowering（降低）：把调用者传来的 list<s64> 写入核心模块的线性内存，转换成 (ptr, len) 参数。
  3. 内存管理：调用核心模块导出的 cabi_realloc 函数分配和释放中间缓冲区。

编译目标仍然是 wasm32-wasip2：

1
cargo build --target wasm32-wasip2 --release

产物是一个 Wasm 组件文件，不再是普通的核心模块。可以用 wasm-tools component wit 检查它的类型信息：

1
wasm-tools component wit target/wasm32-wasip2/release/sprout_stats.wasm

输出应该能看到 statistics 接口的四个函数签名和 file-io 的导入声明。如果类型信息缺失，说明 generate! 宏没有正确处理，或者编译目标不对。

组合组件：宿主提供文件读取

Sprout 组件导入了 file-io，需要有人提供这个能力。在 Wasmtime 的 Rust 嵌入 API 中，宿主程序可以在组件链接阶段注入导入函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
use wasmtime::component::*;
use wasmtime::{Config, Engine, Store};

fn main() -> anyhow::Result<()> {
    let mut config = Config::new();
    config.wasm_component_model(true);
    let engine = Engine::new(&config)?;

    let component = Component::from_file(
        &engine,
        "target/wasm32-wasip2/release/sprout_stats.wasm",
    )?;

    let mut linker = Linker::new(&engine);

    // 宿主实现 file-io 接口
    linker.instance("file-io")?.func_wrap(
        "read-numbers",
        |_store: StoreContextMut<'_, ()>, (path,): (String,)|
         -> Result<(Result<Vec<i64>, String>,)> {
            let content = std::fs::read_to_string(&path)
                .map_err(|e| e.to_string())?;
            let numbers: Result<Vec<i64>, _> = content
                .lines()
                .filter(|l| !l.trim().is_empty())
                .map(|l| l.trim().parse::<i64>())
                .collect();
            match numbers {
                Ok(ns) => Ok((Ok(ns),)),
                Err(e) => Ok((Err(e.to_string()),)),
            }
        },
    )?;

    let mut store = Store::new(&engine, ());
    let instance = linker.instantiate(&mut store, &component)?;

    // 调用 Sprout 组件导出的统计函数
    let sort_fn = instance.get_typed_func::<(Vec<i64>,), (Vec<i64>,)>(
        &mut store, "sort"
    )?;
    let min_fn = instance.get_typed_func::<(Vec<i64>,), (i64,)>(
        &mut store, "min"
    )?;

    let data = vec![5, 3, 8, 1, 9, 2, 7, 4, 6];
    let (sorted,) = sort_fn.call(&mut store, (data.clone(),))?;
    let (minimum,) = min_fn.call(&mut store, (data.clone(),))?;

    println!("sorted: {:?}", sorted);
    println!("min: {}", minimum);

    Ok(())
}

注意 linker.instance("file-io") 和 func_wrap("read-numbers", ...) 的名字必须和 WIT 中的 interface 名、函数名完全匹配。类型也必须匹配——如果 WIT 写的是 result<list<s64>, string>，宿主函数的返回类型就必须是 Result<Vec<i64>, String>。Wasmtime 在实例化时验证这些类型，不匹配就报错。

类型安全的边界

组件模型在边界处做的类型检查值得展开说明。

假设 WIT 定义 sort 接受 list<s64>，但调用方试图传入一组浮点数。在核心 Wasm 的世界里，这种错误不会被拦截——内存里的字节按什么类型解释完全取决于调用约定。但在组件模型中，Canonical ABI 会在数据复制到目标组件之前验证类型。传入的每个元素必须是合法的 s64，否则实例化或调用阶段就会失败。

再看一个更微妙的场景。read-numbers 返回 result<list<s64>, string>。如果宿主实现返回了 Ok 变体但里面的列表包含无效数据（比如超出 s64 范围），Canonical ABI 同样会拦截。组件模型不信任任何一方——即使数据来自宿主，也要在进入目标组件前经过验证。

这种边界检查的代价是数据复制。每次跨组件调用，列表数据都要从源组件的线性内存复制到目标组件的线性内存。对于大数组来说，这是可以观察到的开销。未来的组件模型规范可能引入共享内存或引用传递的优化，但当前版本的设计选择是安全优先。

测试：用 mock 组件验证端到端流程

不依赖真实文件系统来测试 Sprout 组件。写一个 mock 宿主，它的 read-numbers 返回硬编码数据：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
#[test]
fn test_sprout_component_with_mock() {
    let engine = /* ... 同上 ... */;
    let component = Component::from_file(&engine, SPROUT_WASM)?;
    let mut linker = Linker::new(&engine);

    // mock: 无论传什么路径，都返回固定数据
    linker.instance("file-io")?.func_wrap(
        "read-numbers",
        |_store, (_path,): (String,)|
         -> Result<(Result<Vec<i64>, String>,)> {
            Ok((Ok(vec![10, -3, 7, 0, 5]),))
        },
    )?;

    let mut store = Store::new(&engine, ());
    let instance = linker.instantiate(&mut store, &component)?;

    let sort_fn = instance
        .get_typed_func::<(Vec<i64>,), (Vec<i64>,)>(&mut store, "sort")?;
    let min_fn = instance
        .get_typed_func::<(Vec<i64>,), (i64,)>(&mut store, "min")?;
    let max_fn = instance
        .get_typed_func::<(Vec<i64>,), (i64,)>(&mut store, "max")?;
    let mean_fn = instance
        .get_typed_func::<(Vec<i64>,), (i64,)>(&mut store, "mean")?;

    let data = vec![10, -3, 7, 0, 5];
    let (sorted,) = sort_fn.call(&mut store, (data.clone(),))?;
    assert_eq!(sorted, vec![-3, 0, 5, 7, 10]);

    let (min,) = min_fn.call(&mut store, (data.clone(),))?;
    assert_eq!(min, -3);

    let (max,) = max_fn.call(&mut store, (data.clone(),))?;
    assert_eq!(max, 10);

    let (avg,) = mean_fn.call(&mut store, (data.clone(),))?;
    // (10 + (-3) + 7 + 0 + 5) / 5 = 19 / 5 = 3（向零截断）
    assert_eq!(avg, 3);
}

如果 mock 故意返回 Err("not found")，Sprout 组件内部的逻辑需要处理这个错误变体。这也是 result 类型存在的意义——它把错误路径写进了接口契约。

再做一个故意类型不匹配的实验。把 WIT 改成 list<s32> 但宿主仍然传 Vec<i64>，Wasmtime 在链接阶段就会报类型不匹配的错误，不会进入运行时。

如果实例化组件时不提供必需的导入，Wasmtime 会明确报错：

1
2
Error: import `file-io` has the wrong type
    Caused by: expected func found nothing

这正是组件模型的类型安全保证——与核心 Wasm 模块在运行时才发现缺少导入不同，组件在实例化阶段就拒绝不完整的组合。

工具链命令汇总

从核心模块到组件的完整流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 编译 Sprout 核心模块（第 27 篇）
cargo run --locked -- build programs/stats.spr --target wasm32 -o target/stats_core.wasm

# 2. 编译带 WIT 绑定的组件包装
cargo build --target wasm32-wasip2 --release -p sprout-stats-component

# 3. 检查组件的 WIT 类型信息
wasm-tools component wit target/wasm32-wasip2/release/sprout_stats.wasm

# 4. 运行宿主程序，组合宿主和 Sprout 组件
cargo run --release -p stats-host -- numbers.txt

# 5. 运行测试
cargo test -p stats-host

其中 wasm-tools 来自 bytecodealliance/wasm-tools，是检查和操作 Wasm 组件的标准工具。如果第 3 步输出中看不到 statistics 接口，说明组件封装没有正确完成。

练习

  1. 写一份 WIT 接口定义，为一个 calculator 组件导出 add、sub、mul、div 四个函数，每个接受两个 s64 参数并返回 s64。div 的返回类型改为 result<s64, string> 以处理除零。用 Sprout 编译的算术运算实现这个组件，再写一个宿主程序调用它，打印 add(10, 20)、div(10, 0) 的结果。

  2. 在 Sprout 统计组件的 WIT 中增加一个 record：

    1
    2
    3
    4
    5
    6
    7
    8
    record summary {
        sorted: list<s64>,
        min: s64,
        max: s64,
        mean: s64,
    }

    compute-all: func(data: list<s64>) -> summary;

    实现 compute-all，让宿主只调用一次就拿到全部统计结果。观察 record 在 Canonical ABI 中如何被展平成多个核心 Wasm 参数。

  3. 用 wasm-tools component wit 对比第 27 篇的核心模块和本篇的组件文件。核心模块是否输出了任何 WIT 信息？这个差异说明了核心模块和组件的本质区别。

上一篇：27 - 编译到 WebAssembly。下一篇：29 - MLIR 入门：定义 Sprout 方言。