Wing 语言 Json 静态 API 全解析:从 json_static 测试用例到 Hangar 快照验证

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

Wing 语言 Json 静态 API 全解析:从 json_static 测试用例到 Hangar 快照验证

本篇指南以开源仓库 wing 中 json_static.test.w 测试用例及其 Hangar 快照为主线,系统梳理 Wing 标准库 Json 类型的全部静态方法(keys、values、deepCopy、deepCopyMut、delete、parse、tryParse、stringify 等)与 MutJson 可变类型的使用方式,并结合 SDK 源码与编译产物,揭示这些 API 的底层宏实现与"编译期内联"原理。读完本文,你将能熟练地在 Wing 的 preflight 与 inflight 两个阶段读写 JSON 数据,并理解 Hangar 快照测试如何为这类标准库 API 提供端到端保障。

背景:Wing 中的 Json 类型与可变性设计

Wing 为云原生场景提供了专门的 Json 类型(见 std/json.ts),它既可以表示对象,也可以表示数组、字符串、布尔值、数字乃至 null。与常规语言中的 JSON 库不同,Wing 将 JSON 值划分为两类:

  • Json(不可变):只读访问,提供 get、getAt、tryGet、tryGetAt、has 以及 asStr/asNum/asBool 等安全转换方法;
  • MutJson(可变):在 Json 基础上额外提供 set、setAt、delete 等修改能力(见 std/json.ts)。

这一区分在编译器层面被严格执行。仓库中的反向用例 invalid/json_static.test.w 证明:对不可变的 Json 调用 set 会直接产生编译错误——Member "set" doesn't exist in "Json"。因此,凡是需要增删改的场景,必须先通过 Json.deepCopyMut 获得一份可变副本。

测试用例全景:json_static.test.w

本文核心依据的测试源文件位于 tests/valid/json_static.test.w,它被存放在 tests/valid 目录下。根据 tests/README.md 的约定,/valid 下的用例应当编译成功,/invalid 下的用例应当编译失败。该用例将 Wing Json 静态 API 的读写、解析、序列化、类型转换以及 inflight 访问能力全部覆盖了一遍,是学习这套 API 的最佳入门教材。

其对应的 Hangar 测试运行快照 json_static.test.w_test_sim.md 给出了最终运行结果:

pass ─ json_static.test.wsim » root/Default/test:Access Json static inflight
pass ─ json_static.test.wsim » root/Default/test:has key or not

Tests 2 passed (2)
Snapshots 1 skipped
Test Files 1 passed (1)
Duration <DURATION>

两个 test 块全部通过,说明测试中涉及的全部静态方法在模拟器(sim)平台下行为符合预期。

遍历与拷贝:keys / values / deepCopy / deepCopyMut

测试开篇演示了 JSON 对象的键值遍历与深浅拷贝(对应 tests/valid/json_static.test.w):

// Get Keys
let x = Json {a: 123, b: {c: 456, d: 789}};
let k = Json.keys(x);
assert(k.length == 2);

// Get Values
let v = Json.values(x);
assert(v.at(0) == 123);

// Mutable Deep Copy
let m = Json.deepCopyMut(x);
m.set("a", 321);
assert(m.get("a") == 321);

// Immutable Deep Copy
let n = Json.deepCopy(m);
assert(m == n);

// Deleting keys
let var k2 = Json.keys(m);
assert(k2.length == 2);
Json.delete(m, "b");
k2 = Json.keys(m);
assert(k2.length == 1);

各方法的行为与 SDK 定义一一对应(见 std/json.ts):

静态方法 签名 语义
Json.keys keys(json: Json | MutJson): Array<str> 返回 JSON 对象的所有键(实现)
Json.values values(json: Json): Array<Json> 返回 JSON 对象的所有值(实现)
Json.deepCopyMut deepCopyMut(json: Json): MutJson 生成一份可变深拷贝(实现)
Json.deepCopy deepCopy(json: MutJson): Json 生成一份不可变深拷贝(实现)
Json.delete delete(json: MutJson, key: str): void 从可变 JSON 中删除指定键(实现)

注意 Json.delete 要求第一参数为 MutJson,这与 invalid/json_static.test.w 中"不可变对象不可修改"的设计一脉相承;而对 MutJson 实例还可以直接调用其实例方法 delete(key): bool(std/json.ts)。

解析与序列化:parse / tryParse / stringify

字符串与 JSON 之间的双向转换由三个静态方法承担(tests/valid/json_static.test.w):

// Parse string
let s = "\{\"a\": 123, \"b\": \{\"c\": 456, \"d\": 789}}";
let j = Json.parse(s);
assert(Json.keys(j).length == 2);

// Try parse string
let invalidJson = "invalid";
let tryParsed = Json.tryParse(invalidJson) ?? Json { key: "value" };
assert(tryParsed.get("key") == "value");

// Format to string
let jj = Json {a: 123, b: {c : 456, d : 789}};
let ss = Json.stringify(jj);
assert(ss == "\{\"a\":123,\"b\":\{\"c\":456,\"d\":789}}");

let ss2 = Json.stringify(jj, indent: 2);
assert(ss2 == "\{\n  \"a\": 123,\n  \"b\": \{\n    \"c\": 456,\n    \"d\": 789\n  }\n}");
  • Json.parse(str):严格解析,输入非法 JSON 字符串会直接抛错(实现);
  • Json.tryParse(str?):解析失败时返回 undefined 而非抛错,配合 ?? 空值合并运算符可以给出兜底值(实现)。SDK 注释明确说明其宏实现为 try { ... JSON.parse(args) } catch { return undefined },且参数为可选;
  • Json.stringify(json, options?):将 JSON 序列化为字符串,options 为 JsonStringifyOptions 结构体,其中 indent 指定缩进空格数(实现)。测试同时验证了紧凑输出(无缩进)与 indent: 2 的格式化输出,与 JSON 标准语义一致。

关于 JsonStringifyOptions 的完整字段定义,可查阅标准库 API 参考 docs/api/04-standard-library/std/json.md 中的 JsonStringifyOptions 一节。

从 Json 到基础类型:str / num / bool 的 fromJson

JSON 中取出的值是 Json 类型,需要转换后才能赋值给强类型变量。测试给出了三种典型转换(tests/valid/json_static.test.w):

let jsonOfMany = Json {a: 123, b: "hello", c: true};
assert(str.fromJson(jsonOfMany.get("b")) == "hello");
assert(num.fromJson(jsonOfMany.get("a")) == 123);
assert(bool.fromJson(jsonOfMany.get("c")));

对应的,Json 实例上也提供了一组"尝试安全转换"方法:asStr()、asNum()、asBool(),以及各自的 tryAsStr()、tryAsNum()、tryAsBool() 可选版本(见 std/json.ts)。两者区别在于:fromJson 是类型层面的转换,asXxx 系列是值层面的运行时断言转换(类型不匹配时抛错,tryAsXxx 则返回 undefined)。

inflight 阶段访问 Json 静态方法

Wing 语言区分 preflight(基础设施编排)与 inflight(运行时逻辑)两个执行阶段。Json 的静态方法在这两个阶段都可使用,测试用两个 test 块验证了这一点(tests/valid/json_static.test.w):

// Inflight access
test "Access Json static inflight" {
  let ss = Json.stringify(jj);
  assert(ss == "\{\"a\":123,\"b\":\{\"c\":456,\"d\":789}}");
}

// Check whether some key exists in a json
test "has key or not" {
  let hasCheck = Json {a: "hello", b: "wing"};
  assert(hasCheck.has("a") == true);
  assert(hasCheck.has("c") == false);
}

这里 jj 是在 preflight 阶段定义的 Json 值,被 inflight 闭包捕获后通过 lift 机制带入运行时;Json.stringify 以模块级静态函数的形式被 lift(见下方编译产物中 $liftMap 的 <a href="https://link.gitcode.com/i/83ef4e53854b72ee6286247866b96cec" target="_blank">"stringify"] 条目)。has(key) 方法基于 hasOwnProperty 判断键是否存在([std/json.ts),在云函数等 inflight 场景中常用于防御式读取。

编译产物:静态方法背后的宏内联

所有 Json 静态方法在 SDK 中都被标记为 @macro,即它们不是普通运行时函数,而是在编译期被直接内联为 JavaScript 表达式。这一点可以从 json_static.test.w_compile_tf-aws.md 中看到完整的编译快照证据:

以 preflight.cjs 片段为例,Json.keys 被编译为 $macros.__Json_keys(false, std.Json, x),Json.parse 编译为 $macros.__Json_parse(...),Json.stringify 编译为 $macros.__Json_stringify(...)(含 { indent: 2 } 选项),而 tryParse 与 ?? 组合则编译为 ($macros.__Json_tryParse(false, std.Json, invalidJson) ?? ({"key": "value"}))——正好对应测试中"解析失败回退默认值"的逻辑。

在 inflight 侧,inflight.$Closure1-1.cjs 中通过 $macros.__Json_stringify(false, $std_Json, $jj) 完成序列化,而 $liftMap 明确列出 lift 了 Json 模块的 stringify 能力与被捕获的 jj 变量,这印证了 inflight 中调用静态方法所需的显式 lift 机制:

get _liftMap() {
  return ({
    "handle": [
      [$stdlib.core.toLiftableModuleType(..., "@winglang/sdk/std", "Json"), ["stringify"]],
      [jj, []],
    ],
    ...
  });
}

同时,main.tf.json 表明该测试在 tf-aws 平台下编译出的基础设施仅包含空的 AWS provider 配置——因为 json_static.test.w 只使用了纯标准库类型而未创建任何云资源,这正是测试"纯语言能力"用例的典型形态。

通过 Hangar 快照守护标准库 API

上述两篇快照(test_sim 与 compile_tf-aws)均由仓库中的 Hangar 测试工具链生成,位于 tools/hangar。Hangar 是 Wing 的端到端测试套件,负责编译 tests/valid 与 tests/invalid 下的所有用例并固化产物快照。它的工作模式是:

  1. 对每个 .test.w 文件执行编译(compile)与测试(test)两类目标;
  2. 将编译生成的 JavaScript/TypeScript 产物(如 preflight.cjs、inflight.$ClosureN-1.cjs、main.tf.json)以及测试运行输出(stdout.log)保存为 Markdown 快照;
  3. 后续任何对编译器或标准库的改动,若导致产物输出变化,都会在快照对比中暴露,从而防止 API 行为回归。

这意味着本文讲解的每一个 Json 静态方法都有"可编译、可运行、行为稳定"三重保障:tests/valid 提供输入,test_sim 快照验证运行结果,compile_tf-aws 快照锁定编译产物。

关键要点速览

  • 不可变优先:Json 只读,修改前必须先 Json.deepCopyMut 转为 MutJson;对不可变对象调用 set 会在编译期报错。
  • 深拷贝语义:deepCopy/deepCopyMut 均为深拷贝,互不影响原对象,测试中 m 修改后 deepCopy(m) 与 m 仍相等。
  • 解析双通道:parse 抛错、tryParse 返回可选值,配合 ?? 实现安全兜底。
  • 格式化输出:stringify 通过 JsonStringifyOptions.indent 控制缩进,紧凑与美观两种输出均被测试锁定。
  • 双阶段可用:Json 静态方法在 preflight 与 inflight 均可调用,inflight 通过宏与 lift 机制访问。
  • 宏内联实现:SDK 中这些方法全部以 @macro 注解实现为编译期内联表达式,真正的行为定义在宏展开中。

想进一步深入,可以继续阅读仓库中的 docs/by-example/23-Json.md(Json 字面量、枚举、安全转换到结构体等场景示例)、docs/api/04-standard-library/std/json.md(Json、MutJson、JsonEntry、JsonStringifyOptions 完整 API 参考),以及查看 tests/valid 目录下 json.test.w、json_string_interpolation.test.w 等相邻用例,它们共同构成了 Wing 标准库 JSON 能力的完整测试矩阵。

登录后查看全文
wing