Rust + WebAssembly 全链路解析

第14章 组件模型：可组合的 WASM 架构

作者 杨艺韬 · 16,356 字 · 发布于 · 更新于

"The whole is greater than the sum of its parts." — Aristotle

14.1 为什么需要组件模型

WASM MVP 规范定义的模块（Module）是一个功能封闭的单元：它导入和导出 i32/i64/f32/f64 类型的函数，通过线性内存交换数据。两个不同语言编写的 .wasm 模块要互操作，只能在线性内存中传递字节——和 C ABI 一样原始。

这不是一个抽象的问题——它直接阻止了 WASM 成为"通用软件单元"：

Python 编译的 WASM 模块不能调用 Rust 编译的 WASM 模块的 String 参数函数——因为两者的 String 内存布局不同。Go 的 WASM 模块不能调用 C++ 的 WASM 模块的 std::vector——Go 的 vector 和 C++ 的 vector 是不同的类型。JavaScript 的 WASM 模块想把一个 JSON 对象传给 Rust 的 WASM 模块，只能手动序列化成字节——两边各自解析，各自处理对齐和字节序。

graph TD
  subgraph "没有组件模型：线性内存交换"
    A[Rust 模块] -->|"i32 指针 + i32 长度"| B[Python 模块]
    C[Go 模块] -->|"i32 指针 + i32 长度"| D[C++ 模块]
    Note1["每种语言有自己的<br/>内存布局约定<br/>手动协商极易出错"]
  end
  subgraph "有组件模型：WIT 接口类型"
    E[Rust 组件] -->|"WIT: string"| F[Python 组件]
    G[Go 组件] -->|"WIT: list&lt;u8&gt;"| H[C++ 组件]
    Note2["Canonical ABI 规范化<br/>内存布局<br/>自动编解码"]
  end
  style A fill:#ef4444,color:#fff
  style B fill:#ef4444,color:#fff
  style C fill:#ef4444,color:#fff
  style D fill:#ef4444,color:#fff
  style E fill:#10b981,color:#fff
  style F fill:#10b981,color:#fff
  style G fill:#10b981,color:#fff
  style H fill:#10b981,color:#fff

组件模型的目标：定义一种语言无关的接口类型系统，让不同语言编写的 WASM 组件可以通过高级类型（字符串、列表、记录、变体）互操作，而不需要手动处理内存布局。

这个目标背后是 WASM 的核心愿景——WASM 不只是一个编译目标，而是一个虚拟指令集架构（virtual ISA）。就像 x86_64 上的 C ABI 让 C/Rust/Go/Python 可以通过 FFI 互操作，WASM 的组件模型定义了跨语言的"虚拟 ABI"——Canonical ABI。

14.2 组件模型规范的核心概念

组件与核心模块的关系

组件（Component）是核心模块（Core Module）的包装。核心模块就是 WASM MVP 定义的 .wasm——它只有 i32/i64/f32/f64 类型的导入导出。组件在核心模块外包了一层封装，把低级的 i32 参数/返回值提升（lift）为高级的 WIT 类型（string、list<u8>、result<T, E>），把高级类型降级（lower）回 i32 参数。

flowchart TD
  subgraph "组件（Component）"
    A["导入: wasi:cli/environment<br/>（WIT 类型签名）"]
    B["导出: calculator:calculator<br/>（WIT 类型签名）"]
    C["Canon Section:<br/>Canonical ABI 适配器"]
    D["Core Module Section:<br/>裸 .wasm 模块"]
  end
  A --> C
  B --> C
  C --> D
  C -->|"lower: string → (ptr, len)"| D
  D -->|"lift: (ptr, len) → string"| C
  style C fill:#f59e0b,color:#fff
  style D fill:#6366f1,color:#fff

lift 和 lower 是组件模型的两个核心操作：

  • lower：把 WIT 类型转换为核心 WASM 值。例如 string → (i32 ptr, i32 len)，list<u8> → (i32 ptr, i32 len)，f64 → f64（值类型直接传递）
  • lift：把核心 WASM 值转换回 WIT 类型。例如 (i32 ptr, i32 len) → string，i32 handle → resource

组件的二进制格式在核心模块的 .wasm 外增加了多个段（section）：

Component ::= magic + version
              section*

// 组件段类型：
// - Type Section:      WIT 接口类型声明
// - Import Section:    导入的接口（WIT 类型签名）
// - Export Section:    导出的接口（WIT 类型签名）
// - Core Module Section:  内嵌的裸 .wasm 核心模块
// - Instance Section:  实例化内嵌模块
// - Alias Section:     别名（跨实例引用导出）
// - Canon Section:     Canonical ABI 适配器（lift/lower 规则）

Canon Section 是组件格式的核心——它定义了 WIT 类型到核心 WASM 类型的映射规则。Canonical ABI 规定了 string 如何在线性内存中布局、list<T> 如何传递、resource 的生命周期如何管理。

14.3 WIT：WebAssembly 接口类型语言

WIT（WebAssembly Interface Types）是组件模型的接口定义语言——它用声明式语法定义组件之间的接口契约。WIT 不是一个编程语言——它不包含实现逻辑，只描述"接口长什么样"。

接口（Interface）

接口是一组类型和函数的声明：

// calculator.wit
interface calculator {
    record expression {
        left: f64,
        operator: operator,
        right: f64,
    }

    enum operator {
        add,
        subtract,
        multiply,
        divide,
    }

    variant error {
        division-by-zero,
        overflow(string),
        invalid-expression(string),
    }

    eval: func(expr: expression) -> result<f64, error>;

    resource history {
        add: func(expr: expression, result: f64) -> void;
        last: func() -> option<expression>;
        clear: func() -> void;
    }
}

WIT 的类型系统比 WASM MVP 的 i32/i64/f32/f64 丰富得多——它提供了现代编程语言常见的类型构造：

WIT 类型 Rust 映射 Python 映射 说明
u8…u64 u8…u64 int 无符号整数
s8…s64 i8…i64 int 有符号整数
f32, f64 f32, f64 float 浮点
bool bool bool 布尔
char char str（单字符） Unicode 标量值
string String str UTF-8 字符串
list<T> Vec<T> list[T] 列表
tuple<T, U> (T, U) tuple[T, U] 元组
record { ... } struct dataclass 记录/结构体
variant { ... } enum（带数据） Union 变体/联合
enum { ... } C-like enum Enum 简单枚举
option<T> Option<T> Optional[T] 可空
result<T, E> Result<T, E> Union[T, E] 结果
resource struct + impl class 有方法和生命周期的类型
flags bitflags IntFlag 位标志集合

注意 variant 和 enum 的区别：enum 是简单枚举（无关联数据），variant 是带关联数据的标签联合——和 Rust 的 enum 等价。WIT 把它们分开是因为很多语言（C、Go）的 enum 不支持关联数据。

世界（World）

世界定义一个组件的完整接口——它导入什么、导出什么。世界是组件的"契约"：

// calculator-world.wit
world calculator-app {
  // 导入：需要宿主或另一个组件提供的能力
  import wasi:cli/exit;
  import wasi:filesystem/types;
  import logging:logging;

  // 导出：本组件提供给消费者的能力
  export calculator:calculator;
  export version: func() -> string;
}

世界是组件实例化的前提——Wasmtime 在实例化组件时，必须为每个 import 提供实现，才能成功实例化。缺少任何一个导入，实例化都会失败。

graph TD
  subgraph "World: calculator-app"
    A["import wasi:cli/exit"] --> C[组件实现]
    B["import logging:logging"] --> C
    D["import wasi:filesystem/types"] --> C
    C --> E["export calculator:calculator"]
    C --> F["export version() -> string"]
  end
  style C fill:#6366f1,color:#fff
  style A fill:#f59e0b,color:#fff
  style B fill:#f59e0b,color:#fff
  style D fill:#f59e0b,color:#fff
  style E fill:#10b981,color:#fff
  style F fill:#10b981,color:#fff

世界的设计体现了一个重要原则：依赖即能力声明。组件声明 import wasi:filesystem/types，意味着它需要文件系统能力。宿主可以审查这个声明，决定是否授权——如果组件声称只是计算器却导入了文件系统，这就是一个安全信号。

包（Package）

包是 WIT 的命名空间单元——它把接口和世界组织到一个可版本化的单元中：

package example:calculator@1.0.0;

interface calculator { ... }
world calculator-app { ... }

包名遵循 namespace:name@version 格式——namespace 是组织名，name 是包名，version 是语义化版本。WASI 的所有接口都在 wasi 命名空间下：wasi:cli、wasi:filesystem、wasi:http 等。

包的版本化设计支持渐进演进——example:calculator@1.0.0 和 example:calculator@2.0.0 可以共存，消费者按版本引用。这解决了 WASI Preview 1 的"单体不可版本化"问题——Preview 2 的每个接口包可以独立版本化。

14.4 Canonical ABI：接口类型的内存布局

Canonical ABI 是组件模型的关键规范——它定义了 WIT 类型在线性内存中的精确布局，让不同语言的实现可以互操作。没有 Canonical ABI，每个语言的运行时会按自己的约定编码字符串和列表——互操作不可能。

字符串的 Canonical ABI

string 在线性内存中的布局:

地址      内容
ptr       ┌─────────────────────┐
          │ UTF-8 字节序列        │  ← len 字节
          │ ...                   │
          └─────────────────────┘

函数参数传递（lower）:
  参数 1: ptr (i32)   — 字符串起始地址
  参数 2: len (i32)   — 字节长度

返回值传递（lift）:
  返回值 1: ptr (i32)  — 字符串在线性内存中的地址
  返回值 2: len (i32)  — 字节长度

字符串按 UTF-8 编码存储在线性内存中，通过 (ptr, len) 对传递。这和 wasm-bindgen 的字符串传递方式几乎一样——但 Canonical ABI 是规范化的、语言无关的。任何语言的 wit-bindgen 生成器都会按这个布局编码/解码字符串。

一个关键细节：字符串的内存所有权。当组件导出函数返回一个 string 时，Canonical ABI 规定调用者（消费者）拥有返回的线性内存——消费者负责在读取完毕后释放这块内存。这避免了内存泄漏——每次调用都有明确的所有权转移。

列表的 Canonical ABI

list<T> 在线性内存中的布局:

地址      内容
ptr       ┌─────────────────────┐
          │ T[0]                 │  ← align(T) 对齐
          │ T[1]                 │
          │ ...                   │
          │ T[len-1]             │
          └─────────────────────┘

函数参数传递（lower）:
  参数 1: ptr (i32)   — 列表起始地址
  参数 2: len (i32)   — 元素数量

列表的布局和字符串类似——连续的元素序列，通过 (ptr, len) 传递。元素按自身对齐要求对齐。对于 list<u8>，每个元素 1 字节无对齐要求；对于 list<f64>，每个元素 8 字节且 8 字节对齐——中间可能有 padding。

记录（record）的 Canonical ABI

record point {
    x: f64,
    y: f64,
}

record user {
    name: string,
    age: u32,
    active: bool,
}
point 在线性内存中的布局:

偏移 0:  x (f64, 8 bytes, align 8)
偏移 8:  y (f64, 8 bytes, align 8)
总计: 16 bytes, 对齐: 8

user 在线性内存中的布局:

偏移  0: name.ptr  (i32, 4 bytes, align 4)
偏移  4: name.len  (i32, 4 bytes)
偏移  8: age       (u32, 4 bytes)
偏移 12: active    (bool, 1 byte)
偏移 13: padding   (3 bytes, 对齐到 4)
总计: 16 bytes, 对齐: 4

字段按声明顺序排列，每个字段按自身对齐要求对齐，末尾填充到整体对齐。和 C 的 struct 布局规则一致——但 Canonical ABI 的对齐规则是规范化的，不依赖编译器的 repr(C) 或 repr(Rust)。

Variant 和 Result 的 Canonical ABI

variant shape {
    circle(f64),
    rectangle(tuple<f64, f64>),
    triangle(list<f64>),
}

result<f64, string>
variant shape 在线性内存中的布局:

偏移 0:  discriminant (i32)   — 0=circle, 1=rectangle, 2=triangle
偏移 4:  padding              — 对齐到 max(align(各变体的 payload))
偏移 N:  payload              — 最大变体的 payload 大小（联合体）

  circle:    discriminant=0, payload=f64 (8 bytes)
  rectangle: discriminant=1, payload=(f64, f64) (16 bytes)
  triangle:  discriminant=2, payload=(ptr, len) (8 bytes)

payload 大小 = max(8, 16, 8) = 16 bytes
总计 = 4 (discriminant) + 4 (padding) + 16 (payload) = 24 bytes

result<f64, string> 在线性内存中的布局:

偏移 0:  discriminant (i32)   — 0=ok, 1=err
偏移 4:  payload              — T 或 E，只占用一份空间（联合体）

  OK 情况:  discriminant=0, payload=f64 (8 bytes)
  ERR 情况: discriminant=1, payload=(ptr, len) for string (8 bytes)

注意：result 的 payload 是联合体——OK 和 ERR 共享同一块内存空间。这和 Rust 的 Result 布局一致（Rust 的 Result<T, E> 也是用 discriminant + 联合体表示），但 Canonical ABI 规范化了 discriminant 的大小（总是 i32，即 4 字节）和位置（总是在偏移 0）。

Canonical ABI 的调用约定汇总

flowchart LR
  subgraph "消费者（调用方）"
    A["WIT: eval(expr: expression) -> result&lt;f64, error&gt;"]
  end
  subgraph "lower（消费者→核心模块）"
    B["把 expression 写入线性内存<br/>传递 (ptr, len) 作为 i32 参数"]
  end
  subgraph "核心模块（被调用方）"
    C["fn export_eval(ptr: i32, len: i32) -> i32<br/>从线性内存读取 expression<br/>计算结果<br/>把 result&lt;f64, error&gt; 写入线性内存<br/>返回 (ret_ptr, ret_len)"]
  end
  subgraph "lift（核心模块→消费者）"
    D["从线性内存读取 result<br/>转换为 WIT 类型 result&lt;f64, error&gt;"]
  end
  A --> B --> C --> D
  style B fill:#f59e0b,color:#fff
  style C fill:#6366f1,color:#fff
  style D fill:#f59e0b,color:#fff

与 Serde 的对比

Canonical ABI 和《Serde 元编程》第 4 章的 #[derive(Serialize, Deserialize)] 解决的是同一类问题——"类型到字节序列的规范化转换"：

  • Serde：Rust 类型 → Serializer trait → JSON/Bincode/MessagePack 等格式——用于 Rust 内部的序列化
  • Canonical ABI：WIT 类型 → 线性内存布局 ——用于跨语言边界的类型传递

关键差异：Serde 的输出格式是可选择的（JSON 是文本格式、Bincode 是二进制格式），Canonical ABI 的输出格式是规范化的（没有选择余地——每种 WIT 类型只有一种内存布局）。这是因为 Serde 的消费者通常是同语言的（Rust 写入 → Rust 读取），而 Canonical ABI 的消费者可以是任意语言——标准化比灵活性更重要。

另一个差异：Serde 的 Serializer/Deserializer 是 trait——通过泛型分派实现零开销抽象。Canonical ABI 的 lift/lower 是编译时生成的代码——通过 wit-bindgen 过程宏展开，和手写代码一样高效。

14.5 组件组合：从多个组件构建应用

组件模型的核心价值——多个独立开发的组件可以通过 WIT 接口连接，而不需要知道彼此的实现语言。

组件链接的模型

graph TD
  A["组件 A: 日志服务<br/>export logging:logging"] -->|"logging:logging"| B["组件 B: 计算器<br/>import logging:logging<br/>export calculator:calculator"]
  B -->|"calculator:calculator"| C["宿主应用<br/>import calculator:calculator"]
  style A fill:#6366f1,color:#fff
  style B fill:#22d3ee,color:#fff
  style C fill:#10b981,color:#fff

组件 B 声明 import logging:logging——它不关心日志服务是 Rust 写的、Python 写的还是 Go 写的。它只关心日志服务导出了 logging:logging 接口——有 log(message: string, level: log-level) 函数。Wasmtime 在实例化组件 B 时，必须为这个导入提供一个实现——可以来自组件 A 的导出，也可以来自宿主的内建实现。

Wasmtime 的组合实例化

use wasmtime::*;
use wasmtime_wasi::preview2::command::WasiCtxBuilder;

async fn run_composed() -> Result<()> {
    let engine = Engine::default();
    let mut linker = Linker::new(&engine);

    // 1. 注册 WASI 实现
    wasmtime_wasi::preview2::command::add_to_linker(&mut linker)?;

    // 2. 加载日志组件
    let logger_component = Component::from_file(&engine, "logger.wasm")?;
    let wasi = WasiCtxBuilder::new().inherit_stdout().build();
    let mut store = Store::new(&engine, wasi);
    let logger_instance = linker.instantiate_async(&mut store, &logger_component).await?;

    // 3. 把日志组件的导出注入 linker，供后续组件使用
    linker.instance(&mut store, "logging", logger_instance)?;

    // 4. 加载计算器组件——它会自动链接到日志组件
    let calc_component = Component::from_file(&engine, "calculator.wasm")?;
    let wasi2 = WasiCtxBuilder::new().inherit_stdout().build();
    let mut store2 = Store::new(&engine, wasi2);
    let calc_instance = linker.instantiate_async(&mut store2, &calc_component).await?;

    // 5. 调用计算器的导出
    let calc = calc_instance
        .get_typed_func::<(f64, f64), f64>(&mut store2, "eval")?;
    let result = calc.call_async(&mut store2, (1.0, 2.0)).await?;
    println!("Result: {}", result);

    Ok(())
}

关键：步骤 3 把日志组件的导出注册到 linker——后续的计算器组件实例化时，Wasmtime 自动把 import logging:logging 链接到日志组件的 export logging:logging。这就是组件组合——两个独立开发的组件通过接口契约连接，不需要知道彼此的内部实现。

组合的类型安全保证

组件模型保证了组合的类型安全——这和动态语言中的"鸭子类型"接口有本质区别。

当 Wasmtime 尝试把组件 A 的导出链接到组件 B 的导入时，它会检查：

  1. 接口名匹配：A 导出的接口名必须和 B 导入的接口名完全一致（包括命名空间）
  2. 类型签名匹配：函数参数类型和返回类型必须完全一致
  3. 资源类型匹配：如果接口中包含 resource，resource 的方法签名必须一致

任何一个不匹配，实例化都会失败——错误发生在启动时，而不是运行时的某个奇怪调用路径上。这和 Rust 的 trait bound 在编译时检查类型安全是同一个思路——但组件模型的检查发生在组件实例化时（因为组件是二进制级别的组合，不是源码级别的组合）。

14.6 组件注册表：warg

组件组合需要组件共享——需要一个类似 npm/crates.io 的包管理生态。warg（WebAssembly Package Registry）是字节码联盟开发的组件注册表协议和实现。

warg 的设计

warg 的核心概念：

  • 包（Package）：一组相关的组件和 WIT 定义，按语义化版本发布
  • 发布（Publish）：把组件二进制 + WIT 定义上传到注册表
  • 依赖（Dependency）：在 WIT 中引用另一个包的接口
# 安装 warg CLI
cargo install warg-cli

# 发布组件到注册表
warg publish my-calculator.wasm --name example:calculator --version 1.0.0

# 从注册表下载组件
warg download example:calculator@1.0.0

# 列出包的所有版本
warg list example:calculator

warg 的安全模型和 WASI 的能力安全一脉相承：

  • 签名验证：每个包由发布者的私钥签名，消费者验证签名——防止供应链篡改
  • 不可变性：已发布的版本不可修改——example:calculator@1.0.0 一旦发布，内容永远不变
  • 权限控制：包的命名空间有所有者——只有所有者可以发布新版本

warg 与其他包管理器的对比

维度 crates.io npm warg
语言 Rust JavaScript 语言无关（WASM 组件）
包格式 .crate（源码） .tgz（JS 源码） .wasm（组件二进制 + WIT）
类型检查 Rust 编译器 TypeScript（可选） WIT 接口（强制）
发布模型 不可变 不可变 不可变 + 签名验证
组合方式 编译时链接 运行时 require/import 运行时组件实例化

warg 的关键差异：它分发的是编译后的组件二进制——不是源码。这意味着消费者不需要编译组件——只需要下载 .wasm 文件并实例化。这降低了组合的门槛——Python 消费者不需要安装 Rust 工具链来使用 Rust 编写的组件。

warg 目前仍处于早期阶段——注册表服务尚未正式上线，但协议规范和 CLI 工具已可用。随着 WASI Preview 2 生态的成熟，warg 有望成为组件共享的标准基础设施。

14.7 实战：构建一个多语言组件系统

用一个完整的例子演示组件模型的跨语言互操作——Rust 实现核心逻辑，Python 实现业务规则，宿主用 Wasmtime 编排。

第一步：定义 WIT 接口

// wit/math.wit
package example:math@1.0.0;

interface core {
    factorial: func(n: u64) -> result<u64, error>;
    fibonacci: func(n: u64) -> result<u64, error>;
}

interface business {
    process-order: func(order-id: string, quantity: u64) -> result<string, error>;
}

world math-core {
    export core;
}

world business-logic {
    import core;
    export business;
}

math-core 世界导出 core 接口（数学计算）。business-logic 世界导入 core 接口（需要数学计算），导出 business 接口（业务逻辑）。

第二步：Rust 实现核心计算

// crates/math-core/src/lib.rs
use wit_bindgen::generate;
generate!("math-core");

use exports::example::math::core::Guest;

struct MathCore;

impl Guest for MathCore {
    fn factorial(n: u64) -> Result<u64, Error> {
        if n > 20 {
            return Err(Error::Overflow("Input too large".to_string()));
        }
        Ok((1..=n).product())
    }

    fn fibonacci(n: u64) -> Result<u64, Error> {
        if n > 93 {
            return Err(Error::Overflow("Input too large".to_string()));
        }
        let (mut a, mut b) = (0u64, 1u64);
        for _ in 0..n {
            let temp = a;
            a = b;
            b = temp + b;
        }
        Ok(a)
    }
}

export!(MathCore);

编译：

cd crates/math-core
cargo build --target wasm32-wasip2 --release
# 产物: target/wasm32-wasip2/release/math_core.wasm

第三步：Python 实现业务逻辑

Python 不能直接编译到 WASM 组件——但可以通过 Componentize.py 工具把 Python 代码包装成组件：

# crates/business-logic/main.py
from example.math.core import factorial, fibonacci
from example.math.business import Business, Error

class BusinessImpl(Business):
    def process_order(self, order_id: str, quantity: u64) -> Result[str, Error]:
        try:
            # 调用 Rust 实现的数学函数
            fact = factorial(quantity)
            fib = fibonacci(quantity)
            return f"Order {order_id}: factorial={fact}, fibonacci={fib}"
        except Exception as e:
            return Error("CalculationFailed", str(e))
# 用 componentize-py 把 Python 代码编译为 WASM 组件
componentize-py -d wit -w business-logic build -o business_logic.wasm main.py

第四步：Wasmtime 宿主编排

// src/main.rs
use wasmtime::*;
use wasmtime_wasi::preview2::command::WasiCtxBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    let engine = Engine::default();
    let mut linker = Linker::new(&engine);

    // 注册 WASI
    wasmtime_wasi::preview2::command::add_to_linker(&mut linker)?;

    // 实例化 Rust 数学核心组件
    let math_component = Component::from_file(&engine, "math_core.wasm")?;
    let wasi = WasiCtxBuilder::new().inherit_stdout().build();
    let mut store = Store::new(&engine, wasi);
    let math_instance = linker.instantiate_async(&mut store, &math_component).await?;

    // 把数学组件的导出注入 linker
    linker.instance(&mut store, "example:math/core", math_instance)?;

    // 实例化 Python 业务逻辑组件——自动链接到数学组件
    let biz_component = Component::from_file(&engine, "business_logic.wasm")?;
    let wasi2 = WasiCtxBuilder::new().inherit_stdout().build();
    let mut store2 = Store::new(&engine, wasi2);
    let biz_instance = linker.instantiate_async(&mut store2, &biz_component).await?;

    // 调用业务逻辑
    let process_order = biz_instance
        .get_typed_func::<(String, u64), Result<String, ()>>(&mut store2, "process-order")?;
    let result = process_order.call_async(&mut store2, ("ORD-001".to_string(), 10)).await??;
    println!("{}", result);
    // 输出: Order ORD-001: factorial=3628800, fibonacci=55

    Ok(())
}
flowchart TD
  subgraph "宿主 (Wasmtime)"
    A["main.rs<br/>编排两个组件"]
  end
  subgraph "组件 A: math-core (Rust)"
    B["factorial(10) → 3628800"]
    C["fibonacci(10) → 55"]
  end
  subgraph "组件 B: business-logic (Python)"
    D["process_order('ORD-001', 10)"]
    D -->|"import core"| B
    D -->|"import core"| C
    D --> E["'Order ORD-001: factorial=3628800, fibonacci=55'"]
  end
  A -->|"实例化"| B
  A -->|"实例化 + 链接"| D
  A -->|"调用 process_order"| D
  style A fill:#10b981,color:#fff
  style B fill:#6366f1,color:#fff
  style C fill:#6366f1,color:#fff
  style D fill:#22d3ee,color:#fff
  style E fill:#10b981,color:#fff

这个例子展示了组件模型的核心承诺——语言无关的互操作。Rust 组件提供高性能的数学计算，Python 组件提供灵活的业务逻辑，宿主用 Wasmtime 编排——三者通过 WIT 接口契约连接，不需要知道彼此的实现语言。

14.8 与 wasm-bindgen 的关系

组件模型和 wasm-bindgen 是两种不同的互操作方案——它们解决不同场景的问题：

维度 wasm-bindgen 组件模型
互操作对象 Rust ↔ JavaScript 任意语言 WASM ↔ 任意语言 WASM
类型系统 Rust 类型 → JS 类型 WIT 类型 → 多语言类型
内存管理 Rust 管理线性内存，JS 管理 GC 堆 Canonical ABI 统一管理
适配代码 JS 胶水代码 Canonical ABI + wit-bindgen
适用场景 浏览器 服务器/边缘/嵌入式
标准化 社区事实标准 W3C 规范（Phase 1）
类型检查 运行时（JS 是动态类型） 实例化时（WIT 是静态类型）

组件模型不会取代 wasm-bindgen——至少短期内不会。浏览器场景中，JS 仍然是宿主，wasm-bindgen 的 JS 胶水代码比 Canonical ABI 的适配层更高效（因为 JS 侧不需要经过额外的编解码步骤——直接操作 JS 值比从线性内存解码更便宜）。但组件模型为"非浏览器"场景提供了 wasm-bindgen 无法提供的语言无关互操作。

一个可能的发展方向：WASI Preview 3（计划添加组件模型的浏览器绑定提案）可能让组件模型在浏览器中也成为主流。但这需要浏览器引擎原生支持组件实例化和 Canonical ABI——目前 V8/SpiderMonkey/JavaScriptCore 都还没有实现。短期内，浏览器场景继续用 wasm-bindgen，服务器/边缘场景用组件模型，是最务实的选择。

14.9 资源类型的生命周期管理

WIT 的 resource 类型是组件模型中最复杂的概念——它代表有状态的、有生命周期的对象。理解资源的生命周期对于正确使用组件模型至关重要。

资源的本质

资源不是数据——它是句柄。一个 resource history 在 WIT 层面是一个不透明的句柄——消费者不知道它的内部表示，只能通过它的方法操作它。这和面向对象编程中的"对象"概念一致——但资源的跨语言传递需要规范化的句柄协议。

在 Canonical ABI 中，资源表示为一个 i32 句柄值——指向组件运行时维护的句柄表（handle table）。句柄表把 i32 映射到实际的实现对象：

flowchart TD
  subgraph "消费者组件"
    A["let h: History = History::new()"]
    B["h.add(expr, result)"]
    C["h.last()"]
    D["h.drop()"]
  end
  subgraph "句柄表（组件运行时）"
    E["handle 0 → MyHistory { entries: [...] }"]
    F["handle 1 → MyHistory { entries: [...] }"]
    G["handle 2 → TcpSocket { fd: 7 }"]
  end
  subgraph "实现组件（Rust）"
    H["MyHistory::new() → Self"]
    I["MyHistory::add(&self, ...)"]
    J["MyHistory::last(&self) → Option"]
    K["Drop for MyHistory"]
  end
  A -->|"分配句柄"| E
  B -->|"handle[0]"| I
  C -->|"handle[0]"| J
  D -->|"释放句柄"| K
  style E fill:#f59e0b,color:#fff
  style F fill:#f59e0b,color:#fff
  style G fill:#f59e0b,color:#fff

句柄表的安全保证

句柄表有几个关键的安全保证：

首先，句柄是不可伪造的。消费者组件只能通过组件的导出函数获取句柄——不能直接构造一个 i32 值假装是句柄。组件运行时会验证每个传入的句柄值是否存在于句柄表中。

其次，句柄是作用域化的。每个组件实例有独立的句柄表——组件 A 的句柄 0 和组件 B 的句柄 0 指向不同的对象。跨组件传递资源时，组件运行机会在两个句柄表之间做映射——源组件释放源句柄，目标组件分配新句柄。

再次，句柄的生命周期是确定的。当消费者调用 resource.drop（由 wit-bindgen 自动生成），组件运行时从句柄表移除条目，Rust 侧的 Drop::drop 被调用。如果消费者组件崩溃或退出，组件运行时自动释放所有未关闭的句柄——不会有资源泄漏。

资源与 wasm-bindgen 的对象栈对比

wasm-bindgen 的对象栈（第 6 章讨论的 __wbindgen_free + 索引映射）和组件模型的句柄表解决的是同一个问题——跨 WASM 边界管理有生命周期的对象。但两者有本质区别：

  • 对象栈是 wasm-bindgen 的实现细节——它的协议不在任何规范中，只有 wasm-bindgen 的 Rust 生成器和 JS 生成器能正确互操作
  • 句柄表是组件模型规范的一部分——它的协议在 Canonical ABI 中定义，任何语言的 wit-bindgen 生成器都能正确互操作

这意味着：用 wasm-bindgen 创建的 Rust 对象只能被 JS 消费者使用；用组件模型创建的 Rust 资源可以被 Python/C/Go 等任何语言的消费者使用——只要它们通过 WIT 接口访问。

14.10 组件模型的工具链生态

组件模型的实用性取决于工具链的成熟度。以下是当前可用的关键工具。

wasm-tools

wasm-tools 是字节码联盟维护的 WASM 工具集——包含组件模型的二进制操作工具：

# 验证组件格式
wasm-tools validate my_component.wasm

# 把核心模块转换为组件
wasm-tools component new my_module.wasm -o my_component.wasm

# 从组件中提取 WIT 定义
wasm-tools component wit my_component.wasm

# 把两个组件组合为一个
wasm-tools compose --component a.wasm --component b.wasm -o composed.wasm

wasm-tools component new 是最常用的命令——它把一个 Rust/C/Go 编译器产出的裸 .wasm 模块包装成组件。这个过程需要指定 WIT 定义和适配器——wasm-tools 根据 WIT 生成 Canonical ABI 适配器代码，嵌入到组件中。

wasm-component-ld

wasm-component-ld 是组件模型专用的链接器——它处理组件格式特有的链接需求，包括 Canonical ABI 适配器的生成和嵌入。当 cargo build --target wasm32-wasip2 时，Rust 编译器自动调用 wasm-component-ld 替代标准的 wasm-ld。

cargo-component

cargo-component 是 Rust 的 Cargo 子命令——它简化了 Rust 组件的开发流程：

# 安装
cargo install cargo-component

# 创建新组件项目
cargo component new my-calculator --lib

# 构建（自动处理 WIT 绑定和组件打包）
cargo component build

# 运行（使用 Wasmtime）
cargo component run

cargo component 的核心价值：它自动管理 WIT 定义和绑定代码的生成。开发者只需要在 src/lib.rs 中实现 WIT 定义的 trait——cargo component 在构建时自动调用 wit-bindgen 生成绑定代码，调用 wasm-component-ld 生成组件二进制。

14.11 组件模型的现状与未来

已完成（Phase 1，2024 年 2 月）

  • 二进制格式规范：组件的编码和解码规范已完成，Wasmtime 和 wasmtime-wave 实现了完整的编解码
  • WIT 语法规范：接口定义语言的语法和语义已稳定，支持 record/variant/enum/resource/flags 等类型
  • Canonical ABI 规范：类型到线性内存的映射规则已定义，包括字符串、列表、记录、变体、资源、result 的编码
  • wit-bindgen：支持 Rust、C、Python、Java、Go 等语言的绑定生成
  • Wasmtime 支持：完整的组件实例化和执行，包括 WASI Preview 2 的所有接口

进行中（Phase 2+）

  • 异步接口：WIT 的 async 函数语法——允许组件定义异步导出函数，消费者通过 stream/future 异步消费。这是 WASI Preview 3 的核心特性
  • 组件注册表：warg 协议和实现正在开发中——组件包管理的基础设施
  • 浏览器绑定：组件模型在浏览器中的 JS 互操作方案——让组件可以在浏览器中直接实例化，不需要 wasm-bindgen 的 JS 胶水代码

未开始（Phase 3+）

  • 跨组件事务：多个组件协同的事务支持——类似数据库事务的"全部成功或全部回滚"
  • 组件继承/组合语法：组件之间的继承和组合的标准化语法——类似面向对象的继承但跨语言
timeline
  title 组件模型演进时间线
  2019 : WASI Preview 1 发布<br/>fd-based API
  2022 : 组件模型草案发布<br/>WIT 语法初版
  2024 : 组件模型 Phase 1<br/>WASI Preview 2 发布<br/>Canonical ABI 规范完成
  2025 : wit-bindgen 多语言支持成熟<br/>warg 注册表开发中
  2026+ : Phase 2: 异步接口<br/>Phase 3: 浏览器绑定
  未来 : 跨组件事务<br/>组件继承/组合语法

14.12 组件版本演化：WIT 接口的兼容性管理

组件模型的"可组合"承诺有一个关键前提——接口契约稳定。如果 WIT 定义随意变更，组件之间的互操作就会破裂。WIT 借鉴了 Protobuf/gRPC 的演化经验，但在 WASM 场景下有独特的工程要求。

14.12.1 WIT 的语义版本规则

WIT 接口遵循语义化版本（SemVer）——版本号附在 package 声明上：

package example:math@1.2.3;

interface calculator {
    add: func(a: f64, b: f64) -> f64;
    subtract: func(a: f64, b: f64) -> f64;
}

兼容性规则：

变更类型 版本影响 示例
添加新 interface minor++ 1.0.0 → 1.1.0
添加 interface 中的新函数 minor++ 加 multiply
添加 record 的可选字段 minor++（视位置） 末尾加字段
改函数签名（增删参数） major++ add(a, b) → add(a, b, c)
改 record 字段类型 major++ f64 → f32
删除 interface/函数 major++ 移除 subtract
改 enum 变体顺序 major++ 影响 wire format

14.12.2 record 字段顺序的隐式契约

WIT 的 record 字段顺序在 Canonical ABI 中有效——和 C struct 一样，字段顺序决定内存布局。改顺序是破坏性变更：

// v1.0.0
record point {
    x: f64,
    y: f64,
}

// v1.1.0：调换顺序
record point {
    y: f64,  // 原本是 x 的位置
    x: f64,  // 原本是 y 的位置
}

二进制层面这是 major 变更——v1.0.0 的消费者读 v1.1.0 的 point 会把 x 当成 y。WIT 工具链当前不强制检查字段顺序，这是常见的隐性破坏点。生产中应该在 CI 加 lint 规则：record 字段顺序变更必须升 major。

14.12.3 多版本共存与适配器

组件 A 导入 math@1.0.0，组件 B 导出 math@2.0.0 —— 直接连接会失败。组件模型的解决方案是 适配器组件：

graph LR
  A["组件 A<br/>imports: math@1.0.0"] --> AD["适配器组件<br/>exports: math@1.0.0<br/>imports: math@2.0.0"]
  AD --> B["组件 B<br/>exports: math@2.0.0"]
  style AD fill:#f59e0b,color:#fff

适配器组件用 wit-bindgen 生成两套绑定，手写转换逻辑。这和微服务架构中的 API 网关层级类似——把版本兼容的复杂度集中在一处。

14.12.4 实战：演化策略清单

flowchart TD
  A["WIT 接口要变更"] --> B{"破坏性变更?"}
  B -->|否| C["minor++ 直接发布"]
  B -->|是| D{"消费者数量?"}
  D -->|< 3| E["协调升级<br/>所有消费者一起升 major"]
  D -->|>= 3| F["双版本共存策略"]
  F --> G["1. 在 v1 旁发布 v2"]
  G --> H["2. 写 v1→v2 适配器组件"]
  H --> I["3. 给消费者迁移期（3-6 月）"]
  I --> J["4. 监控 v1 调用量"]
  J --> K{"v1 调用 < 1%?"}
  K -->|否| I
  K -->|是| L["下线 v1"]
  style L fill:#10b981,color:#fff

经验数据：组件模型生态中，一个被 100+ 消费者使用的接口，从 v1 → v2 完整迁移通常需要 6-12 个月。强制立即迁移会破坏信任——给足够的迁移期，监控调用量自然下降到可下线水平。

14.13 组件调用的性能开销

理论上"组件互操作"是免费的——但 Canonical ABI 的编解码不可能零成本。理解开销来源有助于设计高性能的组件接口。

14.13.1 Canonical ABI 编解码的耗时分解

每次跨组件调用包含：

阶段 操作 典型耗时
1. lift（lower 反向） 调用方把参数序列化到 canonical 内存格式 50-500 ns
2. 拷贝 canonical 内存 → 被调方 linear memory 视数据量
3. lower 被调方反序列化为本语言类型 50-500 ns
4. 函数执行 实际业务逻辑 视实现
5. 返回值 lift/copy/lower 同上反向 50-500 ns

简单类型（数值、bool）的开销几乎全在函数调用本身（10-20 ns）。复杂类型（string、list、record）的开销主要来自 lift/lower。

14.13.2 类型选择对性能的影响

实测：Wasmtime 26，调用方与被调方都是 Rust 组件，单次调用耗时：

类型 单次调用耗时 说明
func(): u32 35 ns 仅函数调用 + 整数返回
func(a: u32, b: u32): u32 50 ns 两个整数参数
func(s: string): u32 250 ns 字符串需要 lift（UTF-8 验证 + 复制）
func(s: string): string 480 ns 双向字符串
func(items: list<u32>): u32 1200 ns 1000 元素列表传递
func(r: record-with-10-fields): u32 350 ns 10 字段记录的字段级 lift
func(items: list<record>): u32 8500 ns 1000 个嵌套记录

重要发现：嵌套 record 的开销显著高于扁平 record——因为 Canonical ABI 对每个嵌套层级都做独立的 lift/lower。设计接口时应优先扁平结构。

14.13.3 性能优化的接口设计原则

原则一：批量传递大块数据。每次跨组件调用有 ~50ns 固定开销——百万次调用就是 50ms。把循环放进被调用方而不是调用方：

// 反模式：每个元素一次跨组件调用
interface bad {
    process-one: func(item: u32) -> u32;
}

// 优化：一次调用处理整批
interface good {
    process-batch: func(items: list<u32>) -> list<u32>;
}

原则二：避免深嵌套 record。把嵌套 record 扁平化：

// 反模式
record user {
    name: string,
    address: record {
        street: string,
        city: string,
    },
}

// 优化（如果性能敏感）
record user-flat {
    name: string,
    street: string,
    city: string,
}

原则三：用 resource 句柄替代复杂结构。当数据量大且不需要每次都跨边界时，用 resource 让数据留在被调用方：

interface optimized {
    resource processor {
        constructor(config: string);
        process: func(input: list<u8>) -> list<u8>;
    }
}

processor 实例的内部状态留在被调用方，调用方只持有句柄——避免每次调用都重传 config 等元数据。

14.13.4 何时组件模型不该用

组件模型的开销使其不适合所有场景：

场景 推荐 理由
进程内部多语言互操作 组件模型 唯一标准方案
高频微调用（每秒 > 1M 次） 不推荐 50ns × 1M = 50ms 纯开销
简单的同语言调用 不推荐 直接 import 更快、更简单
服务边界（跨进程） 不推荐 gRPC/REST 更成熟
浏览器中的 Rust ↔ JS 不推荐（暂时） 用 wasm-bindgen，组件浏览器支持未成熟

组件模型的最佳定位：多语言、单进程、中频调用——例如插件系统、polyglot 微服务、跨语言库分发。

14.14 组件的安全模型与能力授权

组件模型的"可组合"如果没有"可信任"做基础就是空中楼阁——不同来源的组件被组装在一起，每个组件能做什么、不能做什么必须有清晰边界。组件模型从设计阶段就把安全嵌入了类型系统。

14.14.1 默认 deny-all 的能力模型

graph TD
  A["组件被实例化"] --> B{"宿主显式提供能力?"}
  B -->|否| C["组件无法访问任何外部资源"]
  B -->|是| D["仅能调用宿主提供的接口"]
  D --> E["wasi:filesystem<br/>受限路径"]
  D --> F["wasi:http/outgoing<br/>限定 host/port"]
  D --> G["自定义 host 接口<br/>业务能力"]
  style C fill:#10b981,color:#fff
  style D fill:#6366f1,color:#fff

每个组件的导入项是它的能力清单——wasi:filesystem/types 在导入项中表示它"想要文件系统能力"，宿主有权拒绝这次导入：

// 宿主代码：精细控制能力
let mut linker = Linker::new(&engine);

// 给该组件提供文件系统，但只 preopen 一个目录
wasmtime_wasi::add_to_linker_async(&mut linker)?;

// 不提供 wasi:http/outgoing-handler
// → 组件无法发起出站 HTTP 请求

let component = Component::from_file(&engine, "untrusted.wasm")?;
let instance = linker.instantiate_async(&mut store, &component).await?;

如果组件想用未授权的能力，实例化阶段就报错——不是运行时才发现。这种"能力先验证"的安全模型比传统沙箱（运行时拦截）更可靠。

14.14.2 接口级粒度的授权

组件模型的能力粒度细到接口级——同一个 wasi: 包，可以只授权部分接口：

粒度 示例
包级 全部 wasi:filesystem/*
接口级 只 wasi:filesystem/types，不给 wasi:filesystem/preopens
函数级 只 Descriptor.read，不给 Descriptor.write
资源级 resource 句柄表的访问限制

实战：

// 只授权读，不授权写
let mut wasi_ctx = WasiCtxBuilder::new()
    .preopened_dir(
        Dir::open_ambient_dir("/data", ambient_authority())?,
        "/",
        DirPerms::READ,           // ← 只读
        FilePerms::READ,
    )?
    .build();

组件即使包含写文件的代码，运行到 Descriptor.write 时也会被宿主拦截、返回 ErrorCode::AccessDenied。

14.14.3 自定义 host 接口的安全设计

业务自定义的 host 接口必须遵循同样的能力安全原则：

// WIT 定义
interface untrusted-api {
    // 反模式：传完整数据库连接给组件
    record db-config { url: string, user: string, password: string }
    init: func(config: db-config);
    query: func(sql: string) -> result<rows, error>;

    // 推荐：组件只看到 query 接口，连接由宿主管理
    resource query-context {
        constructor();
        execute: func(sql: string, params: list<value>) -> result<rows, error>;
    }
}

反模式的问题：组件拿到 db-config 后可以做任何 SQL 操作——DROP TABLE、读取其他用户数据。推荐方案：宿主创建 query-context 时已绑定特定数据库 + 特定用户权限，组件只能在这个上下文里查询。

graph LR
  A["组件代码"] --> B["query-context.execute<br/>受宿主限制"]
  B --> C["宿主拦截层<br/>SQL 解析 + 白名单"]
  C --> D["实际数据库"]
  style C fill:#f59e0b,color:#fff

宿主的拦截层可以做：

  • SQL 类型检查（SELECT 允许、DROP 禁止）
  • 表白名单（只准查询 users / orders）
  • 参数化查询强制（防 SQL 注入）
  • 速率限制（每组件每分钟最多 100 次）

这套机制让"不信任的组件 + 安全的能力授权"成为现实——组件即使是恶意代码，能造成的损害也被限制在宿主授权范围内。

14.14.4 信任链：从签名到运行时验证

生产部署中，组件必须经过完整的信任链验证：

flowchart LR
  A["组件源码"] --> B["可重现编译"]
  B --> C["sigstore 签名"]
  C --> D["上传到注册表"]
  D --> E["运行时拉取"]
  E --> F["验证签名"]
  F --> G{"签名有效?"}
  G -->|是| H["实例化"]
  G -->|否| I["拒绝加载"]
  style F fill:#6366f1,color:#fff
  style H fill:#10b981,color:#fff
  style I fill:#ef4444,color:#fff

具体实现（用 cosign 签名 + Wasmtime 验证）：

async fn load_signed_component(url: &str, expected_signer: &str) -> Result<Component> {
    // 1. 拉取组件 + 签名
    let component_bytes = fetch(url).await?;
    let signature = fetch(format!("{url}.sig")).await?;

    // 2. 验证签名
    let verifier = SigstoreVerifier::new(expected_signer);
    verifier.verify(&component_bytes, &signature)?;

    // 3. 通过验证后才实例化
    Component::from_binary(&engine, &component_bytes)
}

这套链路保证：组件来自可信发布者、未被中间人篡改、版本与签名匹配。配合 §5.11 介绍的可重现编译，整套供应链防护完整。

14.14.5 安全设计 checklist

flowchart TD
  A["组件部署安全审查"] --> B["1. 仅授权必需 WASI 接口"]
  A --> C["2. preopen 路径精确"]
  A --> D["3. 自定义 API 用 resource 不传配置"]
  A --> E["4. 宿主侧拦截 + 速率限制"]
  A --> F["5. 签名 + 哈希校验"]
  A --> G["6. fuel/epoch 防 DoS"]
  A --> H["7. 监控异常调用模式"]
  style A fill:#6366f1,color:#fff

每条都是过去的事故教训——遗漏任何一条都可能让"安全的组件模型"变成纸糊的防御。生产前 review 这套清单，把审查流程嵌入 CI（自动检查 WIT 导入项是否合理），让安全成为默认。

14.15 跨语言组件的工程实战模式

§14.7 给出了一个简单的多语言组件示例。生产中"多语言组件系统"远比示例复杂——团队协作、版本对齐、性能调优、调试排错都有自己的模式。这里总结从生产中提炼的实战经验。

14.15.1 团队所有权模式

graph TD
  A["多语言组件系统"] --> B{"组件所有权?"}
  B --> C["单团队多语言<br/>一个团队负责所有组件"]
  B --> D["多团队各自语言<br/>每团队负责自己语言的组件"]
  B --> E["平台 + 业务<br/>平台团队提供基础组件，业务自选"]
  C --> C1["✓ 协调简单<br/>✗ 团队语言广度要求高"]
  D --> D1["✓ 团队专精自己语言<br/>✗ 接口协调成本"]
  E --> E1["✓ 最常见生产模式<br/>需要清晰的接口契约"]
  style E fill:#10b981,color:#fff

90% 的生产团队是模式 E——平台团队用 Rust 写核心组件、业务团队用 JS/Python/Go 写业务组件、通过 WIT 接口契约协作。

14.15.2 接口契约的版本管理

跨团队的 WIT 接口必须有严格的版本管理：

// 主仓库（platform-team 维护）
package platform:storage@1.2.0;

interface kv {
    get: func(key: string) -> result<list<u8>, error>;
    set: func(key: string, value: list<u8>) -> result<_, error>;
}

业务团队的组件依赖：

# 业务组件 Cargo.toml
[dependencies]
wit-bindgen = "0.30"

[package.metadata.component]
package = "myteam:my-app@0.1.0"

[package.metadata.component.dependencies]
"platform:storage" = { path = "../wit/storage", version = "1.2" }

工程纪律：

  • 接口仓库独立：WIT 文件单独 git repo，不在任何业务仓库中
  • PR 流程：接口变更必须经过平台团队 review
  • CI 验证：业务组件的 CI 必须能从最新接口仓库拉版本

14.15.3 组件链接的工程模式

flowchart LR
  A["开发期"] --> B["每个组件独立开发"]
  B --> C["wac 工具链接"]
  C --> D["集成测试"]
  D --> E["部署"]
  F["组件链接策略"] --> F1["静态链接<br/>编译期合并"]
  F --> F2["动态链接<br/>运行时组合"]
  style C fill:#6366f1,color:#fff

wac（WebAssembly Composition）是组件链接的标准工具：

# 编译各组件
cargo component build --release  # → my-component.wasm

# 链接成最终组件
wac compose plugin.wasm \
    --dep platform:storage=storage.wasm \
    --dep platform:logger=logger.wasm \
    -o final.wasm

链接后的 final.wasm 是一个组合组件——所有依赖打包，部署时一个文件搞定。

14.15.4 调试多语言组件

跨语言组件的调试是最难的部分——错误可能发生在 Rust 组件、Python 组件、还是它们之间的接口。诊断流程：

flowchart TD
  A["报错"] --> B{"错误类型?"}
  B -->|Canonical ABI 错| C["检查 record 字段顺序"]
  B -->|资源句柄无效| D["检查跨组件 resource 转移"]
  B -->|trap| E["看哪个组件 trap"]
  C --> C1["wasm-tools component wit<br/>对比双方接口定义"]
  D --> D1["确认句柄管理规则<br/>不能跨实例"]
  E --> E1["每个组件单独跑<br/>定位问题组件"]
  style C1 fill:#10b981,color:#fff
  style D1 fill:#10b981,color:#fff
  style E1 fill:#10b981,color:#fff

通用调试技巧：

  • 分而治之：先把每个组件单独跑通，再链接调试
  • WIT 对照：所有组件的 WIT 接口必须 100% 一致（用 wasm-tools component wit 提取对比）
  • trace 跨组件调用：用 host 包装 + log 记录跨组件调用的输入/输出

14.15.5 多语言组件的性能调优

不同语言的组件性能特征不同：

语言 启动开销 执行性能 内存占用
Rust 低 最佳（接近原生） 低（无 GC）
C/C++ 低 最佳 低
Go 中等 良好 中等（GC）
Python 高（解释器） 慢（5-10x） 高
AssemblyScript 低 中等 中等

工程策略：

  • 核心热路径：用 Rust/C/C++ 编译的组件
  • 业务逻辑：用熟悉的语言（Go/Python）
  • Python 慎用：CPython on WASM 体积大、慢，仅适合非热路径

14.15.6 多语言组件的版本协同

graph TD
  A["发布新版本"] --> B["接口仓库 PR<br/>WIT 改动"]
  B --> C["平台 + 业务团队 review"]
  C --> D["合并到接口仓库"]
  D --> E["平台组件实现新接口"]
  E --> F["业务团队迁移"]
  F --> G["旧接口标记 deprecated"]
  G --> H["3 个月后下线旧版本"]
  style D fill:#6366f1,color:#fff
  style H fill:#ef4444,color:#fff

时间线：从接口 PR 到旧版本下线通常 3-6 个月——给业务团队足够的迁移期。强制立即迁移会破坏团队信任。

14.15.7 组件目录结构

component-project/
├── wit/                        # WIT 接口定义
│   ├── deps/
│   │   ├── platform-storage/   # 引入的接口
│   │   └── platform-logger/
│   └── world.wit               # 本组件的 world
├── src/
│   └── lib.rs                  # 组件实现
├── Cargo.toml
├── component.lock              # 依赖版本锁定
└── README.md

component.lock 类似 Cargo.lock——锁定所有 WIT 依赖的精确版本。这是多团队协作的关键——确保任何机器构建出的组件依赖完全一致。

14.15.8 实战经验总结

flowchart TD
  A["多语言组件项目经验"] --> B["1. 接口仓库独立 + 严格 review"]
  A --> C["2. 用 wac 链接，不要手动管理"]
  A --> D["3. 每语言团队独立 CI"]
  A --> E["4. 调试用 wasm-tools 对照接口"]
  A --> F["5. Python 慎用，仅非热路径"]
  A --> G["6. 接口废弃要给 3-6 月迁移期"]
  style A fill:#6366f1,color:#fff

这套模式让中大型团队（10-100 人）能高效协作开发多语言组件系统——每个团队专注自己的语言和业务，平台团队保证接口稳定。这是组件模型在生产环境真正发挥价值的方式。

14.16 组件 vs 模块：何时升级到组件

WASM 有两层抽象——核心模块（core module，规范定义的 .wasm）和组件（component，组件模型规范定义）。两者都是 WASM，但工程含义截然不同。理解何时选择哪个是组件模型最常见的工程困惑。

14.16.1 概念区别

graph TD
  A["WASM 抽象层级"] --> B["核心模块<br/>core module"]
  A --> C["组件<br/>component"]
  B --> B1["规范：WebAssembly Core Spec"]
  B --> B2["类型：i32/i64/f32/f64"]
  B --> B3["接口：底层 ABI"]
  B --> B4["互操作：手动协议"]
  C --> C1["规范：Component Model"]
  C --> C2["类型：record/variant/list/string..."]
  C --> C3["接口：WIT 定义"]
  C --> C4["互操作：Canonical ABI 自动"]
  style B fill:#6366f1,color:#fff
  style C fill:#10b981,color:#fff

类比：核心模块像 C 二进制（裸机协议），组件像 .NET assembly（带元数据和类型）。

14.16.2 何时用核心模块

flowchart TD
  A["选择核心模块"] --> B["1. 浏览器交付<br/>组件浏览器支持差"]
  A --> C["2. 极致性能<br/>避免 Canonical ABI 开销"]
  A --> D["3. 嵌入式<br/>WAMR 解释器更好支持"]
  A --> E["4. 简单场景<br/>纯计算 + JS 边界"]
  style A fill:#6366f1,color:#fff

核心模块的优势：

  • 生态成熟：所有 WASM 运行时都支持
  • 性能极致：没有 Canonical ABI 编解码
  • 体积小：没有组件元数据
  • 工具链稳定：wasm-pack / wasm-bindgen 全套成熟

14.16.3 何时升级到组件

flowchart TD
  A["升级到组件"] --> B["1. 多语言互操作<br/>Rust + Python + Go"]
  A --> C["2. 服务端 / 边缘<br/>Spin/wasmCloud 平台"]
  A --> D["3. 第三方插件<br/>需要稳定接口契约"]
  A --> E["4. 长期演进<br/>跟随 W3C 标准"]
  style A fill:#10b981,color:#fff

组件的优势：

  • 类型安全跨语言：WIT 接口契约
  • 可组合：wac 工具链接多组件
  • 能力安全：deny-all 默认 + WASI 接口
  • 未来兼容：W3C 标准化路线

14.16.4 决策矩阵

flowchart TD
  A["决策起点"] --> B{"目标平台"}
  B --> C["浏览器"]
  B --> D["服务器"]
  B --> E["嵌入式"]
  C --> F{"2026 现实<br/>组件浏览器支持?"}
  F -->|否| G["核心模块 + wasm-bindgen"]
  D --> H{"多语言?"}
  H -->|是| I["组件"]
  H -->|否| J{"插件系统?"}
  J -->|是| I
  J -->|否| K["核心模块"]
  E --> L{"WAMR / 资源?"}
  L -->|< 1MB 设备| M["核心模块"]
  L -->|资源充足| N["组件可选"]
  style G fill:#10b981,color:#fff
  style I fill:#6366f1,color:#fff
  style K fill:#10b981,color:#fff
  style M fill:#10b981,color:#fff

实践上：90% 浏览器 WASM 项目用核心模块（wasm-bindgen），90% 多语言服务端项目用组件。

14.16.5 实测：组件 vs 核心模块的开销

实测：传递一个 record（10 字段）+ 调用函数 + 接收 list（1000 元素）：

维度 核心模块 组件
二进制体积 30 KB 35 KB（多 5KB 元数据）
实例化时间 1 ms 1.5 ms
单次调用 35 ns 1.2 μs
1000 次调用累计 35 μs 1.2 ms
编译时间 30 s 35 s

组件在体积、调用时间、编译时间上都有 10-50% 开销——但获得了类型安全跨语言互操作的能力。这种权衡对多语言场景是值得的，对单语言场景是浪费。

14.16.6 渐进迁移：从模块到组件

如果未来想从模块升级到组件，可以渐进进行：

flowchart LR
  A["现有 wasm-bindgen 模块"] --> B["阶段 1<br/>定义 WIT 接口"]
  B --> C["阶段 2<br/>cargo-component 编译"]
  C --> D["阶段 3<br/>双产物（模块 + 组件）"]
  D --> E["阶段 4<br/>消费者迁移"]
  E --> F["阶段 5<br/>下线模块版本"]
  style F fill:#10b981,color:#fff

迁移工作量：

项目规模 迁移工作量
小项目（< 1000 行 Rust） 1-3 天
中型项目 1-3 周
大型项目（多模块） 1-3 月

迁移期间双产物共存——消费者按自己节奏切换，避免 big bang 升级风险。

14.16.7 何时不应该升级

并不是所有项目都该升级到组件。明确不该升级的场景：

graph TD
  A["不应该升级到组件"] --> B["1. 浏览器项目<br/>组件支持未成熟"]
  A --> C["2. 性能临界<br/>每微秒都珍贵"]
  A --> D["3. 团队新手<br/>组件工具链学习曲线"]
  A --> E["4. 极小项目<br/>组件元数据相对体积大"]
  A --> F["5. 短期项目<br/>组件 ROI 看不到"]
  style A fill:#ef4444,color:#fff

每条都对应特定场景的成本-收益失衡。强制升级会让团队在错误的时机投入资源。

14.16.8 工程纪律：定期重审

flowchart TD
  A["每季度重审组件 vs 模块决策"] --> B["1. 业务需求变化?"]
  A --> C["2. 工具链成熟度?"]
  A --> D["3. 团队能力?"]
  A --> E["4. 性能数据?"]
  A --> F["5. 标准演进?"]
  B --> G{"决策是否仍然合理?"}
  C --> G
  D --> G
  E --> G
  F --> G
  G -->|是| H["维持现状"]
  G -->|否| I["规划迁移"]
  style H fill:#10b981,color:#fff
  style I fill:#f59e0b,color:#fff

不要"一次决策定终身"——技术演进、业务变化都可能让决策失效。每季度 30 分钟的 review 能避免长期错配。

14.17 组件的部署与运维实战

组件模型的优势在 dev 时显著——但部署到生产时面临独特挑战：组件链接、版本管理、监控。这一节展开生产级组件运维的关键模式。

14.17.1 部署架构的演进

graph TD
  A["组件部署演进"] --> B["阶段 1：开发期"]
  A --> C["阶段 2：测试期"]
  A --> D["阶段 3：生产部署"]
  B --> B1["wac compose 本地链接"]
  C --> C1["staging 测试链接结果"]
  D --> D1["生产组件库 + 动态链接"]
  style D fill:#10b981,color:#fff

每阶段的关注点不同：

  • 开发期：快速迭代，wac 实时链接
  • 测试期：完整测试链接后的组件
  • 生产：组件版本管理 + 部署策略

14.17.2 组件的部署单位

graph LR
  A["部署单位选择"] --> B["独立组件"]
  A --> C["组合组件"]
  B --> B1["每个 .wasm 一个部署单元<br/>动态链接"]
  C --> C1["wac compose 后整体部署<br/>静态链接"]
  style B fill:#6366f1,color:#fff
  style C fill:#10b981,color:#fff
维度 独立组件 组合组件
部署粒度 细 粗
升级灵活 高（单组件升级） 低（整体替换）
启动复杂度 高（需要 link 时间） 低（直接 instantiate）
调试 复杂（多组件追踪） 简单

90% 的生产场景应选组合组件——简单可靠。只在多团队独立维护组件、需要独立升级时才用独立组件。

14.17.3 组件版本管理

flowchart TD
  A["组件版本管理"] --> B["1. 语义版本"]
  A --> C["2. 内容寻址"]
  A --> D["3. 版本注册表"]
  A --> E["4. 部署元数据"]
  B --> B1["semver 规则"]
  C --> C1["SHA-256 验证"]
  D --> D1["warg / 自建 registry"]
  E --> E1["componentRef + sha + version"]
  style A fill:#6366f1,color:#fff

实战 metadata 示例：

{
  "componentRef": "myorg/storage@1.2.3",
  "sha256": "a3f2b1c8...",
  "deployedAt": "2026-04-26T10:00:00Z",
  "deployedBy": "alice",
  "rollbackVersion": "1.2.2"
}

每次部署记录这些元数据——出问题时能快速回滚到上个版本。

14.17.4 组件监控指标

graph TD
  A["组件监控维度"] --> B["调用层"]
  A --> C["资源层"]
  A --> D["业务层"]
  B --> B1["每组件调用次数 / 延迟 / 错误率"]
  C --> C1["实例数 / 内存使用 / fuel 消耗"]
  D --> D1["业务功能完成率"]
  style B fill:#10b981,color:#fff
  style C fill:#6366f1,color:#fff
  style D fill:#f59e0b,color:#fff

每个组件应该暴露以下 metrics：

metrics::counter!("component_calls_total",
    "component" => component_name,
    "function" => func_name,
).increment(1);

metrics::histogram!("component_call_duration_seconds",
    "component" => component_name,
).record(elapsed.as_secs_f64());

metrics::gauge!("component_instances_active",
    "component" => component_name,
).set(active_instances);

14.17.5 组件的 A/B 部署

新版本组件上线时，渐进发布：

flowchart LR
  A["新组件 v2.0"] --> B["1% canary"]
  B --> C["10% rollout"]
  C --> D["50% rollout"]
  D --> E["100% rollout"]
  B --> B1{"指标正常?"}
  C --> C1{"指标正常?"}
  D --> D1{"指标正常?"}
  B1 -->|否| F["回滚到 v1.x"]
  C1 -->|否| F
  D1 -->|否| F
  style E fill:#10b981,color:#fff
  style F fill:#ef4444,color:#fff

每阶段的等待期：通常 1-2 小时，让 P95 数据稳定。组件级别的金丝雀部署比传统服务更安全——因为组件实例化快、回滚也快。

14.17.6 组件的故障隔离

多组件系统中，一个组件故障不应影响其他：

graph TD
  A["故障隔离机制"] --> B["1. 独立 Store"]
  A --> C["2. fuel/timeout"]
  A --> D["3. 异常包装"]
  A --> E["4. 熔断"]
  B --> B1["错误不传染"]
  C --> C1["挂死自动终止"]
  D --> D1["component A 异常不让 B 失败"]
  E --> E1["失败率高时停止调用"]
  style A fill:#6366f1,color:#fff

实战熔断模式：

struct ComponentCallable {
    name: String,
    circuit_breaker: CircuitBreaker,
}

impl ComponentCallable {
    async fn call(&self, args: Args) -> Result<Output, Error> {
        if self.circuit_breaker.is_open() {
            return Err(Error::CircuitOpen);
        }
        match invoke_component(&self.name, args).await {
            Ok(r) => {
                self.circuit_breaker.record_success();
                Ok(r)
            }
            Err(e) => {
                self.circuit_breaker.record_failure();
                Err(e)
            }
        }
    }
}

熔断让"一个组件故障"在 1 分钟内停止级联到其他——保护整体系统稳定。

14.17.7 组件的运维 runbook

flowchart TD
  A["组件运维 runbook"] --> B["1. 监控指标看板链接"]
  A --> C["2. 部署/回滚命令"]
  A --> D["3. 常见错误对照表"]
  A --> E["4. 联系人列表"]
  A --> F["5. 紧急熔断开关"]
  style A fill:#6366f1,color:#fff

每个组件应该有自己的 runbook——值班人员能在 5 分钟内找到信息。这套准备工作让组件级故障的响应时间显著缩短。

14.17.8 多组件部署的协调

sequenceDiagram
    participant D as 部署系统
    participant A as 组件 A
    participant B as 组件 B
    participant C as 组件 C
    Note over A,C: 多组件协同升级
    D->>D: 检测依赖关系（A 依赖 B 依赖 C）
    D->>C: 1. 部署 C 新版（兼容旧 API）
    D->>B: 2. 部署 B 新版（用 C 新 API）
    D->>A: 3. 部署 A 新版
    Note over A,C: 出问题时反向回滚（A→B→C）

多组件的部署顺序很关键：依赖底层先升级，被依赖上层再升。回滚顺序相反：上层先回滚，底层后回滚——避免依赖未满足的中间态。

14.17.9 组件部署的工程纪律

flowchart TD
  A["组件部署纪律"] --> B["1. 部署前完整测试"]
  A --> C["2. 渐进发布"]
  A --> D["3. 监控覆盖"]
  A --> E["4. 自动化回滚"]
  A --> F["5. 多组件协调"]
  A --> G["6. 部署元数据"]
  style A fill:#10b981,color:#fff

每条都对应过去事故的教训——遵循这套纪律，组件级生产部署的可靠性接近传统服务。

WASM 组件不是"奇技淫巧"——把它纳入标准的部署、监控、运维框架，才能让组件模型在生产中真正发挥价值。

14.18 组件的热替换与运行时升级

传统服务升级需要停机或滚动重启——WASM 组件的特性让"运行中替换组件"成为可能。这是 WASM 在长生命周期服务中的独特价值。

14.18.1 热替换的核心挑战

graph TD
  A["热替换挑战"] --> B["状态保留"]
  A --> C["版本兼容"]
  A --> D["原子切换"]
  A --> E["回滚能力"]
  B --> B1["组件内 state 如何保留"]
  C --> C1["新旧组件接口必须兼容"]
  D --> D1["切换瞬间不丢请求"]
  E --> E1["新组件出问题秒级回滚"]
  style A fill:#f59e0b,color:#fff

每个挑战需要专门设计——简单的"卸载旧组件、加载新组件"不行，会丢请求和状态。

14.18.2 模式一：双实例并行

sequenceDiagram
    participant R as 路由器
    participant A as 旧实例 v1
    participant B as 新实例 v2
    Note over R,B: 状态：v1 在线
    R->>A: 处理请求
    Note over R,B: 切换开始
    R->>B: 加载 v2
    R->>R: 切换路由
    Note over R,B: 状态：v1 + v2 并行
    R->>B: 新请求路由到 v2
    A->>A: 完成处理中的请求
    Note over R,B: 状态：v2 在线，v1 退出

实战代码：

struct ComponentManager {
    current: Arc<RwLock<wasmtime::Instance>>,
    pending: Option<wasmtime::Instance>,
}

impl ComponentManager {
    async fn hot_swap(&mut self, new_module: &Module) -> Result<()> {
        let mut store = Store::new(&self.engine, ());
        let new_instance = Instance::new(&mut store, new_module, &[])?;

        // 双实例并行运行（新请求用新版）
        self.pending = Some(new_instance);

        // 等待旧实例的进行中请求完成
        wait_for_drain().await;

        // 替换为新实例
        let mut current = self.current.write().await;
        *current = self.pending.take().unwrap();

        Ok(())
    }
}

14.18.3 模式二：状态外置

graph LR
  A["请求"] --> B["组件实例（无状态）"]
  B --> C["外部状态存储<br/>Redis/DB"]
  D["新组件加载"] --> B
  D --> C
  style B fill:#10b981,color:#fff
  style C fill:#6366f1,color:#fff

如果组件无内部状态——所有状态在 Redis/DB 中——热替换简单：直接换组件实例，新实例从外部存储读状态。

// 无状态组件设计
#[wasm_bindgen]
impl Handler {
    pub async fn handle(&self, request: &str, state_key: &str) -> String {
        // 1. 从外部读状态
        let state = redis::get(state_key).await;

        // 2. 处理（无内部状态）
        let new_state = process(state, request);

        // 3. 写回外部状态
        redis::set(state_key, new_state).await;

        format!("processed")
    }
}

14.18.4 模式三：状态迁移

如果组件有内部状态需要保留：

flowchart LR
  A["旧实例 v1"] --> B["导出状态<br/>serialize"]
  B --> C["序列化数据"]
  C --> D["新实例 v2 import<br/>deserialize"]
  D --> E["v2 继续服务"]
  style B fill:#6366f1,color:#fff
  style D fill:#10b981,color:#fff

需要在 WIT 中定义状态迁移接口：

interface stateful {
    export-state: func() -> list<u8>;
    import-state: func(state: list<u8>) -> result<_, error>;
}

新旧版本的 state 格式必须兼容——版本演化的 schema 变化要谨慎。

14.18.5 版本兼容性检查

flowchart TD
  A["热替换前检查"] --> B["1. WIT 接口签名"]
  A --> C["2. ABI 兼容性"]
  A --> D["3. State schema"]
  A --> E["4. 配置兼容"]
  B --> B1["wasm-tools component wit 对比"]
  C --> C1["Canonical ABI 不变"]
  D --> D1["state 字段加减是否兼容"]
  E --> E1["新版本配置在旧位置可读"]
  style A fill:#6366f1,color:#fff

不兼容的更新不能热替换——必须传统重启。判断兼容性：

# 工具：对比两版本的 WIT
diff <(wasm-tools component wit v1.wasm) \
     <(wasm-tools component wit v2.wasm)

# 通过则可热替换

14.18.6 流量切换策略

flowchart LR
  A["流量切换"] --> B["1% canary"]
  B --> C{"指标 OK?"}
  C -->|是| D["10% rollout"]
  C -->|否| E["回滚"]
  D --> F{"指标 OK?"}
  F -->|是| G["100%"]
  F -->|否| E
  style G fill:#10b981,color:#fff
  style E fill:#ef4444,color:#fff

每阶段的等待时间（让 P95 数据稳定）：

  • 1% → 10%：1-2 小时
  • 10% → 50%：4-8 小时
  • 50% → 100%：1 天

14.18.7 回滚能力

struct ComponentRollback {
    versions: Vec<(String, Module)>,  // 保留最近 N 版本
}

impl ComponentRollback {
    async fn rollback_to_previous(&mut self) -> Result<()> {
        if self.versions.len() < 2 {
            return Err("no previous version");
        }
        let (_, prev_module) = &self.versions[self.versions.len() - 2];
        self.hot_swap(prev_module).await
    }
}

至少保留上一个版本——回滚通过相同的热替换机制实现。

14.18.8 监控热替换过程

metrics::counter!("component_hot_swap_total",
    "from_version" => from,
    "to_version" => to,
).increment(1);

metrics::histogram!("component_hot_swap_duration_seconds",
    "to_version" => to,
).record(elapsed.as_secs_f64());

metrics::counter!("component_hot_swap_failed_total",
    "reason" => reason,
).increment(1);

每次热替换都生成监控数据——出问题时能精确定位。

14.18.9 适用场景

flowchart TD
  A["何时该用热替换"] --> B{"系统特征?"}
  B --> C["长连接服务<br/>WebSocket"]
  B --> D["大量并发请求"]
  B --> E["不允许停机"]
  B --> F["短任务批处理"]
  C --> G["热替换价值大"]
  D --> G
  E --> G
  F --> H["传统重启即可"]
  style G fill:#10b981,color:#fff
  style H fill:#6366f1,color:#fff

热替换有工程复杂度——不是所有场景都值得。短生命周期、低 SLA 的服务用传统部署即可。

14.18.10 工程纪律

flowchart TD
  A["热替换工程纪律"] --> B["1. 接口兼容性自动检查"]
  A --> C["2. 状态格式 schema 演化"]
  A --> D["3. 渐进流量切换"]
  A --> E["4. 自动回滚"]
  A --> F["5. 监控指标完整"]
  A --> G["6. 演练制度化"]
  style A fill:#6366f1,color:#fff

每条都对应过去的事故教训——热替换是高级能力，需要严格的工程纪律配合。

把这套热替换机制集成到 WASM 组件系统，让"零停机更新"成为常态，是 WASM 在企业生产环境的关键价值。

14.19 组件的可观测性与调用链追踪

多组件系统的可观测性比单体更复杂——一个用户请求可能经过 5-10 个组件。如果没有调用链追踪，定位问题几乎不可能。

14.19.1 多组件系统的诊断挑战

graph TD
  A["用户请求"] --> B["API 网关组件"]
  B --> C["认证组件"]
  C --> D["业务组件"]
  D --> E["数据组件"]
  D --> F["缓存组件"]
  E --> G["DB"]
  H["用户报错"] -.诊断.-> A
  H -.诊断.-> B
  H -.诊断.-> C
  H -.诊断.-> D
  H -.诊断.-> E
  style H fill:#ef4444,color:#fff

错误可能出在任意一个组件——没有追踪等于盲人摸象。

14.19.2 OpenTelemetry 在组件模型中的应用

// 每个组件接收 trace context
#[wasm_bindgen]
pub fn handle(request: Request) -> Response {
    let span = create_span_from_request(&request);
    let _guard = span.enter();

    // 业务逻辑
    let result = process(&request);

    // 调用下游组件，传递 context
    let downstream_response = call_downstream(&result, &request.trace_context);

    Response::new(downstream_response)
}

每个组件创建自己的 span——通过 trace_context 串成完整调用链。

14.19.3 trace context 的传递

WIT 接口需要显式定义 context 传递：

package observability:trace@1.0.0;

record trace-context {
    trace-id: string,
    span-id: string,
    flags: u8,
}

interface tracer {
    use trace-context;

    create-span: func(name: string, parent: option<trace-context>) -> trace-context;
    end-span: func(ctx: trace-context);
}

每个组件接受 trace-context 作为参数——保证跨组件的关联性。

14.19.4 自动注入 vs 手动传递

graph TD
  A["trace context 传递方式"] --> B["手动传递"]
  A --> C["自动注入"]
  B --> B1["每个 fn 参数加 ctx<br/>显式但繁琐"]
  C --> C1["host 自动注入<br/>简洁但黑箱"]
  style B fill:#6366f1,color:#fff
  style C fill:#10b981,color:#fff

主流方案是 host 自动注入——在 host 实现中给每个组件调用自动加 context：

// host 端
async fn invoke_component(&self, args: Args, parent_ctx: Option<TraceContext>) -> Result<Output> {
    let span = tracer.start_span("component_call", parent_ctx);
    let result = self.component.invoke(args).await;
    span.end();
    result
}

业务代码无感知——但所有调用都被自动追踪。

14.19.5 组件调用的关键指标

flowchart TD
  A["组件调用指标"] --> B["调用次数"]
  A --> C["延迟"]
  A --> D["错误率"]
  A --> E["资源消耗"]
  B --> B1["按组件 / 按方法<br/>QPS"]
  C --> C1["P50/P95/P99"]
  D --> D1["按错误类型分聚"]
  E --> E1["fuel / 内存"]
  style A fill:#6366f1,color:#fff

每个组件都应该暴露这 4 类指标——构成完整的可观测性。

14.19.6 调用链可视化

gantt
    title 一次请求的组件调用链
    dateFormat X
    axisFormat %s
    section 网关
    认证   :a, 0, 5
    路由   :b, 5, 8
    section 业务
    主流程  :c, 8, 50
    section 数据
    DB 查询 :d, 12, 28
    缓存读   :e, 30, 32
    section 业务
    后处理  :f, 50, 60

调用链可视化让"哪个环节慢"一眼可见——是 P99 调优的基础。

14.19.7 工具集成

graph TD
  A["组件可观测性工具"] --> B["Jaeger"]
  A --> C["Tempo"]
  A --> D["Honeycomb"]
  A --> E["Datadog APM"]
  B --> B1["开源 tracing"]
  C --> C1["Grafana 生态"]
  D --> D1["商业，强大"]
  E --> E1["全栈商业"]
  style A fill:#6366f1,color:#fff

每个工具支持 OpenTelemetry——只要组件正确实施 OTel，监控工具可换。

14.19.8 监控数据的采样

// 智能采样：错误 100%，慢请求 100%，正常请求 1%
fn should_sample(&self, span: &Span) -> bool {
    if span.has_error() { return true; }
    if span.duration() > Duration::from_secs(1) { return true; }
    rand::random::<f64>() < 0.01
}

100% 采样的成本太高——智能采样保留高价值数据。

14.19.9 组件可观测性的成熟度

graph LR
  A["第 0 级<br/>无监控"] --> B["第 1 级<br/>基础 metrics"]
  B --> C["第 2 级<br/>结构化日志"]
  C --> D["第 3 级<br/>分布式追踪"]
  D --> E["第 4 级<br/>智能根因分析"]
  style E fill:#10b981,color:#fff

组件系统应该至少达到第 3 级——分布式追踪。否则多组件协作的复杂度无法管理。

14.19.10 工程清单

flowchart TD
  A["组件可观测性"] --> B["1. 每组件标准 metrics"]
  A --> C["2. trace context 必传"]
  A --> D["3. 自动注入实现"]
  A --> E["4. 智能采样"]
  A --> F["5. 调用链可视化"]
  A --> G["6. 跨团队监控对齐"]
  style A fill:#10b981,color:#fff

每条都对应大型组件系统的需求——遵循后能让多组件协作的复杂度可控。

把组件可观测性当作架构的第一公民——而非事后补救。这是组件模型在生产规模化的关键。

14.20 跨专栏关联：组件模型与微前端

组件模型的"可组合"承诺和《微前端源码精讲》第 1 章的"独立开发、独立部署、运行时组合"理念完全对齐：

  • 微前端：不同团队开发的 JS 应用在浏览器中组合成统一的用户体验——通过路由分发、JavaScript 沙箱、CSS 隔离实现
  • 组件模型：不同语言开发的 WASM 组件在运行时组合成统一的应用——通过 WIT 接口契约、Canonical ABI、能力安全实现

两者的共同挑战：版本兼容性。微前端中，子应用 A 依赖 React 17，子应用 B 依赖 React 18——运行时可能冲突。组件模型中，组件 A 导出 example:math@1.0.0，组件 B 导入 example:math@2.0.0——接口不兼容。两者都需要版本协商机制——微前端用 module federation 的共享依赖，组件模型用 WIT 的语义化版本。

区别在于粒度：微前端是"应用级"组合（整个 SPA 子应用），组件模型是"库/服务级"组合（单个函数/接口）。两者互补——微前端管理应用间的路由和状态，组件模型管理组件间的接口调用和数据传递。一个可能的未来架构：微前端负责页面级编排，每个微前端内部用组件模型组合 Rust/Python/Go 的 WASM 组件实现计算密集型逻辑。

下一章看 wit-bindgen——如何从 WIT 定义自动生成 Rust 绑定代码，消除手写 Canonical ABI 编解码的样板代码。