WASI 0.2.2 规范解析：基于 Component Model 的七大提案与 WIT 接口全览-开发者社区

【免费下载链接】WASI

WebAssembly System Interface

项目地址：https://gitcode.com/gh_mirrors/wa/WASI

本文围绕本仓库specifications/wasi-0.2.2/Overview.md展开，系统讲解 WebAssembly System Interface（WASI）0.2.2 规范的技术定位、提案组成与发布形态：它基于 WebAssembly Component Model，将wasi:io、wasi:random、wasi:clocks、wasi:sockets、wasi:filesystem、wasi:cli、wasi:http七个提案的 WIT（WebAssembly Interface Type）定义按 Wasm OCI Artifact 布局推送到 OCI 分发。读完本文，你将掌握 WASI 0.2.x（Preview 2）这一代接口的完整组成、每个提案的核心接口与仓库中的对应 WIT 源码位置，以及 0.2.2 与相邻 0.2.0/0.2.1 乃至 0.3.x 系列的版本脉络。

WASI 0.2 的时代背景：从 witx 到 Component Model

在进入 0.2.2 的具体内容前，有必要先定位它在 WASI 演进序列中的坐标。仓库根目录的 README.md 给出了清晰的代际划分：

Preview 1（WASI 0.1）：最早发布并已广泛使用的 API，使用 witx IDL 定义，主要受 POSIX 与 CloudABI 影响；
WASI 0.2（Preview 2）：以Wit IDL定义的一组模块化 API 集合，吸收了 0.1 的经验教训，支持更广泛的源语言、更强的模块化、更具表达力的类型系统以及可虚拟化（virtualizability）；
WASI 0.3（Preview 3）：当前预览版，用组件模型原生的future/stream异步能力替代 0.2 中显式的流与轮询接口。

因此，specifications/wasi-0.2.2/Overview.md开头那句 "based on the WebAssembly Component Model" 并非修饰语，而是 0.2 世代所有接口定义的方式论前提：每个提案都不再是扁平的函数清单，而是组件模型中的 world、interface、resource、stream、future 等一等公民。

仓库 specifications/ 目录按版本号排列了从wasi-0.2.0到wasi-0.2.12、再到wasi-0.3.0、wasi-0.3.1的系列 Overview 文档，本篇文章聚焦的specifications/wasi-0.2.2/Overview.md即位于这一版本谱系之中。

0.2.2 规范的提案组成：七个 WASI API 包

specifications/wasi-0.2.2/Overview.md正文的核心内容，是声明包含在 0.2.2 规范中的七个提案，其 WIT 定义被推送到 OCI 分发。完整清单如下：

提案（WIT 包）	职责	仓库对应目录
`wasi:io@0.2.2`	流与 future 等基础 I/O 类型	未在`proposals/`下单独成目录（见下文说明）
`wasi:random@0.2.2`	加密安全的随机数	proposals/random/wit/
`wasi:clocks@0.2.2`	单调时钟、系统时钟与时区	proposals/clocks/wit/
`wasi:sockets@0.2.2`	TCP/UDP/IP 域名解析等网络能力	proposals/sockets/wit/
`wasi:filesystem@0.2.2`	基于 descriptor 的文件系统访问	proposals/filesystem/wit/
`wasi:cli@0.2.2`	命令行环境：参数、环境变量、stdio、退出码	proposals/cli/wit/
`wasi:http@0.2.2`	HTTP 服务端与客户端	proposals/http/wit/

说明：文档列出的wasi:io@0.2.2在proposals/目录下没有对应的独立提案文件夹，从源码结构看，stream<u8>、future<result<...>>等 io 类型直接以依赖形式出现在 filesystem、cli（stdio）、http 等提案的 WIT 签名中（例如 proposals/cli/wit/stdio.wit、proposals/http/wit/types.wit），即 io 承担着"被其余接口复用的底层类型底座"角色。

从 docs/Proposals.md 的活跃提案清单可以看到，clocks、random、filesystem、sockets、cli、http 六个提案目前处于Phase 3（Implementation Phase），分别由 Dan Gohman、Dave Bakker、Piotr Sikora 等人担任 Champion——这与 0.2.2 规范"收录哪些提案"的决策依据直接相关。

发布形态：Wasm OCI Artifact 布局与 WIT 分发

规范文档特别强调，每个提案的 WIT 定义是"pushed to OCI based on the Wasm OCI Artifact layout"，即按 Wasm OCI Artifact 的布局标准打包进 OCI 镜像仓库进行版本化分发。这意味着：

每个提案包对应一个独立的 OCI 镜像，以wasi:<proposal>为命名空间，以0.2.2为 tag（例如wasi:cli@0.2.2）；
WIT 定义成为可被wit-deps等工具直接拉取的依赖单元——仓库中 filesystem、sockets、http、cli 等提案目录内均带 deps.toml 与 deps.lock 文件，正是 WIT 包依赖声明与锁定机制的实际体现；
版本号通过 OCI tag 表达，同一提案的不同规范版本可并行共存，互不覆盖。

这种分发方式的收益在于：工具链和宿主实现可以按精确版本获取接口定义，而不是依赖某个"最新主干"，为多版本并行（0.2.x 与 0.3.x 共存）提供了分发基础。

逐个拆解：七大提案的核心接口

wasi:io：stream 与 future 的类型底座

wasi:io提供的是组件模型 I/O 的类型基础。虽然本仓库没有其独立 WIT 文件，但它的影响无处不在：CLI 的 stdin/stdout/stderr 通过read-via-stream/write-via-stream返回或接收stream<u8>与future<result<_, error-code>>（proposals/cli/wit/stdio.wit），HTTP 请求/响应体同样是option<stream<u8>>（proposals/http/wit/types.wit）。可以推断，wasi:io定义了这些跨提案共享的流式原语，是其余提案的公共依赖。

wasi:random：加密安全的随机数

WASI Random 的目标是让 WASI 程序获得适合密码学用途的高质量底层随机数据。核心接口在 proposals/random/wit/random.wit 中定义了两个函数：

get-random-bytes(max-len: u64) -> list<u8>：返回至多max-len字节的加密安全随机（或伪随机）数据。规范要求数据至少达到充分播种的 CSPRNG 的强度、任何情况下都不得阻塞、且总是不可预测的；实现允许"短读"（返回少于请求的字节），因此需要精确字节数的调用方必须循环调用直至凑齐；max-len为 0 时必须返回空列表而不能 trap；
get-random-u64() -> u64：同样的随机数据以u64形式返回，用于规避list<u8>绑定的额外开销。

此外，该提案还包含insecure.wit（用于哈希表 DoS 防护的固定大小种子，见 proposals/random/README.md）与insecure-seed.wit。其设计目标还包括让源语言在宿主环境支持下为哈希表启用 DoS 防护。

wasi:clocks：单调时钟、系统时钟与时区

proposals/clocks/wit/monotonic-clock.wit 定义单调时钟：起点未指定，连续读取产生非递减值，适合测量流逝时间。其接口包括：

now() -> mark：读取当前值，mark是自未指定起点起的纳秒数（u64）；
get-resolution() -> duration：查询时钟分辨率；
wait-until(when: mark)与wait-for(how-long: duration)：异步等待到指定时刻或等待指定时长。

proposals/clocks/wit/system-clock.wit 定义系统时钟，面向"给人看"的当前日期时间：now() -> instant返回以 1970-01-01T00:00:00Z 为纪元（POSIX 秒）的{seconds: s64, nanoseconds: u32}记录；该时钟可能被外部重置，不保证单调，因此不适合测量流逝时间。

两者共用 proposals/clocks/wit/types.wit 中的duration = u64（纳秒）。在 0.2.2 版本中，timezone接口（world imports中以@unstable(feature = clocks-timezone)标记，见 proposals/clocks/wit/world.wit）属于未稳定特性，这也解释了该提案在 docs/Proposals.md 中"Clocks: Timezone"单列于 Phase 2 的原因。

wasi:sockets：TCP/UDP 与 IP 域名解析

wasi:sockets提供网络能力。proposals/sockets/wit/types.wit 定义了地址族（ipv4/ipv6，对应 POSIXAF_INET/AF_INET6）、IPv4/IPv6 地址、套接字地址（含port、flow-info、scope-id等字段）以及面向 socket 的错误码（如address-in-use、connection-refused、timeout），每个错误码都标注了 POSIX 对应项。TCP socket 资源处于unbound→bound→listening/connecting→connected→closed的状态机中，详细的运行语义可参见仓库中的 TcpSocketOperationalSemantics.md 与 Posix-compatibility.md。

域名解析在 proposals/sockets/wit/ip-name-lookup.wit 中通过resolve-addresses(name: string) -> result<list<ip-address>, error-code>提供，Unicode 域名自动经 IDNA 转 ASCII，IP 字符串则直接解析不发起外部请求，结果按连接顺序偏好返回，且保证成功时至少返回一个地址、从不返回 IPv4-mapped IPv6 地址。

wasi:filesystem：基于 descriptor 的沙箱化文件访问

wasi:filesystem的目标是让 WASI 程序在既有文件系统上低开销地访问文件。proposals/filesystem/wit/types.wit 给出了几条关键的语义约定：

路径即字符串：路径以 Unicode 标量值序列（string）传递，目录分隔符恒为/；
全部相对路径：所有路径都相对于一个指向基准目录的descriptor解释。若路径以/开头，或解析过程中任何一步（含..与符号链接）触及基准目录之外、或触及指向底层文件系统绝对/根路径的符号链接，函数将以error-code::not-permitted失败——这是 WASI 沙箱模型在文件系统层面的落点，详细规则见 path-resolution.md；
兼容优先于可移植：底层平台可能导致路径大小写折叠差异、删除被打开文件的行为差异、并发写者的持久性与原子性差异；需要严格可移植语义的用户应改用键值存储或数据库。

接口以descriptor资源为核心，提供open-at、read-via-stream/write-via-stream/append-via-stream（分别对应 POSIXpread/pwrite/O_APPEND写）、stat/stat-at、create-directory-at、rename-at、link-at、symlink-at、metadata-hash、is-same-object等约 30 个方法，并定义了与 POSIXO_CREAT/O_EXCL/O_TRUNC对应的open-flags以及descriptor-flags（含类似O_SYNC/O_DSYNC的同步标志与mutate-directory写目录开关）。预打开目录通过 preopens.wit 的get-directories() -> list<tuple<descriptor, string>>提供给 guest。

wasi:cli：命令行世界与标准流

wasi:cli是面向命令行环境的 world 提案，覆盖交互式命令行程序、使用文件系统与套接字的服务端程序，以及读写标准输入输出的流过滤器三类典型场景（见 proposals/cli/README.md）。其核心是 command.wit 中的commandworld：

package wasi:cli@0.3.1; @since(version = 0.3.0) world command { include imports; export run; }

commandworld 由两部分组成：

include imports：汇总了wasi:clocks/imports、wasi:filesystem/imports、wasi:sockets/imports、wasi:random/imports，以及environment、exit、stdin/stdout/stderr、terminal-input/terminal-output/terminal-stdin/terminal-stdout/terminal-stderr等接口（proposals/cli/wit/imports.wit）；
export run：guest 导出run: async func() -> result作为程序入口（proposals/cli/wit/run.wit）。

其中几个接口的要点：

environment（environment.wit）：get-environment()返回 POSIX 风格环境变量（(name, value)对），get-arguments()返回命令行参数列表，get-initial-cwd()返回初始工作目录路径；
stdio（stdio.wit）：stdin 通过read-via-stream() -> tuple<stream<u8>, future<result<_, error-code>>>提供读取流；stdout/stderr 通过write-via-stream(data: stream<u8>) -> future<result<_, error-code>>写入，错误码包括io、illegal-byte-sequence、pipe（断管）；
exit（exit.wit）：exit(status: result)与exit-with-code(status-code: u8)退出当前实例及任何链接实例，exit-with-code不返回，效果类似 trap 但无"出错"含义，0 通常表示成功。

设计取舍上，stdout/stderr仍作为output-stream处理而未单独提供"永不失败"的打印 API，是考虑到云/边缘场景应迁移到更专用的 world；环境变量单独作为 import 而非command参数，是为了让非 CLI world 也能复用。

wasi:http：service 与 middleware 两类 world

wasi:http以组件模型 world 的方式同时覆盖 HTTP 服务与客户端。proposals/http/wit/worlds.wit 定义了三个关键构件：

serviceworld：面向 web 应用、API 服务与代理的广义 HTTP 服务，include 时钟与随机数导入，导入wasi:cli/stdout、stderr（以及为兼容工具链而临时保留的stdin）、client接口，并导出handler接口——宿主通过调用组件导出的handler.handle(request) -> result<response, error-code>将入站请求投递给组件，组件需能处理 0..N 次handle调用；
middlewareworld：includeservice并额外导入handler，使组件可参与"请求沿 handler 链流动至末端 service、响应反向流回"的中间件链；
client接口：send的签名与handler.handle相同，既可发往网络也可直连另一组件的handle导出绕过网络。

类型层面，proposals/http/wit/types.wit 定义了method（含other(string)扩展）、scheme、status-code = u16、fields/headers/trailers资源（支持get/set/append/delete/clone等操作，区分可变与不可变）、request与response资源（body 以option<stream<u8>>表达，经consume-body消费）、request-options（可配置连接、首字节、字节间三个传输层超时）以及一套精细的error-code（从DNS-error到TLS-alert-received、HTTP-response-timeout等，涵盖代理场景的 IANA 错误类型灵感）。HTTP 中间件链的更完整讨论可参考 middleware.md 与 service.md。

版本脉络：0.2.x 到 0.3.x 的演进

将specifications/wasi-0.2.2/Overview.md与相邻版本对比，可以看清演进节奏：

wasi-0.2.0、wasi-0.2.1、wasi-0.2.2三个版本结构完全一致，均为七个提案 + OCI 发布声明，差异体现在 OCI tag 版本号上（0.2.1/0.2.2 属修订性发布）；
从wasi-0.3.0开始，规范不再包含wasi:io，并新增 "Component Model features" 章节，明确实现该版本需在默认（非门控）组件模型特性之上，再加已采纳的门控特性（asynclift/lower、future、stream，见 specifications/wasi-0.3.0/Overview.md）；
wasi-0.3.1进一步引入map<K,V>类型与implements/external-id注解等门控特性，完整的采纳记录见 docs/ComponentModelFeatures.md。

这也解释了为什么本仓库proposals/目录下各提案的 WIT 文件包版本为0.3.x（如package wasi:cli@0.3.1）：提案目录反映的是当前在推进的最新定义，而历史规范快照（0.2.x）的 WIT 包则通过 OCI artifact 以对应 tag 分发。

总结：如何在仓库中继续深入

本文基于specifications/wasi-0.2.2/Overview.md展开。若要深入每个提案的实现细节，建议按以下路径在仓库中继续阅读：

提案状态与 Champion：查看 docs/Proposals.md 的 Phase 3 清单；
各提案的 WIT 定义与设计讨论：proposals/<proposal>/wit/*.wit与对应 README；
文件系统路径沙箱规则：proposals/filesystem/path-resolution.md；
socket 状态机与 POSIX 兼容性：proposals/sockets/TcpSocketOperationalSemantics.md、proposals/sockets/Posix-compatibility.md；
HTTP 中间件与服务模型：proposals/http/middleware.md、proposals/http/service.md；
规范版本谱系与门控特性采纳记录：specifications/wasi-0.2.x/、specifications/wasi-0.3.x/与 docs/ComponentModelFeatures.md。

WASI 0.2.2 是 Preview 2 世代中的一个稳定快照：以 Component Model 为骨架，以 OCI artifact 为分发通道，将 io、random、clocks、sockets、filesystem、cli、http 七大能力集成为一个可版本化、可组合、可沙箱化的系统接口体系——这也是后续 0.3 世代迈向原生异步组件模型的基础。