Wing 语言 struct 特性编译产物深度解析:基于 hangar 快照的 tf-aws 编译验证

原创2026-10-15 10:37:272,327 阅读
文章标签:编程语言编译器云原生语言运行时

Wing 语言 struct 特性编译产物深度解析:基于 hangar 快照的 tf-aws 编译验证

导读

Wing 语言(项目根目录)中,struct 是用于承载结构化数据的核心类型机制,它把普通数据建模与云资源运行时代码统一在同一种语言里。本文以仓库中 hangar 测试框架为 tests/valid/structs.test.w 生成的编译快照(structs.test.w_compile_tf-aws.md)为解剖对象,逐文件还原 Wing 源码在 tf-aws 目标下被编译为 JavaScript 与 Terraform JSON 的完整过程。读完你将掌握 struct 的继承、嵌套、自引用、字段简写等语法在真实编译产物中的落地形态,以及 hangar 快照机制如何对编译输出做回归校验。

一、快照背后的测试源文件:structs.test.w

快照文件的第一行即指明了其来源与验证目标:

# <a href="https://link.gitcode.com/i/ffdd6cdab8c67fdb7d8b991b6c1855ef" target="_blank">structs.test.w</a> | compile | tf-aws

其中 compile 表示验证动作是编译,tf-aws 表示目标平台。而对应的源文件位于 tests/valid/structs.test.w,它几乎覆盖了 Wing struct 的全部核心语法,是理解快照产物的钥匙。

1.1 struct 定义、类型注解与接口引用

interface IFoo {
  // other types can reference structs before they are defined
  field0(): A;
}

// type annotations can reference structs before they are defined
let a: A? = nil;

struct A {
  field0: str;
}

struct B extends A {
  field1: num;
  field2: str;
  field3: A;
}

这里演示了三个关键规则:

  • 前向引用:接口方法返回值(field0(): A)和变量类型注解(let a: A? = nil)都可以在 struct A 定义之前出现,编译器允许 struct 类型前向引用;
  • 单继承:struct B extends A 继承 A 的字段,并追加自己的字段;
  • 类型组合:struct 字段可以引用其他 struct(field3: A),从而形成嵌套结构。

1.2 struct 字面量初始化与断言

let x = A {
  field0: "Sup"
};

let y = B {
  field0: "hello",
  field1: 1,
  field2: "world",
  field3: A {
    field0: "foo"
  }
};

assert(x.field0 == "Sup");
assert(y.field1 == 1);
assert(y.field3.field0 == "foo");
  • struct 通过 类型名 { 字段: 值 } 的"类 JSON 字面量"方式构造;
  • 继承后的 struct 必须补全继承字段(y 同时提供 A 的 field0 与自身的 field1/field2/field3);
  • 字段访问支持任意深度的链式取值,并直接配合 assert 做编译期验证。

1.3 多继承、相互引用与自引用

struct Razzle { a: str; }
struct Dazzle { a: str; }
struct Showtime extends Razzle, Dazzle {}

struct M1 { m2: M2?; }
struct M2 { m1: M1?; }

struct Node {
	val: str;
	next: Node?;
}

let aNode = Node {val: "someval"};
let bNode = Node {val: "otherval", next: aNode};
  • Showtime extends Razzle, Dazzle 是多继承,两个父 struct 拥有同名同类型字段 a: str,编译器允许合并;
  • M1/M2 构成相互引用,通过可选类型 ? 打破循环;
  • Node 是自引用结构,next: Node? 允许链接式数据(链表)建模。

随后源文件用 expect.equal(Json.stringify(bNode), ...) 验证自引用 struct 能正确序列化为嵌套 JSON。

1.4 文档注释、字段简写(punning)与多类型字段

/// Struct documentation
struct DocumentedStruct {
    /// Field documentation
    field: str;
}

struct SomeStruct1 { numField: num; }
struct SomeStruct2 {
  structField: SomeStruct1;
  strField: str;
}
struct SomeStruct3 extends SomeStruct2 {
  boolField: bool;
  otherField: str;
}
let numField = 1337;
let strField = "leet";
let boolField = true;
let structField = SomeStruct1 { numField };

let someStruct3 = SomeStruct3 {
  boolField,
  strField,
  otherField: "good",
  structField
};
  • /// 三斜杠注释用于为 struct 及字段编写文档,编译器可正确解析而不会报错;
  • 字段简写(punning):当局部变量名与字段名一致时,可直接写 boolField、strField、structField 而省略 字段名: 变量名,与 JavaScript/TypeScript 的对象简写习惯一致;
  • 此外源文件还定义了一个 lotsOfTypes struct,验证 str/num/Array<str>/Map<str>/Json/bool/str?/Array<Map<num>> 等丰富字段类型均可出现在 struct 中。

1.5 struct 与 preflight/inflight 的组合

class Foo {
  data: B;
  new(b: B) {
    this.data = b;
  }
  inflight getStuff(): str {
    return this.data.field0;
  }
}

struct 可以作为类的字段类型,且该字段可以在 inflight 方法中被读取——这正是 Wing"统一基础设施与运行时代码"模型的关键场景,也是快照中 inflight.Foo-1.cjs 存在的直接原因。

二、快照产物全景:一次 tf-aws 编译生成四个文件

structs.test.w_compile_tf-aws.md 按文件名排序收录了编译输出的全部关键产物:

快照中的文件 说明
inflight.$Closure1-1.cjs 测试用例 test "struct definitions are phase independant" 对应的 inflight 闭包实现
inflight.Foo-1.cjs 类 Foo 的 inflight 形态,承载 getStuff() 方法
main.tf.json Terraform 平台(tf-aws)合成的基础设施定义
preflight.cjs preflight(预检/同步阶段)代码:类型注册、断言、资源构造与 synth 入口

这种"每个 inflight 实体一个 .cjs 文件 + 一个统一 preflight 文件 + 一份 main.tf.json"的布局,是 Wing tf-aws 编译目标的固定产物结构(快照由 tools/hangar/src/utils.ts 中的 createMarkdownSnapshot 按文件排序生成)。

三、preflight.cjs:struct 在同步阶段如何被"降级"为 JavaScript

快照中最具信息量的是 preflight.cjs,它展示了 Wing 源码在 preflight 阶段的 JS 形态。

3.1 结构初始化代码

const a = undefined;
const x = ({"field0": "Sup"});
const y = ({"field0": "hello", "field1": 1, "field2": "world", "field3": ({"field0": "foo"})});

可以看到,struct A {...}、struct B extends A {...} 这类纯数据类型的字面量构造,会被直接编译为普通 JavaScript 对象字面量({...}),嵌套 struct 也是嵌套对象。这印证了官方文档"struct 松散地模仿 JavaScript 中带类型的 JSON 字面量"的定位(参见 docs/by-example/12-structs.md)。

3.2 断言如何落地

$helpers.assert($helpers.eq(x.field0, "Sup"), "x.field0 == \"Sup\"");
$helpers.assert($helpers.eq(y.field1, 1), "y.field1 == 1");
$helpers.assert($helpers.eq(y.field3.field0, "foo"), "y.field3.field0 == \"foo\"");

源码中的 assert(x.field0 == "Sup") 被编译为对 SDK 辅助函数的调用。其底层实现位于 packages/@winglang/sdk/src/helpers.ts:

export function eq(a: any, b: any): boolean {
  try {
    return deepStrictEqual(a, b);
  } catch {
    return false;
  }
}

export function assert(condition: any, message: string): asserts condition {
  if (!condition) {
    throw new Error("assertion failed: " + message);
  }
}

即 eq 基于 Node.js 的 deepStrictEqual(深严格相等,可正确比较嵌套对象/数组),失败时 assert 抛出带源断言语义的错误信息。文件头注释还说明该辅助代码会被自动打入所有 inflight bundle 中,因此要求保持轻量、不引入重依赖。

3.3 自引用 struct 的序列化验证

const aNode = ({"val": "someval"});
const bNode = ({"val": "otherval", "next": aNode});
(expect.Util.equal($macros.__Json_stringify(false, std.Json, bNode), "{\"val\":\"otherval\",\"next\":{\"val\":\"someval\"}}"));

bNode.next 直接引用 aNode 对象,Json.stringify 宏将其序列化为嵌套 JSON 字符串。由于 next 在 Wing 源码中是可选类型 Node?,运行时空闲字段会以实际对象身份参与序列化,这正是自引用 struct 作为链表/树节点的基础。

3.4 字段简写的编译结果

const numField = 1337;
const strField = "leet";
const boolField = true;
const structField = ({"numField": numField});
const someStruct3 = ({"boolField": boolField, "strField": strField, "otherField": "good", "structField": structField});
$helpers.assert($helpers.eq(someStruct3.boolField, true), "someStruct3.boolField == true");
$helpers.assert($helpers.eq(someStruct3.structField.numField, 1337), "someStruct3.structField.numField == 1337");

简写语法在产物中被展开为显式键值对,语义完全等价于完整写法。值得注意的是 structField 会被 $helpers 与 assert 深比较,验证嵌套字段取值正确。

3.5 struct 类(Foo)的编译形态

class Foo extends $stdlib.std.Resource {
  constructor($scope, $id, b) {
    super($scope, $id);
    this.data = b;
  }
  static _toInflightType() {
    return `
      require("${$helpers.normalPath(__dirname)}/inflight.Foo-1.cjs")({
      })
    `;
  }
  _liftedState() {
    return {
      ...(super._liftedState?.() ?? {}),
      $this_data_field0: $stdlib.core.liftObject(this.data.field0),
    };
  }
  get _liftMap() {
    return ({
      "getStuff": [
        [this.data.field0, []],
      ],
      "$inflight_init": [
        [this.data.field0, []],
      ],
    });
  }
}

这是 Wing lift 机制的直接体现:

  • 持有 struct 的类 Foo 被编译为继承 $stdlib.std.Resource 的 preflight 资源类;
  • _liftMap 明确声明:inflight 方法 getStuff 与初始化 $inflight_init 都需要访问 this.data.field0——即从"整块 struct 数据"中按需提升(lift)具体字段,而不是整块搬运;
  • _liftedState() 通过 $stdlib.core.liftObject(this.data.field0) 将该字段序列化到 inflight 环境;
  • _toInflightType() 负责在运行时按需 require 对应的 inflight 模块文件 inflight.Foo-1.cjs。

3.6 测试闭包与自动 ID

class $Closure1 extends $stdlib.std.AutoIdResource {
  _id = $stdlib.core.closureId();
  constructor($scope, $id, ) {
    super($scope, $id);
    $helpers.nodeof(this).hidden = true;
  }
  ...
}
...
globalThis.$ClassFactory.new("@winglang/sdk.std.Test", std.Test, this, "test:struct definitions are phase independant", new $Closure1(this, "$Closure1"));

源码中的 test "struct definitions are phase independant" { ... } 被编译为一个:

  • 自动分配 ID 的闭包类($stdlib.core.closureId(),且节点被标记为 hidden);
  • 通过 globalThis.$ClassFactory.new(...) 注册为 @winglang/sdk.std.Test 测试资源。

这正是快照中 inflight.$Closure1-1.cjs 的注册来源,也解释了为什么测试名字会出现在 sim 运行日志中(见后文第五节)。

3.7 平台管理与 synth 入口

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 $PlatformManager = new $stdlib.platform.PlatformManager({platformPaths: $platforms});
class $Root extends $stdlib.std.Resource { ... }
const $APP = $PlatformManager.createApp({
  outdir: $outdir, name: "structs.test", rootConstruct: $Root,
  isTestEnvironment: $wing_is_test, entrypointDir: process.env['WING_SOURCE_DIR'], rootId: process.env['WING_ROOT_ID']
});
$APP.synth();

生成后的 preflight.cjs 是一个可独立执行的 Node.js 程序:它通过环境变量(WING_PLATFORMS、WING_SYNTH_DIR、WING_IS_TEST、WING_SOURCE_DIR、WING_ROOT_ID)接收编译上下文,实例化 PlatformManager 与根构造 $Root,最终调用 synth() 产出目标平台产物。这也与 hangar 通过 runWingCommand 以子进程方式执行 wing compile -t tf-aws 的测试方式相衔接。

四、inflight 产物与 Terraform 定义

4.1 inflight.Foo-1.cjs:struct 字段如何被"送入"运行环境

module.exports = function({  }) {
  class Foo {
    constructor($args) {
      const { $this_data_field0 } = $args;
      this.$this_data_field0 = $this_data_field0;
    }
    async getStuff() {
      return this.$this_data_field0;
    }
  }
  return Foo;
}

inflight 版本的 Foo 不再携带整块 data: B,而是只接收被 lift 出来的字段 $this_data_field0(对应 this.data.field0),getStuff() 直接返回该字段。这验证了 Wing 的按字段精确提升策略:struct 的其余字段不会进入运行环境,从而最小化部署负载与权限面。

4.2 inflight.$Closure1-1.cjs:测试闭包的运行体

async handle() {
  const s2 = ({"a": "foo"});
  $helpers.assert($helpers.eq(s2.a, "foo"), "s2.a == \"foo\"");
}

测试主体被编译为 handle() 异步方法,同样以 helpers.assert/eq 完成断言。这里再次印证 struct 字面量的 inflight 构造与 preflight 阶段一致(对象字面量),呼应测试名"struct definitions are phase independant"——struct 定义与构造在 preflight 与 inflight 两个阶段行为相同。

4.3 main.tf.json:纯数据 struct 不产生云资源

{
  "//": {
    "metadata": {
      "backend": "local",
      "stackName": "root"
    },
    "outputs": {}
  },
  "provider": {
    "aws": [
      {}
    ]
  }
}

整个 tf-aws 产物仅包含 provider.aws 与空的 metadata/outputs——struct 作为纯数据类型不映射任何云资源,因此 Terraform 定义中没有 resource 条目。这说明 struct 在 Wing 中的职责是数据载体:它只在需要时通过"持有它的资源"(如本例中的 Foo、测试闭包)参与部署,而自身不产生基础设施开销。

五、快照如何生成与验证:hangar 测试机制

该快照不是手工编写的文档,而是 hangar 测试套件的自动回归产物,相关逻辑位于 tools/hangar/src/generated_test_targets.ts:

export async function compileTest(sourceDir, wingFile, env?, includeJavaScriptInSnapshots = true, skipMarkdownSnapshot = false, commandArgs = []) {
  const platforms = ["tf-aws"];
  const args = ["compile", ...commandArgs];
  const targetDir = join(sourceDir, "target", `${wingBasename.replace(".w", "")}.tfaws`);
  ...
  await runWingCommand({ cwd: sourceDir, platforms, wingFile, args, expectFailure: false, env });
  ...
}

核心流程:

  1. 对测试文件执行 wing compile -t tf-aws(runWingCommand 内部走 tools/hangar/src/utils.ts 的 execa 子进程调用,并附 --no-update-check、--no-analytics 参数);
  2. 读取 target/<name>.tfaws/main.tf.json 与 .wing 目录下所有产物(preflight.*、inflight.*、extern/、proc、.Struct.js 等前缀文件,排除 .map sourcemap),并检查产物中不存在绝对路径 require(见 generated_test_targets.ts 第 68-71 行);
  3. 通过 sanitize_json_paths 对 Terraform JSON 做脱敏(剔除 terraform 字段、metadata 版本、绝对路径与 hash 引用);
  4. 由 createMarkdownSnapshot 按 ## 文件名 + 代码块 的格式写入 __snapshots__/test_corpus/...,并用 toMatchFileSnapshot 与既有快照对比。

快照目录常量定义在 tools/hangar/src/paths.ts(snapshotDir = path.join(hangarDir, "__snapshots__")),生成的快照命名规则为 ${wingFile}_${testCase}_${target}.md,其中 testCase 取值 compile 或 test。因此:

  • 本文剖析的文件 structs.test.w_compile_tf-aws.md = 编译动作 + tf-aws 平台;
  • 配套文件 structs.test.w_test_sim.md = 测试动作 + sim 平台。

5.1 sim 测试快照:验证 struct 用例真实运行通过

与编译快照配套的 structs.test.w_test_sim.md 记录了 wing test -t sim 的运行输出:

pass ─ structs.test.wsim » root/Default/test:struct definitions are phase independant

Tests 1 passed (1)
Snapshots 1 skipped
Test Files 1 passed (1)
Duration <DURATION>
  • 测试名称 struct definitions are phase independant 与 preflight 产物中的注册字符串完全对应;
  • Duration <DURATION> 是 hangar 输出脱敏的结果——sanitizeOutput 会把可变时间、端口、绝对路径等替换为占位符(见 utils.ts 第 55-84 行),保证快照在不同环境下可稳定复现;
  • 该用例在模拟器(sim)平台下通过,从运行层面证实了 struct 的前向引用、多继承、自引用、字段简写等特性在真实执行时行为正确。

六、从快照看 Wing struct 的工程结论

将源文件、编译产物与 SDK 辅助实现对照,可以得出几条可直接复用的结论:

  1. struct 是纯数据层抽象:定义、继承、嵌套、自引用全部在编译期完成类型检查,运行时表现为普通 JS 对象,因此可以自由进出 Json 序列化(Json.stringify)与深比较(helpers.eq 的 deepStrictEqual)。
  2. struct 不产生云资源:只要 struct 没有被资源类引用,tf-aws 产物中就不会出现任何 Terraform resource 条目,main.tf.json 仅保留 provider 骨架。
  3. struct 字段是 lift 的最小粒度:当 struct 作为类字段且被 inflight 方法读取时,编译器通过 _liftMap 只提升被访问的具体字段(如 this.data.field0),而不是整块数据;inflight 代码通过构造参数 $args 接收这些字段(见 inflight.Foo-1.cjs)。
  4. 前向引用、多继承与字段简写是稳定语法:structs.test.w 中这些特性不仅被编译器接受,还在 sim 平台通过运行时断言,并经受 hangar 快照的持续回归保护。

七、如何在仓库中复现与延伸阅读

若要在本地重现这份快照,可按仓库文档(contributing/01-start-here/05-development.md)完成工具链构建后,进入 tools/hangar 运行对应测试目标(源码见 tools/hangar/README.md 与 tools/hangar/src/generate_tests.ts),测试主体会依次执行 wing compile -t tf-aws 与 wing test -t sim 并比对快照。

进一步学习资料:

通过这一组快照,你可以清晰地看到:一份 Wing struct 源码,从类型系统到 JavaScript 运行时、再到 Terraform 基础设施定义,每一步都有可验证的中间产物——这正是 Wing"单一语言统一基础设施与业务代码"设计目标在编译层的具体体现。

登录后查看全文
wing