Wing 云存储对象删除语义详解:从 delete.test.w 的 sim 快照测试到多平台实现

原创2026-10-14 09:37:581,861 阅读
文章标签:编程语言编译器云原生语言运行时

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() 的行为契约锁死为三条:

  1. 默认(mustExist: false)删除不存在的 key 时静默成功;
  2. mustExist: true 删除存在的 key 时正常删除;
  3. 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 实现

同样的契约也存在于其他云平台:

三个平台实现相互印证: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 项目里遇到"删除对象时报错/不报错"的困惑时,可以:

  1. 对照 delete.test.w 理解 mustExist 的两种模式;
  2. 查看同目录下其他 bucket 测试(tests/sdk_tests/bucket/ 下还有 20 余个覆盖读写、列表、签名单 URL 等能力的用例);
  3. 结合 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 四个目标端的一致实现。理解这套契约,无论是编写云存储业务逻辑,还是排查删除相关故障,都能做到有的放矢。

登录后查看全文
wing