Wing 云存储对象删除语义详解:从 delete.test.w 的 sim 快照测试到多平台实现
Wing 云存储对象删除语义详解:从 delete.test.w 的 sim 快照测试到多平台实现
导读
本文以 Wing 开源仓库中 cloud.Bucket 的删除能力为核心,围绕 hangar 测试框架生成的 sim 运行快照 delete.test.w_test_sim.md 及其配套测试源码展开。你将完整掌握 Wing 中 Bucket.delete() 的调用方式、mustExist 选项的严格删除语义、对象不存在的错误处理策略,以及同一套代码在模拟器(sim)与 AWS/Azure/GCP 等真实云平台上如何落地,并学会通过 hangar 快照理解 SDK 行为契约。
一、快照文件解读:一条 "pass" 的 sim 测试记录
1.1 快照文件的结构与来源
仓库中的 delete.test.w_test_sim.md 是 hangar 测试框架为测试用例 tests/sdk_tests/bucket/delete.test.w 在 sim(本地模拟器)目标 下运行后自动生成的 Markdown 快照。快照头部明确标注了三个关键信息:
- 来源测试文件:
tests/sdk_tests/bucket/delete.test.w; - 测试阶段:
test(即执行测试,而非仅编译); - 运行目标:
sim(Wing 本地模拟器)。
该文件的主体是 stdout.log 代码块,记录了测试执行的标准输出:
pass ─ delete.test.wsim » root/Default/test:delete
Tests 1 passed (1)
Snapshots 1 skipped
Test Files 1 passed (1)
Duration <DURATION>
从中可以看到,delete.test.w 在 sim 目标下定义了一个名为 delete 的测试用例,运行结果为 pass;Tests 1 passed (1) 表示全部 1 个测试通过,Duration <DURATION> 为测试框架对耗时的占位符(快照机制会抹平易变的执行时间,保证快照内容可稳定比对)。
1.2 快照的生成机制
这类快照并非手写,而是由 hangar 工具在运行测试时自动生成并落盘。在 tools/hangar/src/utils.ts 中,createMarkdownSnapshot() 函数会将测试产生的输出文件(如 stdout.log、main.tf.json)写入 tools/hangar/__snapshots__/test_corpus/<相对路径>/<测试文件>_<阶段>_<目标>.md,并自动生成指向原始测试文件的相对链接——这正是快照文件首行 # <a href="https://link.gitcode.com/i/c5ac5f43de9bd39c2f85911cf96c96a3" target="_blank">delete.test.w</a> 的来源。快照目录由 tools/hangar/src/paths.ts 中的 snapshotDir 常量定义。
因此,这份快照是 Wing SDK 行为契约的可执行证据:只要 cloud.Bucket.delete() 的语义发生变化,对应的 sim 快照或编译快照就会在回归测试中产生 diff,从而暴露行为变更。
二、测试用例逐行分析:delete() 的完整行为契约
快照背后真正的"行为定义"是测试源码 tests/sdk_tests/bucket/delete.test.w。它只引入 cloud 库,创建一个 Bucket 并通过预置对象与多次 delete 调用,覆盖了删除场景的三种关键形态。
2.1 前置准备:预置对象与断言辅助函数
bring cloud;
let b = new cloud.Bucket();
b.addObject("file2.txt", "Bar");
test "delete" {
let assertThrows = (expected: str, block: (): void) => {
let var error = false;
try {
block();
} catch actual {
assert(actual.contains(expected));
error = true;
}
assert(error);
};
...
}
new cloud.Bucket()在 sim 目标下对应本地文件系统实现,而在tf-aws目标下则对应一个 S3 桶。这一点可以在同目录的编译快照 delete.test.w_compile_tf-aws.md 中得到印证:其中生成了aws_s3_bucket资源,以及名为Bucket_S3Object-file2txt_2016A6BF的aws_s3_object(key 为file2.txt,content 为"Bar"),说明addObject在部署阶段就预置了对象。assertThrows是一个闭包辅助函数:执行传入的block(),若抛出异常则断言异常信息包含期望子串,同时通过assert(error)确保异常确实被抛出。它用于验证"必须存在的删除"在对象缺失时会抛错。
2.2 第一段:写入 JSON 对象并删除不存在的 key
let OBJECT_DOES_NOT_EXIST_ERROR = "Object does not exist (key=file1.json).";
let jsonObj1 = Json { key1: "value1" };
b.putJson("file1.json", jsonObj1);
b.delete("file1.txt");
assert(b.exists("file1.json"));
assert(b.exists("file2.txt"));
b.putJson("file1.json", jsonObj1)通过 JSON 写入 API 创建对象(对应 SDK 接口 bucket.ts 中的putJson(key, body))。- 关键点:
b.delete("file1.txt")删除的 key 并不存在(真正写入的是file1.json)。由于未传mustExist选项,这次删除 静默成功、不抛错——这是"非严格删除"的默认语义。 - 随后两个
exists断言确认file1.json与file2.txt都仍然存在,证明静默删除没有误删其他对象。
2.3 第二段:严格删除成功与失败
b.delete("file1.json", mustExist: true);
assertThrows(OBJECT_DOES_NOT_EXIST_ERROR, () => {
b.delete("file1.json", mustExist: true);
});
assert(b.exists("file2.txt"));
b.delete("file2.txt");
assert(!b.exists("file2.txt"));
b.delete("file1.json", mustExist: true)对存在的对象执行严格删除,成功返回。- 紧接着再次对
file1.json执行同样调用,此时对象已不存在,delete抛出错误信息Object does not exist (key=file1.json).,assertThrows验证了异常内容与"确实抛错"两个事实。 assert(b.exists("file2.txt"))再次确认预置对象未被波及。- 最后
b.delete("file2.txt")删除预置对象,并用assert(!b.exists("file2.txt"))确认删除生效。
综合起来,测试用例把 delete() 的行为契约锁死为三条:
- 默认(
mustExist: false)删除不存在的 key 时静默成功; mustExist: true删除存在的 key 时正常删除;mustExist: true删除不存在的 key 时抛出异常,异常信息格式为Object does not exist (key=<key>).。
三、底层接口定义:BucketDeleteOptions 与 delete 签名
Wing 云抽象层的 cloud.Bucket 将删除能力定义为 inflight 方法,源码位于 packages/@winglang/sdk/src/cloud/bucket.ts:
delete(key: string, opts?: BucketDeleteOptions): Promise<void>;
配套的选项接口 BucketDeleteOptions 只有一个字段:
| 字段 | 类型 | 默认值 | 语义 |
|---|---|---|---|
mustExist |
boolean |
false |
若为 true,当对象不存在(或其他错误场景)时抛出异常;false 时静默忽略"对象不存在" |
delete 是 inflight(运行时)方法,返回 Promise<void>,没有布尔返回值。若调用方需要"删除并获知是否真的删掉了",应改用接口中的 tryDelete(key):它返回 Promise<boolean>,对象存在则删除并返回 true,否则返回 false。
同一接口中还有配套的存在性检查 exists(key): Promise<boolean>(bucket.ts)与 putJson(key, body)(bucket.ts),测试用例正是用它们来验证删除前后状态。
四、多平台实现印证:同一语义,不同后端
Wing 的"一次编写、多平台部署"理念体现在 delete() 为每个目标提供了独立实现,但错误语义完全一致。
4.1 AWS(S3)实现
在 shared-aws/bucket.inflight.ts 中:
public async delete(key: string, opts?: BucketDeleteOptions): Promise<void> {
const mustExist = opts?.mustExist ?? false;
if (mustExist && !(await this.exists(key))) {
throw new Error(`Object does not exist (key=${key}).`);
}
const command = new DeleteObjectCommand({
Key: key,
Bucket: this.bucketName,
});
try {
await this.s3Client.send(command);
} catch (error) {
if (!mustExist && error instanceof NoSuchKey) {
return;
}
throw new Error(`Failed to delete object (key=${key}).`);
}
}
实现要点:
mustExist默认为false,与接口定义一致;mustExist: true时先通过exists()预检,不存在则抛出与测试断言完全一致的Object does not exist (key=${key}).错误;- 默认模式下捕获 S3 的
NoSuchKey异常并静默返回,实现"删除不存在的 key 不报错"; - 其余非
NoSuchKey的错误统一包装为Failed to delete object (key=${key}).。
4.2 sim(本地模拟器)实现
在 target-sim/bucket.inflight.ts 中,删除逻辑基于本地文件系统:
const mustExist = opts?.mustExist ?? false;
if (!this._metadata.has(key) && mustExist) {
throw new Error(`Object does not exist (key=${key}).`);
}
if (!this._metadata.has(key)) {
return;
}
const hash = this.hashKey(key);
const filename = join(this._fileDir, hash);
await fs.promises.unlink(filename);
this._metadata.delete(key);
await this.notifyListeners(BucketEventType.DELETE, key);
- 通过
_metadata元数据判断 key 是否存在,mustExist: true时同样抛出相同格式的错误; - 默认模式下 key 不存在则直接
return(静默); - 删除会
unlink哈希命名的本地文件、移除元数据,并通过notifyListeners(BucketEventType.DELETE, key)触发删除事件通知——这与模拟器的事件系统相衔接。
4.3 Azure 与 GCP 实现
同样的契约也存在于其他云平台:
- Azure 实现位于 shared-azure/bucket.inflight.ts,同样解析
opts.mustExist,并在mustExist且对象缺失时抛错; - GCP 实现位于 shared-gcp/bucket.inflight.ts,逻辑与 AWS 版本基本一致,仅在
!mustExist && error.code === 404时静默返回。
三个平台实现相互印证:Object does not exist (key=...). 错误格式与 mustExist 默认关闭的语义是跨平台统一的 SDK 契约,这正是测试快照能够"一次编写、多处验证"的基础。
五、快照测试在研发流程中的价值
5.1 快照作为回归防线
delete.test.w 在 sim 目标下的通过记录(Tests 1 passed (1))与 tf-aws 目标下的 Terraform 输出快照共同构成双层验证:
- 行为验证(test + sim):确保
delete()的运行语义正确; - 基础设施验证(compile + tf-aws):确保预置对象、桶配置等声明式资源被正确翻译为
aws_s3_bucket、aws_s3_object等 Terraform 资源。
任何改动如果改变了 delete() 的错误信息、mustExist 默认值或 S3 资源配置,都会在 hangar 的黄金快照比对中暴露出来。
5.2 快速定位问题
当你在自己的 Wing 项目里遇到"删除对象时报错/不报错"的困惑时,可以:
- 对照 delete.test.w 理解
mustExist的两种模式; - 查看同目录下其他 bucket 测试(
tests/sdk_tests/bucket/下还有 20 余个覆盖读写、列表、签名单 URL 等能力的用例); - 结合 bucket.ts 的接口文档确认默认值与异常契约。
六、实战建议:如何选择删除策略
基于以上契约,在实际的 Wing 云应用中可按场景选择删除方式:
| 场景 | 推荐 API | 说明 |
|---|---|---|
| 删除已知存在的数据,失败时应告警 | b.delete(key, mustExist: true) |
对象缺失即抛 Object does not exist 异常,适合清理任务、数据迁移 |
| 幂等清理,允许对象缺失 | b.delete(key) |
不存在的 key 静默跳过,适合重复执行的定时清理 |
| 需要得知"是否真的删除了" | b.tryDelete(key) |
返回 boolean,存在则删并返回 true,否则返回 false |
| 删除前确认对象状态 | b.exists(key) 配合 b.delete(...) |
适合需要自定义错误处理或日志记录的删除流程 |
注意 delete 与 tryDelete 都是 inflight 方法,只能在运行时(inflight 上下文,例如 test 块、处理器函数)中调用,不能在部署期直接执行——这是 Wing 的 preflight/inflight 阶段模型对云资源操作的基本约束。
结语
一份看似只有几行日志的 sim 快照 delete.test.w_test_sim.md,背后其实是 Wing SDK 对"对象删除"这一基础操作的全套契约设计:mustExist 选项区分严格与非严格删除、统一的 Object does not exist (key=...). 错误格式、以及 sim/AWS/Azure/GCP 四个目标端的一致实现。理解这套契约,无论是编写云存储业务逻辑,还是排查删除相关故障,都能做到有的放矢。