Wing 语言 Json 静态 API 全解析:从 json_static 测试用例到 Hangar 快照验证
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 下的所有用例并固化产物快照。它的工作模式是:
- 对每个
.test.w文件执行编译(compile)与测试(test)两类目标; - 将编译生成的 JavaScript/TypeScript 产物(如
preflight.cjs、inflight.$ClosureN-1.cjs、main.tf.json)以及测试运行输出(stdout.log)保存为 Markdown 快照; - 后续任何对编译器或标准库的改动,若导致产物输出变化,都会在快照对比中暴露,从而防止 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 能力的完整测试矩阵。