Wing 语言 assert 断言与字符串插值编译产物深度解析:从 assert.test.w 快照看 preflight/inflight 生成机制

原创2026-10-14 13:15:361,644 阅读
文章标签:编程语言编译器云原生语言运行时

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 用例。随后按文件名字典序排列三个产物:

  1. inflight.$Closure1-1.cjs —— inflight 闭包代码;
  2. main.tf.json —— 生成的 Terraform (CDKTF) 模板;
  3. 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

把整条链路串起来,这份快照的生成路径如下:

  1. paths.ts 扫描 tests/valid/,收集 assert.test.w 等 .w 文件(排除 *.skip.w);
  2. compileTest 调用 wing compile -t tf-aws(经 runWingCommand 执行,附加 --no-update-check --no-analytics),产物落盘到 target/assert.test.tfaws/;
  3. 读取 main.tf.json 并清洗;遍历 target/.../.wing/ 目录,按 preflight.、inflight.、extern/、proc、.Struct.js 等前缀过滤收集代码文件,同时拒绝含绝对路径 require(...) 的文件(generated_test_targets.ts),保证快照可移植;
  4. createMarkdownSnapshot 计算相对路径、按字典序排列文件,生成 ## 文件名 + ```扩展名 的 Markdown,写入 tools/hangar/__snapshots__/test_corpus/valid/assert.test.w_compile_tf-aws.md 并执行快照比对;
  5. 若快照内容发生变化,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,即可形成从源码到产物再到测试体系的完整闭环。

登录后查看全文
wing