Wing 语言 bool 类型实战:`bool.fromJson()` 解析 JSON 布尔值与 hangar 快照测试
Wing 语言 bool 类型实战:bool.fromJson() 解析 JSON 布尔值与 hangar 快照测试
导读
在 Wing 语言中,bool 是内置基础类型之一,而 JSON 数据与强类型之间的转换是云应用开发中最常见的痛点。本文以仓库中的 hangar 快照 bool.test.w_test_sim.md 为线索,结合对应的测试用例 tests/sdk_tests/std/bool.test.w 与 SDK 标准库源码,系统讲解 bool.fromJson() 的用法、JSON Schema 校验原理、错误信息格式,以及 hangar 快照测试体系的验证机制。读完本文,你将掌握如何在 Wing 中安全地从 Json 提取布尔值,并能看懂标准库相关测试的组织方式。
快照文档揭示了什么
快照文件 bool.test.w_test_sim.md 是 hangar 测试工具在 sim(模拟器)目标下运行 bool.test.w 后记录的标准输出:
pass ─ bool.test.wsim » root/Default/test:fromJson()
Tests 1 passed (1)
Snapshots 1 skipped
Test Files 1 passed (1)
Duration <DURATION>
这份快照说明了三件事:
- 测试文件通过 sim 平台编译执行,测试名称为
fromJson(),属于root/Default作用域; - 该测试一次性全部通过(
Tests 1 passed (1)),快照被跳过(Snapshots 1 skipped,即快照比对未触发更新,说明输出与已记录基线一致); Duration <DURATION>中的占位符是 hangar 刻意为之,用于消除测试耗时的抖动,保证快照可稳定比对。
快照中的相对链接 ../../../../../../tests/sdk_tests/std/bool.test.w 指向实际测试源文件,以仓库根目录为起点即为 tests/sdk_tests/std/bool.test.w,下文对该文件逐段剖析。
bool.fromJson():API 与 SDK 底层实现
方法签名
在 Wing 标准库中,bool 类型的 fromJson 静态方法定义于 packages/@winglang/sdk/src/std/bool.ts:
public static fromJson(json: Json, options?: JsonValidationOptions): boolean {
const schema = JsonSchema._createJsonSchema({
$id: "bool",
type: "boolean",
} as any);
schema.validate(json, options);
return json as any;
}
关键点:
- 它接收一个
Json类型入参,返回boolean; - 校验依赖 JSON Schema 描述
{ "$id": "bool", "type": "boolean" },即要求输入必须是 JSON 布尔值; - 第二个参数
options类型为 JsonValidationOptions,定义于json.ts:
export interface JsonValidationOptions {
/** Unsafe mode to skip validation (may lead to runtime errors) */
readonly unsafe?: boolean;
}
当 unsafe: true 时校验会被跳过,文档源码注释明确警告这"可能导致运行时错误",因此日常开发中应保持默认(开启校验)。
JSON Schema 校验的真实调用链
schema.validate() 实现在 packages/@winglang/sdk/src/std/json_schema.ts:
public validate(obj: Json, options?: JsonValidationOptions) {
if (options?.unsafe) {
return; // skip validation
}
const validator = this.validator.compile(this._rawSchema);
const valid = validator(obj);
if (!valid) {
const schemaId = this._rawSchema.$id.replace("/", "");
throw new Error(
`unable to parse ${schemaId}:\n- ${validator.errors
?.map(
(error: any) => schemaId + error.instancePath + " " + error.message,
)
.join("\n- ")}`,
);
}
}
从源码可以确认以下行为:
- 校验失败时抛出的错误以
unable to parse <schemaId>开头,bool类型的 schemaId 即bool,因此运行时错误消息为unable to parse bool:...; - 错误会附带 JSON Schema 校验器的详细错误路径与原因(如
bool must be boolean这类消息片段),便于定位; - 该校验逻辑同时被
_fromJson与_tryFromJson(同文件 json_schema.ts)复用,_tryFromJson捕获异常并返回undefined,为"尝试解析"场景提供了不抛错的分支。
测试用例逐段解读
辅助函数 assertThrows
tests/sdk_tests/std/bool.test.w 开头定义了一个通用断言辅助函数:
let assertThrows = (expected: str, block: (): void) => {
let var error = false;
try {
block();
} catch actual {
assert(actual.contains(expected));
error = true;
}
assert(error);
};
它验证两件事:闭包 block 执行期间必须抛出异常,且异常消息必须包含 expected 子串。这保证了"错误路径"测试既确认了异常发生,又确认了错误文案符合预期。
紧接着定义错误常量(L13):
let PARSE_ERROR = "unable to parse bool";
它正是上文 json_schema.ts 校验失败时错误消息的前缀,测试与实现两处的文案严格对应。
正向与负向用例
测试文件在 test "fromJson()" 块内同时覆盖了成功与失败两条路径(L28-L35):
test "fromJson()" {
let t = bool.fromJson(Json.parse("true"));
assert(t == true);
let f = bool.fromJson(Json.parse("false"));
assert(f == false);
try { bool.fromJson(Json 123); } catch s { assert(s.contains(PARSE_ERROR)); }
}
- 正向:
Json.parse("true")与Json.parse("false")均可成功转换为bool,且转换结果与原值相等; - 负向:将 JSON 数字
123传入bool.fromJson()会抛出异常,异常消息包含unable to parse bool。
值得注意的是测试块外(L18-L25)还运行了相同逻辑的顶层断言,说明这些调用既可出现在 test 块中(编译为目标平台的可执行测试),也可直接作为顶层表达式参与程序执行——这体现了 Wing 中 test 块与普通代码的边界差异。
JSON 数字字面量语法
负向用例中的 Json 123 是 Wing 的 JSON 字面量语法:以 Json 关键字开头,直接书写 JSON 值。Json.parse("true") 则是把字符串解析为 Json。两种方式都能得到 Json 类型,但类型内容不同——前者是数字,后者是布尔,这正是校验器区分"可解析"与"不可解析"的依据。
与 str、num 的 fromJson 对照
bool.fromJson 并非孤例,Wing 标准库为基础类型提供了统一的 JSON 转换家族:
- tests/sdk_tests/std/string.test.w 中
str.fromJson(Json "Hello")验证字符串解析,str.fromJson(Json 123)触发同样的解析错误; - tests/sdk_tests/std/number.test.w 中
num.fromJson(Json 12)验证数字解析; - 底层实现上,
String、Number与Boolean的fromJson均采用各自类型的 JSON Schema(type分别为string、number、boolean)走同一套validate流程。
从 packages/@winglang/sdk/src/std/json.ts 的宏定义还可以看到,Json 类型本身也提供 tryAsBool、asBool 等类型提取宏,失败时同样抛出 unable to parse ... as a boolean 类错误。也就是说,Wing 中"从 JSON 取布尔"有两条路径:从 Json 值侧用 Json.asBool()/tryAsBool(),从类型侧用 bool.fromJson(),二者在错误处理策略上略有差异(前者宏内联、后者走 JSON Schema 校验),但都在编译期或运行期提供类型安全保护。
编译器层面的约束
从编译器源码 packages/@winglang/wingc/src/type_check.rs 可见,fromJson 与 tryFromJson 是编译器识别的特殊方法名——类型检查阶段会限制只有"字段均可由 JSON 表示"的 struct 才能定义 fromJson,确保该方法只出现在合法的强类型转换场景。基础类型(如 bool)的 fromJson 作为标准库能力被直接支持,无需额外定义。同时,type_check.rs 中还有一条相关提示,当开发者需要把动态 Json 转成强类型时,编译器会建议使用 fromJson() 来完成显式转换,这印证了 fromJson 是 Wing 中 JSON 反序列化的标准入口。
如何在本仓库复现与扩展验证
仓库为只读资源,你可以在本地对测试进行复现与扩展:
- 阅读完整测试源文件 tests/sdk_tests/std/bool.test.w,对比快照 bool.test.w_test_sim.md;
- 通过 hangar 工具(tools/hangar)在 sim 目标下运行该测试,观察是否得到与快照一致的输出;
- 尝试扩展边界用例:
bool.fromJson(Json true)、bool.fromJson(Json "true")(字符串布尔会被拒绝)、以及传入unsafe选项时的行为差异,逐一对照 bool.ts 与 json_schema.ts 的实现预期结果。
总结
bool.fromJson()是 Wing 中把Json安全转换为布尔类型的标准入口,底层基于 JSON Schematype: boolean校验(bool.ts);- 校验失败统一抛出以
unable to parse bool开头、包含 schemaId 路径的错误消息(json_schema.ts),测试中的PARSE_ERROR常量与其严格对应; - hangar 快照 bool.test.w_test_sim.md 记录了
fromJson()测试在 sim 目标的通过结果,是测试输出与实现行为的双重佐证; - 建议在业务代码中优先使用
bool.fromJson()处理外部 JSON 布尔字段,并利用try/catch捕获unable to parse系列错误,实现优雅降级。