Wing 标准库 std.Node 详解:构造树节点、依赖关系与连接管理

原创2026-10-12 19:13:161,661 阅读
文章标签:编程语言编译器云原生语言运行时

Wing 标准库 std.Node 详解:构造树节点、依赖关系与连接管理

std.Node 是 Wing 语言标准库中每个构造(construct)的"内部节点",它把应用里所有云资源组织成一棵可遍历、可校验、可序列化的构造树(construct tree)。本文基于 docs/api/04-standard-library/std/node.md 完整梳理 Node 类的全部方法、属性、AddConnectionProps 结构与 IApp 协议,并结合 node.ts 等源码实现说明每个 API 的底层行为与真实使用场景。读完本文,你将掌握在 Wing 应用中如何访问节点标识(id/path/addr)、如何管理依赖与连接、如何读写上下文与元数据,以及这些机制如何支撑 Wing Console 的树状可视化与部署产物生成。

std.Node 是什么:构造树的内部节点

在 Wing 的编程模型中,一个应用本质上是一棵构造树:根节点是 cloud.App,每个云资源(Bucket、Queue、Function、Topic 等)都是树中的一个构造节点。std.Node 就是挂载在每个构造上、负责描述这棵树结构的那层"内部节点",对应源码 std/node.ts 中的 Node 类。

源码中通过 Node.of(construct) 静态方法获取任意构造的内部节点:

// packages/@winglang/sdk/src/std/node.ts
public static of(construct: IConstruct): Node {
  let node = (construct as any)[NODE_SYMBOL];
  if (!node) {
    node = new Node(construct);
    (construct as any)[NODE_SYMBOL] = node;
  }
  return node;
}

该实现使用 Symbol.for("@winglang/sdk.std.Node") 作为全局注册表键,同一个构造多次调用 Node.of() 返回的是同一个实例。构造成功后,Node 内部同时持有两个对象:

  • _constructsNode:底层 constructs 库(constructs 10.x)提供的节点,负责 scope、path、addr、上下文、依赖等标准能力;
  • _connections:Connections 实例(见 core/connections.ts),用于记录构造之间"调用关系"的连接元数据。

Wing SDK 中大量云资源在构造时就会调用 Node.of(this) 设置显示信息,例如 cloud/api.ts 设置 title = "Api"、description = "A REST API endpoint",因此 std.Node 也是 Wing Console 树视图、tree.json 可视化数据的重要数据源(相关概念可参考 docs/02-concepts/02-application-tree.md)。

Node 类 API 总览

Node 类提供 12 个方法与 19 个属性,完整清单如下:

方法

名称 签名 说明
addConnection addConnection(props: AddConnectionProps): void 在两个构造之间添加一条连接(关系元数据)
addDependency addDependency(...deps: Array<IDependable>): void 为另一个构造添加排序依赖
addMetadata addMetadata(type: str, data: any, options?: MetadataOptions): void 为构造添加元数据条目
addValidation addValidation(validation: IValidation): void 为构造添加校验器
findAll findAll(order?: ConstructOrder): MutArray<IConstruct> 返回本构造及其全部子构造(可指定遍历顺序)
findChild findChild(): IConstruct 按 id 返回直接子构造,找不到则抛错
getContext getContext(key: str): any 读取树上下文值,不存在则抛错
lock lock(): void 锁定该构造,之后不允许再添加子构造
setContext setContext(key: str, value: any): void 写入树上下文值
tryFindChild tryFindChild(): IConstruct? 按 id 返回直接子构造,找不到返回 undefined
tryGetContext tryGetContext(key: str): any 读取树上下文值,不存在返回 undefined
tryRemoveChild tryRemoveChild(childName: str): bool 删除指定名称的子构造(若存在)
validate validate(): MutArray<str> 校验本构造,返回错误消息数组

属性

名称 类型 说明
addr str 树内唯一的不透明地址
app IApp 构造树的根(cloud.App 对象),与 root 类似
children MutArray<IConstruct> 本构造的全部直接子构造
dependencies MutArray<IConstruct> 本节点上注册的全部依赖(非递归)
id str 本构造在当前作用域内的 id
locked bool 本构造及其所在作用域是否已锁定
metadata MutArray<MetadataEntry> 与构造关联的元数据数组
path str 构造在树中的完整绝对路径,组件以 / 分隔
root IConstruct 构造树的根(cloud.App 对象)
scopes MutArray<IConstruct> 该构造的全部父级作用域
scope IConstruct 定义该构造的作用域,树根处为 undefined
color str 构造的显示颜色(见下文色值列表)
defaultChild IConstruct id 为 Default 或 Resource 的子构造
description str 构造的显示描述
expanded bool 节点在 UI 中默认展开还是折叠
hidden bool 构造是否默认在树视图中隐藏
icon str 构造的显示图标(Heroicons 图标名)
sourceModule str 定义该构造的源文件或库
title str 构造的显示标题

从源码结构看,绝大多数方法/属性都是对底层 constructs 节点 _constructsNode 的透传封装(如 node.ts),而 addConnection 与 app/root 的解析则是 Wing SDK 自己实现的扩展逻辑。

节点标识:id、path、addr、scope 与树的根

id 与 path

  • id 是构造在当前作用域(scope)内唯一的标识,例如某个 Bucket 在 App 下的 id 可能是 "my-bucket"。
  • path 是沿树从根到该构造的完整路径,各组件以 / 连接,例如 root/my-bucket。path 是构造树定位与 tree.json、simulator.json 中资源索引的主键,见 target-sim/app.ts 中 resources[r.node.path] 的用法。

addr:树内唯一地址

addr 返回一个"不透明"的树内唯一地址,用于在重命名/重构构造树时仍能稳定标识资源。原文档明确给出了其格式与计算规则:

  • 长度为 42 字符的十六进制字符串,以 c8 开头,后跟 40 个小写十六进制字符(0-9a-f);
  • 通过对构造路径各组件计算 SHA-1 得到;
  • 为了支持构造树重构,id 为 Default 的构造会被排除在计算之外,因此同一棵树中可能出现相同地址。

示例:

c83a2846e506bcc5f10682b564084bca2d275709ee

addr 在 SDK 中被广泛用于资源命名:例如 shared-aws/bucket.ts 生成 BUCKET_NAME_${this.node.addr.slice(-8)}、shared-aws/function.ts 生成 FUNCTION_NAME_${this.node.addr.slice(-8)},shared/resource-names.ts 也使用 resource.node.addr.substring(0, 8) 参与资源名哈希。由此可见 addr 是跨平台资源命名的稳定基石。

scope、root 与 app

  • scope:返回定义该构造的作用域,树根处值为 undefined;
  • scopes:返回所有父级作用域列表,列表末尾是当前构造自身、首元素是树根;
  • root / app:都返回构造树的根。区别在于 root 返回 IConstruct,app 返回类型化更强的 IApp(即 cloud.App 对象)。

源码中 root 与 app 通过向上递归查找实现(node.ts):findApp 逐级向上寻找带 APP_SYMBOL 标记的构造,findRoot 则寻找被 _markRoot 标记的构造,找不到时抛出 "Cannot find root app" / "Cannot find root construct" 错误。二者均带缓存,首次访问后复用。

树遍历与子构造管理

Node 提供了一组子构造查询与修改能力:

API 行为
children 直接子构造数组
findChild(id) 按 id 查找直接子构造,找不到抛异常
tryFindChild(id) 按 id 查找直接子构造,找不到返回 undefined
findAll(order?) 返回自身及所有后代,默认 ConstructOrder.PREORDER(前序)
tryRemoveChild(childName) 按名称移除子构造,返回是否删除成功(源码标记为实验性 API)
defaultChild 返回 id 为 Default 或 Resource 的子构造,通常是提供底层核心功能的那个构造

defaultChild 的可写性在源码 node.ts 中体现:仅在默认子构造不叫 Resource/Default 时才需要覆盖;若将其设为 undefined,则恢复为按 Default/Resource 名称查找的默认行为。

这些 API 在 SDK 中随处可见,例如 preSynthesizeAllConstructs(core/app.ts)正是通过 app.node.findAll() 遍历整棵树并触发每个资源的 _preSynthesize()。

依赖管理:addDependency 与 DependencyGraph

addDependency(...deps: Array<IDependable>) 用于为当前构造注册对其他构造的"排序依赖",dependencies 属性返回(非递归地)注册在本节点上的全部依赖。

依赖的真正价值体现在合成阶段:SDK 在 core/dependency.ts 中构建 DependencyGraph,实现要点如下:

  • 为树中每个构造建立图顶点(以 node.path 为键);
  • 遍历所有构造的 node.dependencies 建立边(source → target);
  • 不跨越作用域边界建边——目标不在本作用域内时直接跳过(注释明确说明这是刻意的简化,便于图表只渲染自己的子节点);
  • 无入边的顶点(孤儿节点)统一挂到人工根顶点 _fosterParent 下;
  • topology() 返回拓扑排序后的构造序列。

模拟器合成时正是按这个拓扑顺序输出资源,保证依赖方在合成产物中排在被依赖方之后(见 target-sim/app.ts 的 new core.DependencyGraph(this.node).topology())。

上下文与元数据:setContext / getContext / addMetadata

树上下文(Tree Context)

setContext(key, value) 与 getContext(key) / tryGetContext(key) 构成一套沿树传递的键值上下文机制:

  • 上下文通常在树根初始化,树中任意位置都可以覆盖;
  • 上下文必须在添加任何子构造之前设置,因为子构造在构造期间可能读取上下文信息;
  • 若 key 已存在,setContext 会覆盖旧值;
  • getContext 在 key 不存在时抛异常,tryGetContext 则返回 undefined。

元数据(Metadata)

addMetadata(type, data, options?) 为构造添加任意元数据条目:

  • type:字符串,表示元数据类型;
  • data:元数据值(可以是 Token),若为 null/undefined 则该条元数据不会被添加;
  • options:constructs.MetadataOptions 可选参数;
  • 每个条目会自动附带添加时的堆栈追踪(stack trace),用于回溯到添加该条目的代码位置。

原文档指出,元数据可用来在 CloudFormation 模板中注入源码映射(source mapping)以改进诊断,也可支撑弃用提示(deprecation notices)等功能。metadata 属性返回与该构造关联的元数据数组(不可变)。

显示属性:让构造在 Wing Console 中"可见可读"

Node 上有一组面向展示的属性,它们最终会进入 tree.json 的 display 字段,驱动 Wing Console 的树视图渲染。合成逻辑位于 core/tree.ts 的 synthDisplay:只要 description、title、hidden、color、icon、expanded 任一被设置,就生成对应的 display 对象。

属性 类型 默认值 说明
title str — 构造的显示标题
description str — 构造的显示描述
sourceModule str — 定义该构造的源文件或库,如 @winglang/sdk
hidden bool — 默认是否在树可视化中隐藏(如模拟器内部资源 Policy、EventMapping 会隐藏,见 target-sim/policy.ts)
expanded bool false 节点默认折叠,设 true 则默认展开
icon str — Heroicons 图标名,如 "academic-cap"(图标集见 https://heroicons.com/)
color str — 显示颜色,支持的色值:orange、sky、emerald、lime、pink、amber、cyan、purple、red、violet、slate

SDK 中各云资源的 title/description 均在构造时设置(如 cloud/bucket.ts 的 "Bucket" / "A cloud object store");而颜色则按资源类型区分,例如 shared-aws/bucket.ts 将 Bucket 设为 amber、shared-aws/function.ts 将 Function 设为 pink。

校验与锁定:validate / addValidation / lock

  • addValidation(validation: IValidation):注册一个校验对象。当 node.validate() 被调用时,所有已注册校验的 validate() 方法都会被依次调用,并聚合返回所有错误;
  • validate():返回校验错误消息数组(MutArray<str>);
  • lock():锁定该构造,之后不允许再向其或其后代添加子构造;locked 属性返回当前构造或其所在作用域是否已锁定。

这套机制让 SDK 能够在合成前做集中式合法性检查,例如模拟器合成流程中的 preSynthesizeAllConstructs 遍历(core/app.ts)前后,均可通过 validate 捕获配置错误。

连接(Connections):addConnection 与 AddConnectionProps

addConnection(props) 是在两个构造之间添加一条"连接"——一段描述两个构造之间如何关联的元数据,例如"API 的 GET /hello 请求会调用某个 Function 的 invoke 操作"。这是 Wing 特有的资源关系追踪能力,最终会序列化到合成产物 connections.json 中。

AddConnectionProps 字段

字段 类型 必填 默认值 说明
name str 是 — 连接的名称
target IConstruct 是 — 连接的目标构造
source IConstruct 否 this 连接的源构造,省略时默认为调用 addConnection 的构造自身
sourceOp str 否 无操作 源构造支持的一个操作
targetOp str 否 无操作 目标构造支持的一个操作

底层实现

Node.addConnection 委托给 Connections.of(construct)(core/connections.ts),该实现以 Symbol.for("@winglang/sdk.core.Connections") 为键、挂在树的根节点上,因此同一棵树内的所有 addConnection 调用共享一个 Connections 单例。add 方法会按 source/sourceOp/target/targetOp/name 五元组去重,完全相同的连接不会被重复记录。

合成时 Connections.synth(outdir) 将连接写出为 connections.json(版本 connections-0.1),每条连接记录以构造的 node.path 标识源与目标:

{
  "version": "connections-0.1",
  "connections": [
    { "source": "root/api", "sourceOp": "request", "target": "root/Function", "targetOp": "invoke", "name": "get /hello" }
  ]
}

模拟器目标与 Terraform 目标在合成时都会写出该文件:模拟器见 target-sim/app.ts,共享 TF 后端见 shared-tf/app.ts。connections.json 的 Schema 定义在 simulator/simulator.ts 附近,测试快照见 test/core/snapshots/connections.test.ts.snap。

真实调用案例

1. API 路由与处理函数(target-sim/api.ts):每个路由注册时记录"请求 → Function.invoke"连接:

Node.of(this).addConnection({
  source: this,
  sourceOp: "request",
  target: fn,
  targetOp: cloud.FunctionInflightMethods.INVOKE,
  name: `${method.toLowerCase()} ${path}`,
});

2. Bucket 事件触发 Topic(cloud/bucket.ts):Bucket 的 put / put_json 操作连接到事件 Topic 的 publish:

Node.of(this).addConnection({
  source: this,
  sourceOp: op,
  target: topic,
  targetOp: TopicInflightMethods.PUBLISH,
  name: BucketEventType.CREATE,
});

3. 队列死信(DLQ)(target-sim/queue.ts):主队列的 pop 失败转投死信队列的 push,连接命名为 "dead-letter queue"。

4. 提升(lift)自动生成连接(std/resource.ts):每个资源在 _preSynthesize 阶段根据 _liftMap 递归为每个 lift 操作生成 name: "call" 的连接,记录 inflight 代码对依赖资源各操作的调用关系。

5. Token 引用推导连接(target-sim/app.ts):合成 simulator 规格时扫描资源 props 中的 token 引用,为每个引用自动补一条 name: "<ref>" 的连接(跳过 handle 属性,因为 inflight 方法调用的连接已覆盖)。

IApp:Wing 应用的抽象协议

IApp 接口(node.ts)扩展自 constructs.IConstruct,由 cloud.App 实现,表示一个完整的 Wing 应用。它额外暴露以下成员:

成员 类型 说明
node Node 应用自身的树节点
entrypointDir str 当前 Wing 应用入口文件所在目录
isTestEnvironment bool 是否为测试环境
parameters ParameterRegistrar 应用的参数注册器,用于注册/查找应用参数(平台参数体系)
workdir str 预检(preflight)期间可写入中间产物的 .wing 目录
makeId(prefix?) str 在给定作用域内生成唯一 ID,形如 '{prefix}{n}',n 为从 0 开始的递增整数序列

makeId 的实现位于 core/app.ts:以 scope.node.addr|prefix 为计数键,保证生成的 ID 在指定作用域内唯一。SDK 用其为自动生成的内部资源命名,例如 target-sim/api.ts 的 App.of(this).makeId(this, "OnRequestHandler")、target-sim/queue.ts 的 App.of(this).makeId(this, "Consumer"),以及 std/resource.ts 中为自动 ID 资源生成唯一标识。

在 Wing 应用中实践 std.Node

虽然 std.Node 是 SDK 内部机制,但开发者可以通过以下方式直接感知和使用它:

  • 访问应用信息:在预检代码中通过 App.of(this)(见 core/app.ts)取得 IApp,读取 entrypointDir、isTestEnvironment、workdir 等属性;
  • 自定义资源显示:实现资源时调用 Node.of(this).title、.description、.color、.icon 等属性,让自己的资源在 Wing Console 树视图中拥有友好的展示(tree.json 由 core/tree.ts 的 synthesizeTree 生成);
  • 追踪资源关系:通过 addConnection 记录"谁调用了谁、哪个操作触发哪个操作",这些关系会在合成产物 connections.json 中呈现,也供 Console 绘制交互关系图;
  • 稳定命名:借助 node.addr 保证资源名跨平台稳定,这与 docs/999-rfcs/2022-08-22-resource-naming.md 中讨论的资源命名策略一脉相承。

需要说明的是,Node 上标注 @internal 或实验性的能力(如 tryRemoveChild)在 SDK 内部使用,普通应用代码中一般通过 Node.of(resource) 读取属性即可,不必直接修改树结构。

小结

std.Node 是 Wing 构造系统的心脏:id/path/addr 提供稳定的树内定位,scope/root/app/scopes 描述树的层级关系,addDependency 与 DependencyGraph 决定合成顺序,addConnection 记录资源间的调用关系并产出 connections.json,setContext/addMetadata 支撑上下文与诊断信息,显示属性驱动 Console 可视化,validate/lock 保障树的合法性与不可变性。理解这层"内部节点",也就理解了 Wing 应用从预检代码到树形产物、再到可视化与部署的完整链路。

参考路径

登录后查看全文
wing