Wing 语言自定义对象 ID:`as` 语法、`nodeof` 内建函数与 tf-aws 编译快照解析
Wing 语言自定义对象 ID:as 语法、nodeof 内建函数与 tf-aws 编译快照解析
本文以 Wing 官方测试语料中的 custom_obj_id.test.w 及其 tf-aws 编译快照为核心,讲解如何在 Wing 中通过 as 语法为 preflight 类实例指定自定义对象 ID,如何用 nodeof 内建函数在 preflight 阶段断言实例身份,并逐段解读该测试在 wing compile -t tf-aws 下生成的 preflight.cjs、inflight.Foo-1.cjs 与 main.tf.json 三个产物,帮助读者理解实例命名从语言语法到 SDK 构造树的完整落地链路。
一、被验证的 Wing 源码:自定义对象 ID 的最小用例
快照文件 custom_obj_id.test.w_compile_tf-aws.md 对应的是测试语料库中的 custom_obj_id.test.w,完整源码如下:
class Foo { }
let foo1 = new Foo();
let bar2 = new Foo() as "bar2";
assert(nodeof(foo1).id == "Foo");
assert(nodeof(bar2).id == "bar2");
这段代码覆盖了三个核心机制:
- 默认命名:
new Foo()未显式指定名称,实例 ID 默认为类名Foo; as语法:new Foo() as "bar2"将实例 ID 覆写为字符串字面量"bar2";nodeof内建函数:在 preflight 阶段读取构造树节点信息,此处断言两个实例的id字段与预期一致。
按照官方文档 Application tree 的说明,preflight 类实例由唯一名称标识,该名称同时决定了 Wing Console 中的资源展示名、基础设施工程引擎(如 Terraform)中的逻辑名,以及云厂商侧的物理资源名;默认名称为类名,可用 as 语法覆写,且名称在其所处作用域内必须唯一。
二、as 语法的语义:作用域与唯一性约束
文档明确了两条命名规则,本用例恰好验证了第一条(默认值与覆写):
- 默认名称:
let bucket1 = new cloud.Bucket();的默认名称是cloud.Bucket(类名); - 显式覆写:
new cloud.Bucket() as "my-bucket"将其命名为my-bucket; - 作用域隔离:名称只需在同一作用域内唯一,不同类构造出的子作用域可以复用同名资源,例如两个不同类的
new() { new cloud.Bucket() as "Store"; }是合法的。
从编译产物(见下文)可以进一步印证:as 并非运行时重命名,而是直接体现在构造器调用的第二个参数上,即构造树(construct tree)中的构造 ID。
三、nodeof 内建函数的 SDK 实现
nodeof 在 SDK 中的实现位于 helpers.ts:
export function nodeof(construct: Construct): Node {
// Should only be used preflight, avoid bundling
const Node = eval("require('./std/node').Node");
return Node.of(construct);
}
两点值得注意:
- 源码注释标明
nodeof只应在 preflight 阶段使用("Should only be used preflight, avoid bundling"),避免被 bundle 进 inflight 代码——这与 Wing 的 preflight/inflight 两阶段模型一致; - 实现上它是对构造体调用
Node.of(construct),返回的Node对象携带id、path等构造树元信息。文档示例log(nodeof(b).path);会输出类似/root/Bucket的路径,本用例则使用.id字段做相等性断言。
编译后的 preflight.cjs 中,Wing 的 assert(nodeof(foo1).id == "Foo") 被翻译为:
$helpers.assert($helpers.eq($helpers.nodeof(foo1).id, "Foo"), "nodeof(foo1).id == \"Foo\"");
即 assert 展开为 $helpers.assert + $helpers.eq,并附带人类可读的断言消息,便于编译期失败时定位。
四、编译快照逐段解析
快照文件由 hangar 测试框架对 tests/valid/custom_obj_id.test.w 执行 wing compile -t tf-aws 后生成,包含三个产物。以下按原快照结构逐一给出全文并解析。
4.1 inflight.Foo-1.cjs
原快照中的完整内容:
"use strict";
const $helpers = require("@winglang/sdk/lib/helpers");
const $macros = require("@winglang/sdk/lib/macros");
module.exports = function({ }) {
class Foo {
}
return Foo;
}
//# sourceMappingURL=inflight.Foo-1.cjs.map
这是编译器为 Foo 生成的 inflight 类型桩文件。由于 Foo 是 preflight 类,编译产物中会生成一个工厂函数形式加载的 inflight 变体(对应 preflight.cjs 里的 static _toInflightType() 返回值),供未来 inflight 场景引用该类型。本用例的 Foo 是空类,因此生成的 inflight 类也是空壳,仅保留 require("@winglang/sdk/lib/helpers") 等标准脚手架,并在文件尾携带 sourcemap 引用以便错误栈回溯。
4.2 main.tf.json
原快照中的完整内容:
{
"//": {
"metadata": {
"backend": "local",
"stackName": "root"
},
"outputs": {}
},
"provider": {
"aws": [
{}
]
}
}
该文件是 tf-aws 目标平台的 Terraform JSON 模板。由于 Foo 不是云资源类(不映射到任何 Terraform 资源),模板中只有元数据与 AWS provider 声明:
backend: "local"、stackName: "root":快照生成时使用的本地后端与根栈名(测试环境产物,非部署配置);- 快照生成流程会调用 sanitize_json_paths 清洗 JSON,移除
terraform块、cdktf 版本号与绝对路径/资源哈希等易变字段,保证快照跨机器可稳定比对。
这正体现了快照的价值:自定义 ID 不产生额外资源时,main.tf.json 保持最小形态;若 Foo 换成 cloud.Bucket,此处将出现以实例 ID 命名的 aws_s3_bucket 资源。
4.3 preflight.cjs
原快照中的完整内容:
"use strict";
const $stdlib = require('@winglang/sdk');
const $macros = require("@winglang/sdk/lib/macros");
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;
const $extern = $helpers.createExternRequire(__dirname);
const $types = require("./types.cjs");
const $PlatformManager = new $stdlib.platform.PlatformManager({platformPaths: $platforms});
class $Root extends $stdlib.std.Resource {
constructor($scope, $id) {
super($scope, $id);
$helpers.nodeof(this).root.$preflightTypesMap = { };
let $preflightTypesMap = {};
$helpers.nodeof(this).root.$preflightTypesMap = $preflightTypesMap;
class Foo extends $stdlib.std.Resource {
constructor($scope, $id, ) {
super($scope, $id);
}
static _toInflightType() {
return `
require("${$helpers.normalPath(__dirname)}/inflight.Foo-1.cjs")({
})
`;
}
get _liftMap() {
return ({
"$inflight_init": [
],
});
}
}
const foo1 = new Foo(this, "Foo");
const bar2 = new Foo(this, "bar2");
$helpers.assert($helpers.eq($helpers.nodeof(foo1).id, "Foo"), "nodeof(foo1).id == \"Foo\"");
$helpers.assert($helpers.eq($helpers.nodeof(bar2).id, "bar2"), "nodeof(bar2).id == \"bar2\"");
}
}
const $APP = $PlatformManager.createApp({ outdir: $outdir, name: "custom_obj_id.test", rootConstruct: $Root, isTestEnvironment: $wing_is_test, entrypointDir: process.env['WING_SOURCE_DIR'], rootId: process.env['WING_ROOT_ID'] });
$APP.synth();
//# sourceMappingURL=preflight.cjs.map
关键编译决策如下:
- Wing 类 → SDK 构造类:
class Foo { }被提升为class Foo extends $stdlib.std.Resource,挂在$Root构造器内部(对应 Wing 中"顶层实例挂到 root 节点"的默认作用域规则); as语法 → 构造器第二参数:new Foo()编译为new Foo(this, "Foo"),new Foo() as "bar2"编译为new Foo(this, "bar2")。构造 ID 在合成(synth)阶段即确定,是 preflight 期不可变的;- 两条 assert 保留在 preflight 中:
nodeof(...).id的相等断言在$Root构造期间执行,意味着 ID 断言属于编译/合成期检查,一旦 ID 冲突或命名错误,wing compile阶段即失败,而非等到部署; _toInflightType()静态方法:返回加载inflight.Foo-1.cjs的表达式,把 4.1 节的桩文件与 preflight 类关联起来;- 应用装配:末尾
$PlatformManager.createApp({...})接收WING_SYNTH_DIR、WING_ROOT_ID等环境变量(rootId默认root,与 4.2 节main.tf.json中stackName: "root"对应),$APP.synth()触发整个应用树向 Terraform JSON 的合成。
五、快照是如何生成的:hangar 测试框架
该快照并非手工维护,而是由 hangar 工具自动生成与校验:
- generated_test_targets.ts 中的
compileTest会以<a href="https://link.gitcode.com/i/16f4974693ed06c2f73c02f870e58d6f" target="_blank">"compile"]参数、平台tf-aws调用wingCLI(调用细节见 [runWingCommand,其以--no-update-check --no-analytics附加-t tf-aws执行); - 编译成功后,收集
target/<name>.tfaws/下的main.tf.json与.wing/目录中匹配preflight.、inflight.等前缀的文件(排除.mapsourcemap),经sanitize_json_paths清洗后; - 由 createMarkdownSnapshot 拼装为 Markdown 并以
toMatchFileSnapshot写入tools/hangar/__snapshots__/test_corpus/目录,文件命名规则为<wing文件名>_<用例类型>_<目标平台>.md,因此本文主文档的命名为custom_obj_id.test.w_compile_tf-aws.md。
同一语料还有运行类快照 custom_obj_id.test.w_test_sim.md,记录了在 simulator 目标下运行该测试的 stdout(pass ─ custom_obj_id.test.wsim (no tests)),说明该用例不含 test 块、仅需通过编译期断言即可验证。
六、小结与适用前提
as语法的生效时机:自定义对象 ID 是 preflight 概念,直接固化到构造器的 ID 参数与合成产物(Terraform 逻辑名)中,inflight 阶段不可更改;- 验证手段:
nodeof(x).id/nodeof(x).path是 preflight 期查询构造树身份的标准方式(实现见 helpers.ts),配合assert可实现命名约定自检; - 快照的适用前提:本文所引快照针对
tf-aws平台与本地 backend 的测试环境产物,绝对路径、资源哈希、版本号等易变字段已被清洗;若要复现,需在该仓库内构建 CLI 并运行 hangar 测试流程,具体目录约定见 paths.ts。