企业官网建设流程全解析

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

本篇技术指南以 Wing 仓库中的tests/sdk_tests/bucket/events.test.w及其 hangar 编译快照（tools/hangar/__snapshots__/test_corpus/sdk_tests/bucket/events.test.w_compile_tf-aws.md）为切入点，深入剖析cloud.Bucket的onCreate、onUpdate、onDelete、onEvent事件 API 在tf-aws目标上的落地方式：从 Wing 源码中的事件声明，到 SDK 如何生成 S3 事件通知、SNS Topic、Lambda 函数、IAM 权限与 DynamoDB 计数器，最终形成可部署的 Terraform JSON（main.tf.json）。读完本文，你将掌握 Wing Bucket 事件模型的编程范式、事件类型与 S3 事件的映射关系、编译产物的资源结构，以及如何像 hangar 一样用快照验证编译结果。

一、事件测试用例：它验证了什么

快照文档标题即指向其源测试文件 events.test.w，该用例位于 tests/sdk_tests/bucket 目录下，与put、delete、copy、bucket_list等 20 余个用例并列，专门用于验证 Bucket 对象事件的触发次数是否符合预期。

测试的核心场景如下：

bring cloud; bring util; enum Source { anyEvent, // 由 onCreate/onUpdate/onDelete 触发 onEvent // 由 onEvent 触发 } let b = new cloud.Bucket(); let idsCounter = new cloud.Counter(); let logs = new cloud.Bucket() as "LogHistory"; let logHistory = inflight (key: str, operation: str, source: Source) => { logs.putJson("{idsCounter.inc()}", Json { key: key, operation: operation, source: "{source}" }); }; b.onDelete(inflight (key: str) => { logHistory(key, "OnDelete()", Source.anyEvent); }); b.onUpdate(inflight (key: str) => { logHistory(key, "OnUpdate()", Source.anyEvent); }); b.onCreate(inflight (key: str) => { logHistory(key, "OnCreate()", Source.anyEvent); }); b.onEvent(inflight (key: str, event: cloud.BucketEventType) => { logHistory(key, "{event}()", Source.onEvent); });

测试语义可概括为：

• 创建一个主 Bucketb、一个cloud.Counter（用于生成唯一日志编号）和一个名为LogHistory的日志 Bucket；
• 通过b.onDelete / b.onUpdate / b.onCreate为单类事件注册 inflight 处理器（对应Source.anyEvent），再通过b.onEvent注册一个覆盖所有事件类型的处理器（对应Source.onEvent）；
• 每个事件处理器将(key, operation, source)三元组以 JSON 形式写入日志 Bucket，key 使用idsCounter.inc()保证唯一性。

随后在std.Test中执行一系列写操作并校验事件计数：

new std.Test(inflight () => { b.put("a", "1"); b.put("b", "1"); b.put("c", "1"); b.put("b", "100"); // 覆盖 b → 触发一次 Update b.delete("c"); // 删除 c → 触发一次 Delete // https://github.com/winglang/wing/issues/2724 if @target != "tf-aws" { checkHitCount(key: "a", type: "OnCreate()", source: Source.anyEvent, count: 1); // ... 对 b、c 的 OnCreate / OnUpdate / OnDelete 计数断言 } }, timeout: 8m) as "hitCount is incremented according to the bucket event";

期望的计数结果：a触发 1 次 Create；b触发 1 次 Create 与 1 次 Update（因被覆盖写入）；c触发 1 次 Create 与 1 次 Delete。注意代码注释中的 issue 引用：由于tf-aws上 S3 事件通知存在一定的最终一致性与事件合并特性，测试在@target != "tf-aws"时才执行严格计数断言，这是仓库源码中明确记录的已知边界（对应 events.test.w）。

二、事件 API 与事件类型：SDK 层的声明

事件模型定义在 SDK 的 cloud/bucket.ts 中，核心是BucketEventType枚举：

export enum BucketEventType { CREATE = "OnCreate", DELETE = "OnDelete", UPDATE = "OnUpdate", }

四个事件 API 均接受一个IBucketEventHandler（即携带handle(key: string, type: BucketEventType)签名的 inflight 处理器），当前版本中传入的 options 对象会被忽略并打印警告（bucket.onCreate does not support options yet）：

从 cloud/bucket.ts 的createBucketEvent私有方法可以看到事件机制的内部骨架：每个BucketEventType对应一个内部cloud.Topic（通过_topicsMap 惰性创建并缓存，见getTopic），事件处理器通过topic.onMessage(...)订阅；同时通过构造器连接（connection）将put/putJson/delete/tryDelete等写方法与对应 Topic 的publish操作关联起来。这正是 Wing 应用树（application tree）中"事件订阅即连接"的体现。

onEvent则是一次性订阅全部三类事件，处理器会额外收到cloud.BucketEventType参数，从而在回调中区分具体事件类型——这也是测试中用"{event}()"拼接出OnCreate()/OnUpdate()/OnDelete()日志文本的原因。

三、tf-aws 平台的实现：S3 事件通知 → SNS → Lambda

在tf-aws目标上，抽象的事件订阅被编译为一条完整的 AWS 资源链，实现集中在 target-tf-aws/bucket.ts 与 target-tf-aws/topic.ts。

3.1 事件类型到 S3 事件的映射

target-tf-aws/bucket.ts 定义了关键映射表：

const EVENTS = { [cloud.BucketEventType.DELETE]: ["s3:ObjectRemoved:*"], [cloud.BucketEventType.CREATE]: ["s3:ObjectCreated:Put"], [cloud.BucketEventType.UPDATE]: ["s3:ObjectCreated:Post"], };

即：onCreate→s3:ObjectCreated:Put（普通 PUT 上传）；onUpdate→s3:ObjectCreated:Post（对已存在对象的覆盖写）；onDelete→s3:ObjectRemoved:*（所有删除类型）。

3.2 资源生成流程

在 tf-aws 的Bucket.createTopic中，每次注册事件都会：

1. 创建一个 SNS Topic（aws_sns_topic），命名形如OnCreate-c8b721b0；
2. 通过addPermissionToPublish授权s3.amazonaws.com服务主体对该 Topic 执行sns:Publish（生成aws_sns_topic_policy，并使用aws:SourceArn条件限定只能来自本 Bucket）；
3. 将(id: "on-oncreate-notification", events: [...], topicArn)记入notificationTopics数组；
4. 在_preSynthesize阶段统一生成一个aws_s3_bucket_notification资源，把 Bucket 的三个事件绑定到对应 SNS Topic，并dependsOn三个 Topic 策略以保证权限先于通知创建。

而 target-tf-aws/topic.ts 的onMessage则为每个订阅创建一个 Lambda 函数（aws_lambda_function），并通过aws_sns_topic_subscription（protocol 为lambda）将 SNS Topic 与函数关联，同时授予 SNS 服务调用该函数的aws_lambda_permission。

最终形成的事件链路：

S3 Bucket 写操作 → aws_s3_bucket_notification（按事件类型分发） → SNS Topic（OnCreate / OnUpdate / OnDelete） → SNS Topic 策略（s3.amazonaws.com 可 Publish，限定 SourceArn） → Lambda 函数（事件处理器） → CloudWatch Log Group（日志）

3.3 SNS 消息解析

SNS 投递给 Lambda 的原始消息由 shared-aws/bucket.ts 的BucketEventHandler.toTopicOnMessageHandler解析：它会先忽略 AWS 在真实事件前发送的s3:TestEvent测试消息，再从message.Records[0].s3.object.key中提取对象 key，连同事件类型一起回调用户处理器。这解释了为何 SNS 通知事件不会污染用户的计数验证。

四、快照main.tf.json逐资源解读

快照文档events.test.w_compile_tf-aws.md的核心内容，就是 hangar 对上述用例执行wing compile -t tf-aws后生成的完整 main.tf.json。下面按资源类型解读其含义（资源名即快照中的uniqueId）。

4.1 存储资源：三个 S3 Bucket

"aws_s3_bucket": { "Bucket": { "//": { "metadata": { "path": "root/Default/Default/Bucket/Default", "uniqueId": "Bucket" } }, "bucket_prefix": "bucket-c88fdc5f-", "force_destroy": false } }

bucket_prefix由 target-tf-aws/bucket.ts 的BUCKET_PREFIX_OPTS规则生成：全小写、禁止点号、最大 37 字符并以-结尾，Terraform 自动补充随机后缀。此外createEncryptedBucket会校验前缀不能以xn--开头、必须以字母或数字开头。

4.2 计数器：DynamoDB 表

cloud.Counter在 tf-aws 上落地为一张 DynamoDB 表：

"aws_dynamodb_table": { "Counter": { "//": { "metadata": { "path": "root/Default/Default/Counter/Default", "uniqueId": "Counter" } }, "attribute": [{ "name": "id", "type": "S" }], "billing_mode": "PAY_PER_REQUEST", "hash_key": "id", "name": "wing-counter-Counter-c824ef62" } }

采用PAY_PER_REQUEST按量计费模式，哈希键为id（字符串）。事件处理器中的idsCounter.inc()在快照中体现为 Lambda IAM 策略里的dynamodb:UpdateItem权限。

4.3 六个事件处理函数：Lambda

测试注册了 4 个处理器，但 onCreate / onUpdate / onDelete 的anyEvent处理器与 onEvent 的处理器并非同一函数，因此编译出 6 个 Lambda（每组OnCreate/OnUpdate/OnDelete各两个），例如：

"aws_lambda_function": { "Bucket_OnCreate-OnMessage0_4C972FB4": { "//": { "metadata": { "path": "root/Default/Default/Bucket/OnCreate-OnMessage0/Default", "uniqueId": "Bucket_OnCreate-OnMessage0_4C972FB4" } }, "architectures": ["arm64"], "environment": { "variables": { "BUCKET_NAME_76338bfb": "${aws_s3_bucket.LogHistory.bucket}", "DYNAMODB_TABLE_NAME_6cb5a3a4": "${aws_dynamodb_table.Counter.name}", "NODE_OPTIONS": "--enable-source-maps", "WING_FUNCTION_NAME": "OnCreate-OnMessage0-c8740b4b", "WING_TARGET": "tf-aws" } }, "function_name": "OnCreate-OnMessage0-c8740b4b", "handler": "index.handler", "logging_config": { "log_format": "JSON" }, "memory_size": 1024, "publish": true, "runtime": "nodejs20.x", "s3_bucket": "${aws_s3_bucket.Code.bucket}", "s3_key": "${aws_s3_object.Bucket_OnCreate-OnMessage0_S3Object_3AC22680.key}", "timeout": 60, "vpc_config": { "security_group_ids": [], "subnet_ids": [] } } }

关键参数解读：

• runtimenodejs20.x、架构arm64、内存 1024 MB、超时 60 秒：这是当前仓库版本 Wing 为事件处理函数生成的默认运行时配置；
• publish: true：每次部署发布函数新版本，配合 SNS 订阅的 Lambda 别名策略；
• handler: "index.handler"：指向 Wing 编译器生成的 JS bundle 入口；
• 代码包：每个函数对应一个aws_s3_object（Bucket_OnCreate-OnMessage0_S3Object_3AC22680等），上传到CodeBucket，s3_key以<ASSET_KEY>占位，表示由 Wing CLI 在构建阶段注入真实资产位置；
• 环境变量：BUCKET_NAME_76338bfb指向LogHistory（lift 机制注入的 Bucket 名称，命名规则见 shared-aws/bucket.ts 的BUCKET_NAME_${addr.slice(-8)}）；DYNAMODB_TABLE_NAME_6cb5a3a4指向 Counter；WING_TARGET=tf-aws标记目标平台；NODE_OPTIONS=--enable-source-maps启用源码映射便于调试；
• 日志：每个函数配套一个aws_cloudwatch_log_group，命名/aws/lambda/<function_name>（如/aws/lambda/OnCreate-OnMessage0-c8740b4b），retention_in_days: 30，log_format: JSON。

4.4 S3 事件通知：aws_s3_bucket_notification

这是整个事件链路的枢纽资源，将 Bucket 的 S3 事件按类型路由到三个 SNS Topic：

"aws_s3_bucket_notification": { "Bucket_S3BucketNotification_D5E2F72C": { "//": { "metadata": { "path": "root/Default/Default/Bucket/S3BucketNotification", "uniqueId": "Bucket_S3BucketNotification_D5E2F72C" } }, "bucket": "${aws_s3_bucket.Bucket.id}", "depends_on": [ "aws_sns_topic_policy.Bucket_OnDelete_PublishPermission-..._89434C6B", "aws_sns_topic_policy.Bucket_OnUpdate_PublishPermission-..._9BF3340C", "aws_sns_topic_policy.Bucket_OnCreate_PublishPermission-..._E9DA9F8C" ], "topic": [ { "events": ["s3:ObjectRemoved:*"], "id": "on-ondelete-notification", "topic_arn": "${aws_sns_topic.Bucket_OnDelete_0EB7243C.arn}" }, { "events": ["s3:ObjectCreated:Post"], "id": "on-onupdate-notification", "topic_arn": "${aws_sns_topic.Bucket_OnUpdate_E297838E.arn}" }, { "events": ["s3:ObjectCreated:Put"], "id": "on-oncreate-notification", "topic_arn": "${aws_sns_topic.Bucket_OnCreate_9682272C.arn}" } ] } }

该资源的生成逻辑与 target-tf-aws/bucket.ts 的_preSynthesize完全对应：topic数组来自createTopic中累积的notificationTopics，depends_on则引用三个aws_sns_topic_policy，确保 S3 的发布权限先于通知配置生效（否则 Terraform 创建通知时会因权限未就绪而失败）。

4.5 消息路由：SNS Topic、策略与订阅

快照中创建了 3 个 SNS Topic（OnCreate-c8b721b0、OnDelete-c8951577、OnUpdate-c81749ea），每个 Topic 配套：

• aws_sns_topic_policy：授权s3.amazonaws.com发布，并带有aws:SourceArn条件精确限定源 Bucket，防止跨账户/跨桶误发：

"policy": "{\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"s3.amazonaws.com\"},\"Action\":\"sns:Publish\",\"Resource\":\"${aws_sns_topic.Bucket_OnCreate_9682272C.arn}\",\"Condition\":{\"ArnEquals\":{\"aws:SourceArn\":\"${aws_s3_bucket.Bucket.arn}\"}}}]}"

• aws_sns_topic_subscription：每个事件类型两个订阅（对应两个处理器函数），protocol: "lambda"、endpoint指向对应 Lambda 的 ARN；
• aws_lambda_permission：允许sns.amazonaws.com主体调用对应 Lambda（action: "lambda:InvokeFunction"，source_arn限定为 SNS Topic）。

4.6 最小权限 IAM

每个事件函数都有一组 IAM 资源（快照中Bucket_OnCreate-OnMessage0_IamRole_*、IamRolePolicy_*、IamRolePolicyAttachment_*三件套）：

• aws_iam_role：信任策略仅允许lambda.amazonaws.com执行sts:AssumeRole；
• aws_iam_role_policy：内联策略精确授予两个最小权限集——dynamodb:UpdateItem（对应 Counter 的inc()）与s3:PutObject*/s3:Abort*（对应向LogHistory写入日志），Resource 分别限定到 Counter 表与LogHistoryBucket（含前缀/*）；
• aws_iam_role_policy_attachment：附加 AWS 托管策略AWSLambdaBasicExecutionRole（提供 CloudWatch 日志写入能力）。

由此可见，事件处理函数只获得了执行其业务逻辑所需的最小权限，这与 Wing SDK 的calculateBucketPermissions（见 shared-aws/bucket.ts 的onLift权限计算）一致：用户 inflight 代码 lift 了哪些 Bucket/Counter 操作，编译产物就生成对应的 IAM 策略。

五、测试验证机制：waitUntil 轮询计数

checkHitCount采用了"轮询直到断言成立"的验证模式，其底层是util.waitUntil：

let checkHitCount = inflight (opts: CheckHitCountOptions): void => { util.waitUntil(inflight () => { let var count = 0; for u in logs.list() { let data = logs.getJson(u); if (data.get("key") == opts.key && data.get("operation") == opts.type && data.get("source") == "{opts.source}") { count = count + 1; } } return count == opts.count; }, timeout: 2m, interval: 10s); };

其语义：每 10 秒遍历一次LogHistory，统计与(key, operation, source)匹配的日志条数，直到达到预期计数或 2 分钟超时。对应 SDK 中 util/util.ts 的waitUntil实现：默认超时 1 分钟、轮询间隔 0.1 秒（此处显式覆盖为 2m / 10s）；若谓词在超时前返回true则成功返回，否则抛出"Timeout elapsed"错误。整体测试用例std.Test的超时设为 8 分钟（timeout: 8m）。

这种轮询设计是刻意为之：S3 事件通知属于异步分发，事件到达 SNS/Lambda 存在延迟，因此不能同步断言，必须等待事件最终送达。也正因如此，测试对tf-aws目标做了跳过处理（issue 2724），仅在其他目标上执行严格计数。

六、快照与 hangar：如何复现与验证编译产物

本文剖析的快照文件是 Wing 工具链测试框架 hangar（位于 tools/hangar）的产物。hangar 的测试目录布局如下：

• 源测试用例：tests/sdk_tests/bucket/events.test.w（以及tests/sdk_tests下 api、queue、math、std 等 20 余个资源模块的用例）；
• 编译快照：tools/hangar/snapshots目录，按test_corpus/sdk_tests/bucket/组织结构保存每个用例在tf-aws（以及 sim 等其他目标）下的编译结果，命名规则为<用例名>_compile_<目标>.md；
• 快照生成逻辑：tools/hangar/src 中的generate_tests.ts、paths.ts（定义snapshotDir路径）与utils.ts。

hangar 的工作方式可概括为：将每个.test.w用例以指定目标平台执行wing compile，把生成的main.tf.json序列化为 Markdown 快照，与既有快照比对（snapshot 测试）；任何源码或编译器改动导致编译产物变化，都会通过快照 diff 暴露出来。因此，像events.test.w_compile_tf-aws.md这样的快照不仅是 Terraform 配置的真实记录，更是 SDK 生成逻辑的回归测试基线——当你修改 cloud/bucket.ts 或 target-tf-aws/bucket.ts 的事件实现时，本快照就是校验"编译产物是否符合预期"的第一道防线。

要在本地复现该编译产物，可在仓库根目录执行wing compile -t tf-aws（配合 package.json 中配置的构建脚本与 tools/hangar 的 vitest 配置运行快照测试）。需要注意的是：快照中的<ASSET_KEY>/<ASSET_SOURCE>为资产占位符，真实部署时由 Wing CLI 构建阶段填充。

七、小结

通过events.test.w及其 tf-aws 快照，可以完整看到 Wing "单一语言模型"在 Bucket 事件场景下的价值：开发者只需用onCreate/onUpdate/onDelete/onEvent声明式订阅，SDK 便自动生成 S3 事件通知、SNS Topic、Lambda 函数、CloudWatch 日志、DynamoDB 计数、最小权限 IAM 以及 SNS 发布/调用权限共 12 类 Terraform 资源（快照中可见aws_cloudwatch_log_group、aws_dynamodb_table、aws_iam_role、aws_iam_role_policy、aws_iam_role_policy_attachment、aws_lambda_function、aws_lambda_permission、aws_s3_bucket、aws_s3_bucket_cors_configuration、aws_s3_bucket_notification、aws_s3_object、aws_sns_topic、aws_sns_topic_policy、aws_sns_topic_subscription），且每个资源都遵循最小权限原则。这种"抽象 API + 平台编译产物 + 快照回归"的三层结构，正是 Wing 云编程模型在 tests/sdk_tests 与 tools/hangar/snapshots中的典型呈现方式。

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