Wing 语言 struct 特性编译产物深度解析:基于 hangar 快照的 tf-aws 编译验证
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 的对象简写习惯一致; - 此外源文件还定义了一个
lotsOfTypesstruct,验证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 });
...
}
核心流程:
- 对测试文件执行
wing compile -t tf-aws(runWingCommand内部走 tools/hangar/src/utils.ts 的 execa 子进程调用,并附--no-update-check、--no-analytics参数); - 读取
target/<name>.tfaws/main.tf.json与.wing目录下所有产物(preflight.*、inflight.*、extern/、proc、.Struct.js等前缀文件,排除.mapsourcemap),并检查产物中不存在绝对路径require(见generated_test_targets.ts第 68-71 行); - 通过
sanitize_json_paths对 Terraform JSON 做脱敏(剔除terraform字段、metadata 版本、绝对路径与 hash 引用); - 由
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 辅助实现对照,可以得出几条可直接复用的结论:
- struct 是纯数据层抽象:定义、继承、嵌套、自引用全部在编译期完成类型检查,运行时表现为普通 JS 对象,因此可以自由进出
Json序列化(Json.stringify)与深比较(helpers.eq的deepStrictEqual)。 - struct 不产生云资源:只要 struct 没有被资源类引用,tf-aws 产物中就不会出现任何 Terraform
resource条目,main.tf.json仅保留 provider 骨架。 - struct 字段是 lift 的最小粒度:当 struct 作为类字段且被 inflight 方法读取时,编译器通过
_liftMap只提升被访问的具体字段(如this.data.field0),而不是整块数据;inflight 代码通过构造参数$args接收这些字段(见inflight.Foo-1.cjs)。 - 前向引用、多继承与字段简写是稳定语法:
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 并比对快照。
进一步学习资料:
- struct 基础语法与函数调用中的展开用法:docs/by-example/12-structs.md;
- struct 展开参数(trailing struct parameters)补充示例:docs/by-example/13-trailing-struct-parameters.md;
- 更多 struct 相关测试用例可浏览 tests/valid/ 目录下
struct_from_json.test.w、struct_json_conversion.test.w等(位于 tests/invalid/ 的structs.test.w、struct_expansion.test.w则覆盖错误场景); - inflight 闭包与 lift 的完整语义可参考 docs/docs/02-concepts/01-preflight-and-inflight.md;
- SDK 侧
expect库与std.Json的实现位于 packages/@winglang/sdk/src。
通过这一组快照,你可以清晰地看到:一份 Wing struct 源码,从类型系统到 JavaScript 运行时、再到 Terraform 基础设施定义,每一步都有可验证的中间产物——这正是 Wing"单一语言统一基础设施与业务代码"设计目标在编译层的具体体现。