Wing 语言 bool 类型实战:`bool.fromJson()` 解析 JSON 布尔值与 hangar 快照测试

原创2026-10-14 23:54:471,668 阅读
文章标签:编程语言编译器云原生语言运行时

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>

这份快照说明了三件事:

  1. 测试文件通过 sim 平台编译执行,测试名称为 fromJson(),属于 root/Default 作用域;
  2. 该测试一次性全部通过(Tests 1 passed (1)),快照被跳过(Snapshots 1 skipped,即快照比对未触发更新,说明输出与已记录基线一致);
  3. 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 反序列化的标准入口。

如何在本仓库复现与扩展验证

仓库为只读资源,你可以在本地对测试进行复现与扩展:

  1. 阅读完整测试源文件 tests/sdk_tests/std/bool.test.w,对比快照 bool.test.w_test_sim.md;
  2. 通过 hangar 工具(tools/hangar)在 sim 目标下运行该测试,观察是否得到与快照一致的输出;
  3. 尝试扩展边界用例:bool.fromJson(Json true)、bool.fromJson(Json "true")(字符串布尔会被拒绝)、以及传入 unsafe 选项时的行为差异,逐一对照 bool.ts 与 json_schema.ts 的实现预期结果。

总结

  • bool.fromJson() 是 Wing 中把 Json 安全转换为布尔类型的标准入口,底层基于 JSON Schema type: 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 系列错误,实现优雅降级。
登录后查看全文
wing