编程语言编译器云原生语言运行时【免费下载链接】wingA programming language for the cloud ☁️ A unified programming model, combining infrastructure and runtime code into one language ⚡项目地址https://gitcode.com/gh_mirrors/wi/wing点击查看免费下载云上测试成本高昂、耗时漫长如何在不真正部署到云端的前提下持续验证 Wing 应用与依赖库的合成输出没有回归Wing 在wing test中内置了一套云测试快照cloud test snapshots机制当针对tf-aws等云端目标运行测试且全部通过时框架会自动把编译器产物快照捕获到入口文件.tf-aws.snap.md并在 CI 中仅做零部署比对。本文以仓库中真实存在的快照样例 main.w.tf-aws.snap.md 为解剖对象逐段讲解快照文件的生成规则、字段含义并深入到 snapshots.ts 源码与官方 CLI 文档帮助你掌握快照的完整生命周期何时捕获、如何断言、怎样更新。一、为什么需要云测试快照Wing 的测试框架支持两个层面的测试在本地模拟器sim中快速执行以及通过-t tf-aws等目标部署到真实云环境执行。针对云端目标逐条运行测试虽然真实却存在明显的现实约束——正如 RFC 2024-03-24-snapshot-tests.md 中所描述的每次提交都在真实云上跑完全部测试既不现实耗时很长也代价高昂云资源费用同时还需要维护一套复杂的 AWS 账号环境。云测试快照正是为缓解这一约束而生的轻量方案。其设计思路与 AWS CDK 的集成测试快照类似在本地开发环境完整部署并跑通测试后捕获一份合成输出快照提交进仓库在 CI 环境中不再部署而是重新合成输出并与快照比对。一旦输出发生变化例如 SDK 升级、依赖变更、代码改动导致 IaC 模型变化测试就会失败并给出 diff从而在没有云环境的情况下捕获回归。从 snapshots-help.ts 中可以看到该机制的官方描述When testing against a cloud target (e.g. -t tf-aws), if all tests pass, the compiler output will be captured under entrypoint.snap.md.即只有云目标非sim且测试全部通过时才会生成快照。二、快照的捕获流程与命名规则2.1 触发时机先测试后快照在 test.ts 的testOne流程中快照捕获被严格置于测试成功之后首先根据目标平台计算快照模式determineSnapshotMode若需要执行sim或DEPLOY模式则编译并把应用部署到目标平台执行测试一旦有任一测试失败则跳过快照捕获success !results.some((r) !r.pass)全部通过后才调用captureSnapshot。值得注意的是为了让快照可复现测试编译时会把 root id 固定为rootrootId: (options.rootId ?? target sim) ? root : ...而普通云测试则使用随机 id。这正是快照中能看到path: root/Default/Default/Bucket/Default、stackName: root等稳定标识的原因。2.2 命名规则entrypoint.target.snap.md快照文件的命名在 snapshots.ts 中定义const snapshotFile ${entrypoint}.${target}.snap.md;因此示例入口main.w针对tf-aws目标生成的快照即为main.w.tf-aws.snap.md与本文分析的 fixture 完全一致。官方 CLI 文档 02-cli-user-manual.md 中的示例也印证了这一点test_bucket.test.w跑通后会生成test_bucket.test.w.tf-aws.snap.md。2.3 快照内容Markdown 包装的合成产物createMarkdownSnapshotsnapshots.ts会遍历合成输出目录按扩展名收集文件并组装成标准 Markdown包含的文件类型**/*.js、**/*.json、**/*.tf、**/*.ts、**/*.yaml、**/*.yml排除的文件connections.json、tree.json、**/*.zip、**/*.map以及所有以.开头的隐藏目录如.wing通过dot: false排除安全性检查若产物中出现绝对路径的require(...)调用如/...或C:\...捕获会直接失败避免快照携带不可移植的绝对路径。最终createMarkdown生成如下模板结构# main.w.tf-aws.snap.md ## main.tf.json json { ... }即每个合成文件占一个 ## 小节语言标签取自文件扩展名。本文的 fixture 只包含一个 main.tf.json 文件这是 Wing 编译器针对 tf-aws 目标合成的 Terraform 配置。 ## 三、逐段解读 main.w.tf-aws.snap.md ### 3.1 顶层结构 json { //: { metadata: { backend: local, stackName: root, version: 0.20.7 }, outputs: {} }, provider: { aws: [ {} ] }, resource: { ... }, terraform: { ... } }//.metadataCDKTF 生成的元信息。backend: local表示使用本地 Terraform 状态后端stackName: root对应合成栈名与 2.1 中固定 root id 相呼应version: 0.20.7是当前仓库 winglang 包对应的编译器/SDK 版本号版本变化本身不会自动改写快照但会引起合成输出差异从而触发断言失败。provider.aws声明了 AWS provider此处为空对象因为本样例无需显式 provider 配置。resource实际创建的云资源本例为 S3 桶及其 CORS 配置。terraformTerraform 后端与 provider 版本锁定详见 3.4。3.2aws_s3_bucket桶资源与命名前缀aws_s3_bucket: { Bucket: { //: { metadata: { path: root/Default/Default/Bucket/Default, uniqueId: Bucket } }, bucket_prefix: bucket-c88fdc5f-, force_destroy: false } }这段输出直接来自 tf-aws 平台对cloud.Bucket的实现packages/winglang/sdk/src/target-tf-aws/bucket.tspath与uniqueIdroot/Default/Default/Bucket/Default展示了资源在应用树中的层级路径uniqueId是资源在 Terraform 中的稳定标识。对应源码中createEncryptedBucket(this, ...)以Default为资源名创建S3Bucket。bucket_prefixbucket-c88fdc5f-由ResourceNames.generateName(scope, BUCKET_PREFIX_OPTS)生成。源码中的BUCKET_PREFIX_OPTSbucket.ts 第 37-44 行规定了严格的命名约束maxLen: 37Terraform 要求前缀 3-37 字符、仅小写字母数字与连字符、并以-结尾以区分 Wing 生成部分与 Terraform 追加的随机后缀。前缀中的c88fdc5f属于资源的确定性哈希由构造树路径推导因此同一份源码在不同机器上合成的快照是一致的——这正是快照机制可复现的前提。force_destroy对应cloud.BucketProps.forceDestroy默认false。注意一个细节createEncryptedBucketbucket.ts 第 159-186 行中实际写入的forceDestroy是!!isTestEnvironment || forceDestroy即测试环境下会被强制置为true便于测试结束后清理资源。本快照中显示false是因为快照重新编译时并未开启testing: true标志参见 snapshots.ts 中为了快照而再次编译的注释。3.3aws_s3_bucket_cors_configuration默认 CORS 规则aws_s3_bucket_cors_configuration: { Bucket_CorsConfiguration-1357ca3a_A4CCA40A: { //: { metadata: { path: root/Default/Default/Bucket/CorsConfiguration-1357ca3a } }, bucket: ${aws_s3_bucket.Bucket.id}, cors_rule: [ { allowed_headers: [*], allowed_methods: [GET,POST,PUT,DELETE,HEAD], allowed_origins: [*], expose_headers: [], max_age_seconds: 0 } ] } }为什么默认就有 CORS 配置tf-aws 的Bucket构造函数中if (props.cors ?? true)默认开启 CORS并使用cloud.DEFAULT_BUCKET_CORS_CONFIGURATION定义于 cloud/bucket.ts。该默认值正是快照中的五个方法GET/POST/PUT/DELETE/HEAD、allowedHeaders: [*]、allowedOrigins: [*]、exposeHeaders: []、maxAge: 0s。资源命名CorsConfiguration-1357ca3a来自addCorsRulebucket.ts 第 73-97 行中的CorsConfiguration-${this.node.addr.slice(-8)}即取节点地址的后 8 位十六进制A4CCA40A则是 CDKTF 生成的唯一 id 后缀path中的CorsConfiguration-1357ca3a与uniqueId中的前后缀共同构成稳定可寻址的标识。bucket引用${aws_s3_bucket.Bucket.id}是 Terraform 资源间引用表示 CORS 配置依赖同一个桶。cors_rule的惰性求值corsRule在源码中使用Lazy.anyValue包裹实际值在合成时由收集到的corsRules数组动态生成支持后续多次addCorsRule追加规则。3.4terraform段后端与 provider 版本terraform: { backend: { local: { path: ./terraform.tfstate } }, required_providers: { aws: { source: aws, version: 5.56.1 } } }backend.local快照样例使用本地状态文件./terraform.tfstate说明这是本地/CI 可执行的合成输出required_providers.aws锁定 AWS provider 版本为5.56.1当前仓库 winglang 依赖锁定的版本。这一约束意味着快照比对同时隐含了对 provider 版本的敏感性——升级 provider 可能引起合成输出的差异。四、--snapshots五种模式与自动判定逻辑快照行为由--snapshots mode或-s mode开关控制共五种模式帮助文本见 snapshots-help.ts完整说明见 02-cli-user-manual.md 的 Cloud test snapshots 一节模式行为典型场景never完全不捕获、不校验快照只想在 CI 中真正跑云测试时deploy部署并执行测试全部通过后更新快照本地开发环境默认当未设置 CIassert不部署仅合成并断言快照未变CI 环境默认当设置了 CIupdate不部署仅更新快照dry run确认过产物正确后批量刷新快照auto依据CI环境变量在deploy与assert间自动切换默认行为自动判定逻辑实现在determineSnapshotModesnapshots.ts两条硬性规则值得特别注意sim目标永不快照无论显式指定何种模式只要target BuiltinPlatform.SIM一律返回NEVER。快照机制只服务于云端目标tf-*、awscdk等。auto由 CI 决定未显式指定模式时若process.env.CI存在则进入ASSERT否则进入DEPLOY。对应的单元测试覆盖见 snapshots.test.ts其中专门验证了sim即使在显式DEPLOY/ASSERT/UPDATE下也会被强制禁用。五、CI 集成从 部署捕获 到 零部署断言5.1 本地环境未设 CI$ wing test -t tf-aws test_bucket.test.w ✔ Compiling test_bucket.test.w to tf-aws... ✔ terraform init ✔ terraform apply ... ✔ Snapshot test_bucket.test.w.tf-aws.snap.md...部署并执行测试全部通过后捕获快照对应DEPLOY模式。5.2 CI 环境设CI1$ CI1 wing test -t tf-aws test_bucket.test.w ✔ Snapshot test_bucket.test.w.tf-aws.snap.md...只做合成与比对不再触碰云端ASSERT模式。5.3 失配时的失败信息$ CI1 wing test -t tf-aws test_bucket.test.w ✖ Snapshot test_bucket.test.w.tf-aws.snap.md... Snapshot mismatch: - Expected: test_bucket.test.w.tf-aws.snap.md - Actual: test_bucket.test.w.tf-aws.snap.md.actual在captureSnapshotsnapshots.ts的ASSERT分支中失配时会把新产物写入snapshotFile.actual优先通过系统diff命令渲染统一 diffCI 下禁用颜色然后删除临时文件并抛出以Snapshot mismatch:为前缀的错误若快照文件根本不存在则直接报Snapshot file does not exist。错误提示同时给出两条恢复路径snapshots-help.tsUpdate with --snapshotsupdate To disable this behavior run with --snapshotsnever即确认变更是预期回归后用--snapshotsupdate刷新快照或在本轮确实需要真实云测试时用--snapshotsnever关闭。UPDATE模式本身跳过部署、直接写快照snapshots.ts因此官方文档特别提醒谨慎使用因为它可能把回归行为固化进快照。5.4 测试级别的行为差异在 test.test.ts 中可以观察到--retry与--parallel等选项与快照机制的配合失败的测试会自动重试且只有最终全部通过才进入快照环节测试结果汇总报告pass/fail由renderTestReport渲染。六、用源码测试验证快照的确定性snapshots.test.ts 是对本文快照机制最直接的验证它动态生成一个包含cloud.Bucket与test put用例的main.w分别以UPDATE、DEPLOY模式捕获快照并逐字节比对仓库中的 main.w.tf-aws.snap.mdexpect(snapshot).toStrictEqual(expected)。测试覆盖的关键结论NEVER模式下不会产生任何快照文件UPDATE与DEPLOY生成的快照内容完全一致证明快照不依赖部署过程ASSERT在快照缺失时报错在快照被篡改如把force_destroy改为true时报出 diff在完全一致时通过。这份 fixture 本身即仓库 CI 的一部分只要 tf-aws 平台的合成输出有任何非预期变化快照断言就会失败并暴露差异。七、实操建议与注意事项把快照文件视为契约入口.tf-aws.snap.md应提交进版本库并在每次依赖或 SDK 升级后主动 review diff避免带病更新。区分环境行为本地默认deploy、CI 默认assert的切换依赖CI环境变量如需强制某一种行为显式传--snapshotsmode。sim 目标没有快照本地模拟器测试请使用常规断言assert/expect承担功能验证快照只负责云端合成输出的回归防护。关注快照的可复现性快照之所以稳定是因为编译阶段固定了 root id、命名前缀使用确定性哈希、且排除了.wing、zip、map 等易变产物若自行扩展平台应保持相同的确定性约束。阅读入口机制实现集中在 snapshots.ts 与 snapshots-help.tsCLI 行为规范见 02-cli-user-manual.md设计初衷见 RFC 2024-03-24-snapshot-tests.mdtf-aws 平台资源生成见 packages/winglang/sdk/src/target-tf-aws/bucket.ts。通过本文你已经能够读懂任意入口.tf-aws.snap.md快照中每个字段的来源与含义理解wing test快照在本地与 CI 下的完整行为差异并在合成输出发生非预期变化时依据 diff 与--snapshots模式做出正确的处置决策。赞分享编程语言编译器云原生语言运行时【免费下载链接】wingA programming language for the cloud ☁️ A unified programming model, combining infrastructure and runtime code into one language ⚡项目地址https://gitcode.com/gh_mirrors/wi/wing点击查看免费下载相关推荐Wing SDK 源码模块架构深度解析从 src 目录看懂 Wing 云无关标准库的设计Wing SDK 源码模块架构深度解析从 src 目录看懂 Wing 云无关标准库的设计 本篇技术指南以 packages/winglang/sdk/src编程语言编译器云原生语言运行时eslint-plugin-unicorn 规则快照测试解析从 no-useless-recursion 快照报告读懂递归检测与回归验证eslint plugin unicorn 规则快照测试解析从 no useless recursion 快照报告读懂递归检测与回归验证 no uselessLint代码质量Wing 支持哪些云服务Wing SDK 云资源全景与兼容性矩阵解读Wing 支持哪些云服务Wing SDK 云资源全景与兼容性矩阵解读 本篇基于 Wing 官方 FAQ「Supported Services」文档展开梳理编程语言编译器云原生语言运行时上一篇Qwen-Image 2.1 ComfyUI 单文件模型部署指南Diffusion 模型、文本编码器与 VAE 的完整安装与工作流实践下一篇在 Jevgrep 中把 Claude Code 训练成可靠的 claude -p 子代理SKILL 规范与委托工作流实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考