• 编程语言
• 编译器
• 云原生
• 语言运行时

本篇文章以 tests/valid/bucket_keys.test.w 及其 hangar 快照 bucket_keys.test.w_test_sim.md 为主线，系统讲解 Wing 中cloud.Bucket的 Key 命名空间语义、list()在模拟器（sim）平台上的返回行为，以及 hangar 测试框架如何把wing test -t sim的运行结果固化为 Markdown 快照。读完本文，你将能理解 Bucket Key 的扁平化特性、读懂 hangar 快照文件每一行的含义，并掌握如何在本地复现这套测试。

一、这份快照文档是什么

bucket_keys.test.w_test_sim.md位于 tools/hangar/snapshots/test_corpus/valid/ 目录下，是 hangar（Wing 的端到端测试与快照框架）为tests/valid/bucket_keys.test.w生成的模拟器平台测试快照。文件命名遵循{测试文件名}_{用例}_{目标平台}.md的规则，其中：

• 测试用例：test
• 目标平台：sim（Wing 模拟器，本地运行环境）

文件首行# [bucket_keys.test.w](https://link.gitcode.com/i/7fb96d36c5f29d88976f17790636661e) | test | sim是一个带相对链接的标题，指向被快照的 Wing 源码文件；| test | sim说明该快照记录的是wing test在 sim 目标上的执行结果。快照正文只包含一个## stdout.log代码块，即测试运行的标准输出。

该测试属于tests/valid目录。根据 tests/README.md 的说明，/valid目录存放应当成功编译并运行的 Wing 示例，/invalid目录则存放应当失败的用例。bucket_keys.test.w属于前者，是验证 Bucket Key 语义的正向测试。

二、被快照的测试源码逐行解读

快照对应的 Wing 源码 tests/valid/bucket_keys.test.w 只有 17 行，核心逻辑如下：

bring cloud; let b = new cloud.Bucket(); test "test" { b.put("foo", "text"); b.put("foo/", "text"); b.put("foo/bar", "text"); b.put("foo/bar/", "text"); b.put("foo/bar/baz", "text"); let objs = b.list(); assert(objs.at(0) == "foo"); assert(objs.at(1) == "foo/"); assert(objs.at(2) == "foo/bar"); assert(objs.at(3) == "foo/bar/"); assert(objs.at(4) == "foo/bar/baz"); }

这段代码揭示了 Wing 对象存储的一个关键设计点：Bucket 的 Key 是扁平命名空间中的普通字符串，斜杠/只是 Key 的一部分，并不创建真实的目录层级。foo、foo/、foo/bar、foo/bar/、foo/bar/baz是五个彼此独立的对象 Key——注意foo/和foo/bar是两个不同的 Key，前者末尾带斜杠、后者没有，二者互不覆盖、同时存在。

这一点与 docs/api/04-standard-library/cloud/bucket.md 中对 Bucket 的官方描述一致：对象存储与文件存储不同，数据不是按层级结构组织，而是以扁平的 Key-Value 对象列表形式存在，每个对象关联一个 Key。所谓"前缀""目录"只是 Key 字符串层面的约定，由list(prefix)之类的 API 在应用层实现过滤语义。

测试代码还体现了 Wing 的test关键字用法：test "test" { ... }定义了一个在wing test下独立执行的测试用例。更完整的测试框架说明见 docs/docs/02-concepts/04-tests.md——Wing 的轻量测试框架围绕wing test命令与test关键字构建，允许同一套测试分别在模拟器和云端运行。

三、sim 平台的 list() 行为：从源码印证

该测试断言list()返回的数组索引0..4依次为foo、foo/、foo/bar、foo/bar/、foo/bar/baz，与写入顺序完全一致。为什么 sim 平台能保证这个顺序？答案在模拟器实现源码 packages/@winglang/sdk/src/target-sim/bucket.inflight.ts 中：

public async list(prefix?: string): Promise<string[]> { return this.context.withTrace({ message: `List (prefix=${prefix ?? "null"}).`, activity: async () => { return Array.from(this._metadata.keys()).filter((key) => { if (prefix) { return key.startsWith(prefix); } else { return true; } }); }, }); }

从源码可以推断出三点实现事实：

1. 顺序语义：_metadata是一个Map<string, ObjectMetadata>，Array.from(this._metadata.keys())按 Map 的插入顺序返回 Key 列表。这正是测试中foo、foo/、foo/bar、foo/bar/、foo/bar/baz按写入顺序返回的原因。换句话说，该测试的断言顺序成立的前提是 sim 平台基于插入有序的 Map 实现。
2. 前缀过滤：传入prefix时，通过key.startsWith(prefix)过滤，属于纯字符串前缀匹配，同样印证了"目录"只是 Key 字符串约定这一语义。
3. 键值落盘方式：addFile用hashKey(key)（crypto.createHash("sha512").update(key).digest("hex").slice(-32)，即 Key 的 SHA-512 哈希取后 32 位）作为磁盘文件名，再把内容写入模拟器的 state 目录；Key 本身记录在metadata.json中。所以即使 Key 包含/字符，也不会产生真实的文件系统嵌套目录。

需要提醒的是，list()的顺序约定属于 sim 平台的具体实现行为（由 packages/@winglang/sdk/src/target-sim/bucket.inflight.ts 可证）。不同云平台对list()返回顺序的保证可能不同，因此业务代码不应依赖特定顺序，除非该平台有明确的排序契约。

list(prefix)的签名定义在标准库接口 packages/@winglang/sdk/src/cloud/bucket.ts 中：inflight list(prefix?: str): MutArray<str>，语义为"返回 Bucket 中现有的对象 Key，prefix用于限制返回以指定前缀开头的 Key"。其余常用方法（put、get、delete、exists、putJson、getJson、tryGet、tryDelete、signedUrl、publicUrl、metadata、copy、rename等）也统一定义于该接口文件。

四、快照正文的含义与输出规范化

快照正文是一个log代码块，内容为wing test -t sim在bucket_keys.test.w上执行的标准输出：

pass ─ bucket_keys.test.wsim » root/Default/test:test Tests 1 passed (1) Snapshots 1 skipped Test Files 1 passed (1) Duration <DURATION>

逐行解读：

• pass ─ bucket_keys.test.wsim » root/Default/test:test：测试通过。bucket_keys.test.wsim是编译产物标识，root/Default/test:test是该测试用例在应用树中的路径（测试资源挂在root/Default之下，用例名为test）。
• Tests 1 passed (1)：1 个测试全部通过。
• Snapshots 1 skipped：本次快照统计中的占位/跳过信息（与 hangar 的快照机制相关）。
• Test Files 1 passed (1)：1 个测试文件通过。
• Duration <DURATION>：注意这里不是真实耗时，而是规范化后的占位符。真实输出本应是Duration 0m0.123s之类的数值。

<DURATION>的替换由 hangar 的sanitizeOutput完成，见 tools/hangar/src/utils.ts。该函数在生成快照前对命令输出做了一系列规范化处理：统一换行符、归一化 Windows 路径分隔符、抹去 Rust 源码行号（替换为:LINE:COL）、去除绝对路径（替换为<ABSOLUTE>）、隐藏.state状态文件、将测试耗时替换为<DURATION>、端口替换为<PORT>、IP 与时间戳替换为占位符等。这样做的目的是让快照在不同机器、不同时间上保持一致，避免非确定性输出导致快照对比失败——这正是把运行结果固化为可提交文档的关键工程手段。

五、hangar 如何生成这份快照：机制链路

要理解这份快照，需要了解 hangar 的生成流水线。整个链路由以下模块串联：

1. 目录定义tools/hangar/src/paths.ts：定义了testDir（tests）、validTestDir（tests/valid）、snapshotDir（tools/hangar/__snapshots__）等路径常量，并自动收集tests/valid下所有.w文件（排除*.skip.w）作为有效测试样本。
2. 测试用例生成tools/hangar/src/generate_tests.ts：遍历tests/valid等目录，为每个.w文件生成一个 vitest 测试文件，其中包含两个用例——wing compile -t tf-aws（编译快照）和wing test -t sim（运行快照）。bucket_keys.test.w的 sim 快照即来自后者。同时该文件还会解析 Wing 文件头部的元注释（见 tools/hangar/src/meta_comment.ts，支持skip、skipPlatforms、env、args等控制项）。
3. 执行与快照tools/hangar/src/generated_test_targets.ts：testTest函数调用runWingCommand（来自 tools/hangar/src/utils.ts）执行wing test（平台sim，带--no-update-check、--no-analytics），随后调用createMarkdownSnapshot（tools/hangar/src/utils.ts）把输出写入tools/hangar/__snapshots__/test_corpus/valid/bucket_keys.test.w_test_sim.md。文件名、标题链接、文件块结构都由该函数统一生成。
4. 输出规范化：写盘前，stdout/stderr 先经sanitizeOutput处理（上一节已述），从而保证快照内容可重复、可提交。

这套机制的本质是**"运行结果即文档"**：每次 CI 都会重新运行wing test -t sim并与仓库中的快照对比，任何输出变化都会导致快照不匹配，从而第一时间暴露行为回归。

六、本地复现：从快照回到命令行

如果你想在本地复现这份快照，方式如下。

安装并配置好 Wing CLI 后，在仓库根目录或tests/valid目录下执行：

wing test bucket_keys.test.w -t sim

• -t sim指定模拟器目标，它同时也是wing test的默认目标，可省略（见 docs/api/02-cli-user-manual.md 中关于wing test的说明与 docs/docs/02-concepts/04-tests.md）。
• 输出中会出现pass ─ bucket_keys.test.wsim » root/Default/test:test与Tests 1 passed (1)，与快照中的记录对应；本机输出的Duration数值会被快照机制规范化为<DURATION>。

如果改用云平台目标（例如wing test -t tf-aws），则会把测试部署到对应云环境执行；本文快照记录的是 sim 目标的运行结果，两者输出形态会有所差异。

七、这份测试想验证的工程价值

bucket_keys测试与其快照一起，构成了 Wing 对象存储行为契约的一部分：

• 语义契约：验证了 Bucket Key 是扁平字符串，/不产生真实层级，foo/与foo/bar可共存；
• API 契约：验证了list()返回全部 Key 且（在 sim 平台）保持插入顺序，为使用者提供可预测的行为；
• 回归保障：hangar 快照机制确保任何对 Bucket 存储、list()实现或测试输出的改动，都会在 CI 中与这份快照对比，从而及时暴露行为漂移。

深入阅读时可继续查看以下仓库资源：

• 测试源码：tests/valid/bucket_keys.test.w
• 快照生成结果：tools/hangar/snapshots/test_corpus/valid/bucket_keys.test.w_test_sim.md
• 标准库 Bucket 接口与文档：packages/@winglang/sdk/src/cloud/bucket.ts、docs/api/04-standard-library/cloud/bucket.md
• 模拟器实现：packages/@winglang/sdk/src/target-sim/bucket.inflight.ts、packages/@winglang/sdk/src/target-sim/bucket.ts
• hangar 框架：tools/hangar/src/paths.ts、tools/hangar/src/generate_tests.ts、tools/hangar/src/generated_test_targets.ts、tools/hangar/src/utils.ts

• 编程语言
• 编译器
• 云原生
• 语言运行时