Wing 语言 assert 断言与字符串插值编译产物深度解析:从 assert.test.w 快照看 preflight/inflight 生成机制
Wing 语言 assert 断言与字符串插值编译产物深度解析:从 assert.test.w 快照看 preflight/inflight 生成机制
本文以仓库中 assert.test.w 的 tf-aws 编译快照 为线索,结合其 源测试文件、simulator 运行快照 以及 SDK 与编译器的底层实现,系统讲解 Wing 语言中 assert 内置函数、字符串字面量与插值比较的编译与运行机制。读完本文,你将掌握 Wing 一个 .w 源文件如何被编译为 preflight.cjs、inflight.*.cjs 与 main.tf.json 三类产物,理解 assert 断言、闭包 lift、测试注册与 Terraform 模板生成的完整链路,并学会通过 hangar 快照反向阅读 Wing 的编译产物。
一、快照文件的性质:hangar 测试框架的"编译写真"
tools/hangar/__snapshots__/test_corpus/ 目录存放的是 Wing 仓库自研测试框架 hangar 生成的快照。从 paths.ts 可以看到,snapshotDir 指向 tools/hangar/__snapshots__;而 generated_test_targets.ts 中的 compileTest 会针对 tests/valid/ 下的每个 .w 文件执行 wing compile -t tf-aws,再把编译产物整理成 Markdown 快照。
快照文件的第一行 # <a href="https://link.gitcode.com/i/7528a55f5fc1c85f4fcbc359cfc48f00" target="_blank">assert.test.w</a> | compile | tf-aws 表明:本快照对应 assert.test.w 源文件在 tf-aws 目标下的 compile 用例。随后按文件名字典序排列三个产物:
inflight.$Closure1-1.cjs—— inflight 闭包代码;main.tf.json—— 生成的 Terraform (CDKTF) 模板;preflight.cjs—— preflight 阶段代码。
快照中的内容并非人工编写,而是由 createMarkdownSnapshot 自动生成:它对文件字典排序,按扩展名写入代码块,并用 toMatchFileSnapshot 与既有快照比对,从而在 CI 中守护编译产物的稳定性。
二、源文件解读:assert.test.w 到底断言了什么
先看被测试的 Wing 源程序 tests/valid/assert.test.w,其核心可拆成两部分。
2.1 preflight 顶层的字符串字面量断言
let s1 = "foo";
let s2 = "bar";
assert("" == "");
assert("'" == "'");
assert("\"" == "\"");
assert("`" == "`");
assert("``" == "``");
assert("`s1`" == "`s1`");
assert(s1 == s1);
assert("{s1}" == "{s1}");
assert("{s1}" != "{s2}");
assert("a{s1}" == "a{s1}");
assert("a{s1}" != "b{s1}");
assert("{s1}a" == "{s1}a");
assert("{s1}a" != "{s1}b");
assert("`'{s1}" == "`'{s1}");
assert("a{s1}b{s2}c" == "a{s1}b{s2}c");
这部分覆盖了三类核心语义:
- 特殊字符字面量:空串
""、单引号'、双引号"、反引号`、成对反引号``以及s1纯文本(注意这里`s1`是反引号包裹的普通字符串,不是插值,因此与变量s1的值"foo"无关); - 变量直接比较:
s1 == s1; - 字符串插值(interpolation):
"{s1}"、"a{s1}"、"{s1}a"、"`'{s1}"、"a{s1}b{s2}c"等,验证{expr}语法在字符串各位置(开头、中间、结尾、混合多插值)的求值,以及与!=组合时的比较语义。
2.2 inflight 测试块
test "assert works inflight" {
assert("" == "");
assert("'" == "'");
// ……与 preflight 完全相同的 15 条断言
}
test 关键字声明一个名为 "assert works inflight" 的单元测试,其内部 assert 在运行时(inflight 阶段)执行。这体现了 Wing 双阶段(preflight / inflight)模型:同一份断言逻辑既能在编译期构造资源时运行,也能作为云端函数在运行时运行。
三、preflight.cjs:断言如何被降级为 JavaScript
快照中的 preflight.cjs 是 Wing 编译器(wingc)对源文件 preflight 部分的降级产物,它是理解 assert 实现的关键。
3.1 环境引导与资源树建立
const $stdlib = require('@winglang/sdk');
const $platforms = ((s) => !s ? [] : s.split(';'))(process.env.WING_PLATFORMS);
const $outdir = process.env.WING_SYNTH_DIR ?? ".";
const $wing_is_test = process.env.WING_IS_TEST === "true";
const std = $stdlib.std;
const $helpers = $stdlib.helpers;
这些头部分别对应 Wing CLI 传入的环境变量:WING_PLATFORMS(平台列表,按 ; 分割)、WING_SYNTH_DIR(合成输出目录,默认当前目录)、WING_IS_TEST(是否为测试环境)。随后 $PlatformManager.createApp(...) 创建应用根节点,$APP.synth() 触发合成,最终产出 main.tf.json。
3.2 assert 的 JS 覆盖与调用形态
源文件中的 assert(x == y) 并没有直接翻译为运行时 assert,而是由编译器内联展开。对比源程序与产物可以发现一一对应关系:
| Wing 源码 | preflight.cjs 产物 |
|---|---|
assert("" == "") |
$helpers.assert($helpers.eq("", ""), "\"\" == \"\"") |
assert(s1 == s1) |
$helpers.assert($helpers.eq(s1, s1), "s1 == s1") |
assert("{s1}" != "{s2}") |
$helpers.assert($helpers.neq(String.raw({ raw: ["", ""] }, s1), String.raw({ raw: ["", ""] }, s2)), "\"{s1}\" != \"{s2}\"") |
assert("a{s1}b{s2}c" == "a{s1}b{s2}c") |
$helpers.assert($helpers.eq(String.raw({ raw: ["a", "b", "c"] }, s1, s2), String.raw({ raw: ["a", "b", "c"] }, s1, s2)), "\"a{s1}b{s2}c\" == \"a{s1}b{s2}c\"") |
这条降级规则定义在编译器源码中:在 wingc/src/type_check.rs 中,内置函数 assert 被注册为:
- 签名:
(condition: bool, message: str?): void,Phase::Independent(preflight 与 inflight 都可用); js_override为"$helpers.assert($args$, \"$args_text$\")",即编译时把条件表达式替换进$args$,把条件的源码文本(如"{s1}" != "{s2}")作为断言失败时的错误信息。
同理,== 与 != 运算符降级为 $helpers.eq / $helpers.neq;字符串插值 "{s1}" 则被转换为 String.raw({ raw: ["", ""] }, s1)——这是 JavaScript 模板字符串底层表示,raw 数组保存各段字面文本,后续参数依次是插值表达式。"a{s1}b{s2}c" 因此变成 String.raw({ raw: ["a", "b", "c"] }, s1, s2),其中 "a"、"b"、"c" 是插值之间的静态片段。
3.3 lift 机制:闭包与捕获变量的注册
preflight.cjs 中定义了 $Closure1 类(继承 $stdlib.std.AutoIdResource),它是源文件中 test 块的 inflight 处理函数在 preflight 侧的载体:
static _toInflightType() {
return `
require("${$helpers.normalPath(__dirname)}/inflight.$Closure1-1.cjs")({
$s1: ${$stdlib.core.liftObject(s1)},
$s2: ${$stdlib.core.liftObject(s2)},
})
`;
}
get _liftMap() {
return ({
"handle": [
[s1, []],
[s2, []],
],
"$inflight_init": [
[s1, []],
[s2, []],
],
});
}
_liftMap 声明闭包的 handle 与 $inflight_init 需要捕获(lift)变量 s1、s2(空数组表示无额外操作)。_toInflightType 则在运行时加载对应的 inflight 代码文件并注入捕获值。这正是 Wing "显式 lift" 能力在产物层的体现——被测试块引用的 s1、s2 必须在此登记,inflight 代码才能访问。
3.4 测试注册
globalThis.$ClassFactory.new("@winglang/sdk.std.Test", std.Test, this, "test:assert works inflight", new $Closure1(this, "$Closure1"));
test "assert works inflight" 最终创建了一个 @winglang/sdk.std.Test 资源。在 SDK 中,std/test.ts 的 Test 类描述为 "A cloud unit test":其构造函数会把 handler 交给测试运行器(App.of(this)?._testRunner?._addTestFunction(...))注册为云函数;若未通过 wing test 运行,则 Node.of(this).hidden = true,不生成实际资源。
四、inflight.$Closure1-1.cjs:运行时闭包的最终形态
inflight.$Closure1-1.cjs 是闭包运行时的 JavaScript 模块,模块工厂函数接收 lift 进来的 { $s1, $s2 }:
module.exports = function({ $s1, $s2 }) {
class $Closure1 {
constructor($args) { … }
async handle() {
$helpers.assert($helpers.eq("", ""), "\"\" == \"\"");
// …… 15 条断言与 preflight 侧完全一致
}
}
return $Closure1;
}
几点值得注意的实现事实:
handle是async方法——wingc 会把 inflight 代码块编译为异步函数,为将来可能出现的异步调用(例如访问云资源)预留能力;- 闭包头部注入的
{ $s1, $s2 }与 preflight 中_liftMap声明的捕获完全对应; - 断言的条件表达式(如
$helpers.eq("", ""))与错误消息("\"\" == \"\"")与 preflight 侧逐字一致,说明同一段 Wing 断言源码在 preflight 与 inflight 两个阶段被各自独立降级编译; - 文件末尾
//# sourceMappingURL=...表明产物带有 sourcemap,便于调试。
五、main.tf.json:为什么 assert 测试不会产生任何云资源
快照第三部分是 main.tf.json:
{
"//": {
"metadata": {
"backend": "local",
"stackName": "root"
},
"outputs": {}
},
"provider": {
"aws": [
{}
]
}
}
这是唯一包含 resource 字段之外的极简 CDKTF 模板:只有 AWS provider 声明与堆栈元数据,没有任何 aws_* 资源。原因在于:源程序全部由纯字符串断言构成,没有创建任何云资源(Bucket、Function、Queue 等);而 test 块在非模拟器目标下虽然会被注册为 std.Test,但按 std/test.ts 的注释,其实际函数"仅当用 wing test 编译非模拟器目标时才创建"。本快照走的是 wing compile 而非 wing test,因此 Terraform 模板中不出现测试函数资源。
此外快照生成时经过了 sanitize_json_paths 清洗:删除 terraform 字段与 metadata.version,对 asset.xxx、绝对 source 路径等做脱敏(替换为 <ASSET_KEY>、<SOURCE> 等占位符),以保证快照在不同机器/版本间稳定可比。
六、底层支撑:SDK helpers 中 eq / neq / assert 的实现
编译产物反复调用的 $helpers.assert、$helpers.eq、$helpers.neq 定义于 packages/@winglang/sdk/src/helpers.ts:
export function eq(a: any, b: any): boolean {
try {
return deepStrictEqual(a, b);
} catch {
return false;
}
}
export function neq(a: any, b: any): boolean {
try {
notDeepStrictEqual(a, b);
return true;
} catch {
return false;
}
}
export function assert(condition: any, message: string): asserts condition {
if (!condition) {
throw new Error("assertion failed: " + message);
}
}
要点:
eq采用 Node.js 的deepStrictEqual语义做深比较。文件注释说明(helpers.ts):因从 Node 18 迁移到 Node 20 后deepStrictEqual行为有差异,SDK 引入了本地实现./util/equality的deepStrictEqual(关联 winglang/wing#4444 的已知问题),以保证跨版本一致;assert(condition, message)在条件为假时抛出Error("assertion failed: " + message),其中的message正是 wingc 通过$args_text$注入的原始 Wing 源码文本,便于定位失败表达式;- 该文件头部注释强调:此代码会被自动打包进所有 inflight 代码,因此实现刻意保持轻量(如
nodeof用eval("require(...)")延迟加载),避免 inflight bundle 体积膨胀。
七、运行结果验证:simulator 下的测试快照
编译快照之外,同目录还保存了模拟器运行快照 assert.test.w_test_sim.md,其 stdout.log 展示了测试执行结果:
pass ─ assert.test.wsim » root/Default/test:assert works inflight
Tests 1 passed (1)
Snapshots 1 skipped
Test Files 1 passed (1)
Duration <DURATION>
这证实:15 条 preflight 断言在编译期全部通过(否则 wing compile 会以非零退出码失败,hangar 的 runWingCommand 会判定测试失败),而 "assert works inflight" 测试在模拟器(sim)平台上运行一次并 pass。Duration <DURATION> 是 hangar 在 sanitizeOutput 中对耗时文本的规范化替换,属于快照的确定性处理。
八、快照生成全流程:hangar 如何产出这份 Markdown
把整条链路串起来,这份快照的生成路径如下:
- paths.ts 扫描
tests/valid/,收集assert.test.w等.w文件(排除*.skip.w); - compileTest 调用
wing compile -t tf-aws(经 runWingCommand 执行,附加--no-update-check --no-analytics),产物落盘到target/assert.test.tfaws/; - 读取
main.tf.json并清洗;遍历target/.../.wing/目录,按preflight.、inflight.、extern/、proc、.Struct.js等前缀过滤收集代码文件,同时拒绝含绝对路径require(...)的文件(generated_test_targets.ts),保证快照可移植; - createMarkdownSnapshot 计算相对路径、按字典序排列文件,生成
## 文件名 + ```扩展名的 Markdown,写入tools/hangar/__snapshots__/test_corpus/valid/assert.test.w_compile_tf-aws.md并执行快照比对; - 若快照内容发生变化,CI 会提示更新快照——这正是 Wing 团队用快照锁住编译器输出的机制。
对模拟器测试,testTest 走 wing test -t sim 分支,捕获 stdout.log / stderr.log 生成 _test_sim.md 快照,与本篇分析的 _compile_tf-aws.md 相互印证。
九、小结:从一份快照读出 Wing 的编译世界观
通过逐层剖析 assert.test.w_compile_tf-aws.md,可以提炼出 Wing 编译器与运行时的几个关键设计:
- 双阶段编译:同一份断言源码在 preflight(
preflight.cjs内联展开)与 inflight(闭包handle内)被分别降级,两个阶段的产物结构镜像对应; - 宏式内联:
assert通过 wingc 的js_override机制编译为$helpers.assert(...),并把源码文本固化进错误消息,让运行时报错可直接对应到 Wing 代码行; - 显式 lift:闭包捕获的变量必须登记在
_liftMap并注入 inflight 模块,这是 Wing 保证 inflight 安全访问外部状态的实现基础; - 最小资源合成:纯逻辑测试在
tf-aws目标下只生成 provider 级空模板,云资源与测试函数按需创建; - 快照守护:hangar 用确定性清洗(脱敏路径、时长、端口、版本号)把编译产物固化为 Markdown 快照,使其成为可评审、可回溯的"编译契约"。
对于想要深入 Wing 编译链路的读者,建议按以下顺序继续研读:源文件 tests/valid/assert.test.w → 快照 assert.test.w_compile_tf-aws.md → 编译器注册逻辑 wingc/src/type_check.rs → SDK 运行时 sdk/src/helpers.ts → 测试框架 tools/hangar/src/generated_test_targets.ts,即可形成从源码到产物再到测试体系的完整闭环。