Wing 云语言 math 标准库 fibonacci 函数实战:从递归实现到 sim 平台测试快照验证

原创2026-10-13 18:27:371,759 阅读
文章标签:编程语言编译器云原生语言运行时

Wing 云语言 math 标准库 fibonacci 函数实战:从递归实现到 sim 平台测试快照验证

导读

本文以 Wing 仓库中 fibonacci.test.w_test_sim.md 快照文档为切入点,系统讲解 Wing 云语言 math 标准库中 fibonacci 静态函数的 API 用法、递归实现原理,以及 hangar 端到端测试框架如何通过 preflight 断言与 inflight 测试用例在 sim 模拟器平台上完成验证。读完本文,你将掌握 math.fibonacci 的调用方式、测试组织模式,以及如何解读 hangar 生成的测试快照输出。

一、快照文档定位:hangar 端到端测试的可视化结果

tools/hangar/__snapshots__/test_corpus/sdk_tests/math/fibonacci.test.w_test_sim.md 是一份由 hangar 测试框架自动生成的 Markdown 快照文件,用于记录 Wing 编译器 + 标准库端到端测试在 sim(模拟器)平台上的实际运行结果。文件名遵循 {测试文件名}.w_{测试用例名}_{目标平台}.md 的约定,其中:

  • fibonacci.test.w:被测的 Wing 源文件,位于 tests/sdk_tests/math/fibonacci.test.w;
  • test:本次快照记录的用例名(即源文件中的 test "inflight fibonacci" 测试块);
  • sim:目标平台,即 Wing 的本地模拟器平台。

快照的标题行 # <a href="https://link.gitcode.com/i/01d0e41c3cb9db3993f1f121e36bfca4" target="_blank">fibonacci.test.w</a> | test | sim 直接指向被测源文件的相对路径。换算到仓库根目录后,源文件即 tests/sdk_tests/math/fibonacci.test.w,属于 tests/sdk_tests/math/ 目录下 33 个数学模块测试用例之一。

从 tests/README.md 可知,tests 目录存放用于测试 Wing 编译器与标准库的示例:/valid 下是应编译成功的示例,/invalid 下是应编译失败的示例,而 sdk_tests 则是针对标准库各模块(api、bucket、math、queue 等)的专项测试。

二、被测源文件解读:preflight 与 inflight 双阶段验证

快照背后对应的实际测试源码 tests/sdk_tests/math/fibonacci.test.w 结构非常清晰,体现了 Wing 语言的核心设计——同一份代码可以同时运行在 preflight(基础设施阶段)与 inflight(运行时阶段):

bring math;

assert(math.fibonacci(0) == 0);
assert(math.fibonacci(1) == 1);
assert(math.fibonacci(2) == 1);
assert(math.fibonacci(3) == 2);
assert(math.fibonacci(4) == 3);
assert(math.fibonacci(5) == 5);
assert(math.fibonacci(6) == 8);
assert(math.fibonacci(7) == 13);
assert(math.fibonacci(8) == 21);
assert(math.fibonacci(9) == 34);
assert(math.fibonacci(10) == 55);

test "inflight fibonacci" {
  assert(math.fibonacci(0) == 0);
  assert(math.fibonacci(1) == 1);
  assert(math.fibonacci(2) == 1);
  assert(math.fibonacci(3) == 2);
  assert(math.fibonacci(4) == 3);
  assert(math.fibonacci(5) == 5);
  assert(math.fibonacci(6) == 8);
  assert(math.fibonacci(7) == 13);
  assert(math.fibonacci(8) == 21);
  assert(math.fibonacci(9) == 34);
  assert(math.fibonacci(10) == 55);
}

文件包含两个测试层面:

  1. 文件顶层的 preflight 断言:bring math; 引入标准库 math 模块后,直接在文件作用域以 assert 验证 fibonacci(0) 到 fibonacci(10) 的返回值。这 11 条断言在 preflight 阶段执行,即程序"定义基础设施"时便完成校验。Fibonacci 序列的前几项 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55 与断言一一对应。

  2. test "inflight fibonacci" 测试块:以 test 关键字声明一个命名测试用例,内部重复了相同的 11 条断言。测试块中的代码被编译为在 inflight(运行时)阶段执行的闭包,由 sim 模拟器调度执行——这正是快照输出中 root/Default/test:inflight fibonacci 路径的含义:测试用例挂载在应用的根节点 root/Default 下,名为 test:inflight fibonacci。

这种"同名断言分别在 preflight 与 inflight 各测一遍"的组织方式,验证了 math.fibonacci 在 Wing 的两个执行阶段行为一致,这也是 Wing 标准库函数测试的常见模式。

三、math.fibonacci 的 API 与底层实现

3.1 API 签名

math.fibonacci 是 Wing 标准库 math 模块 Util 类上的一个公开静态函数。官方 API 参考文档 docs/api/04-standard-library/math/api-reference.md 给出的签名如下:

bring math;

math.fibonacci(n: num);

参数说明:

参数 类型 必填 说明
n num 是 要计算的斐波那契数的位置(第 n 项)

函数描述为 "Calculates the nth Fibonacci number."(计算第 n 个斐波那契数)。在标准库中,Util 类以静态函数形式提供了 abs、ceil、floor、sqrt、log、sin、cos、factorial、combinations 等数十个数学工具,fibonacci 是其中的序列计算类函数之一。

3.2 源码实现:经典递归

math.fibonacci 的实际实现位于 packages/@winglang/sdk/src/math/math.ts 的第 187~192 行:

/**
 * Calculates the nth Fibonacci number.
 * @param n - The position of the Fibonacci number to calculate.
 */
public static fibonacci(n: number): number {
  if (n === 0 || n === 1) {
    return n;
  }
  return this.fibonacci(n - 1) + this.fibonacci(n - 2);
}

实现要点:

  • 递归基线:当 n 为 0 或 1 时直接返回 n 本身(fibonacci(0) = 0、fibonacci(1) = 1),这保证了递归终止;
  • 递推公式:其余情况返回 fibonacci(n - 1) + fibonacci(n - 2),即斐波那契数列的标准定义;
  • 调用方式:作为 Util 类的静态方法,通过 math.fibonacci(...) 直接调用,无需实例化(Util 类的构造函数是私有的,见该文件末尾的 private constructor() {})。

需要注意的是,这是一种未经记忆化(memoization)的朴素递归实现,时间复杂度为 O(2ⁿ)。从源码结构看,SDK 优先保证 API 的简洁与正确性,并没有针对大 n 值做性能优化,因此测试与日常使用中建议保持 n 在合理范围内(如测试覆盖的 0~10)。

另外,整个 Util 类实现了 _toInflightType() 方法(返回 InflightClient.forType(...)),这表明该类支持被编译为 inflight 客户端代码,从而能在运行时阶段(如 test 块内)被调用——这是 math.fibonacci 能在 test "inflight fibonacci" 中直接执行的原因。

四、快照内容解读:sim 平台上的测试输出

快照文档正文是一个名为 stdout.log 的代码块,记录了 wing test -t sim 执行后的标准输出:

pass ─ fibonacci.test.wsim » root/Default/test:inflight fibonacci

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

逐行解读:

  • pass ─ fibonacci.test.wsim » root/Default/test:inflight fibonacci:第一个 test "inflight fibonacci" 用例执行通过(pass)。wsim 表示 Wing sim 平台的测试产物;root/Default/test:inflight fibonacci 是测试用例在模拟器应用树中的完整路径;
  • Tests 1 passed (1):1 个测试用例,1 个通过,0 失败;
  • Snapshots 1 skipped:本次测试跳过了 1 个快照更新(即当前这份 .md 快照本身,说明测试运行期间未发生快照内容变化或选择了不更新);
  • Test Files 1 passed (1):1 个测试文件全部通过;
  • Duration <DURATION>:<DURATION> 是 hangar 对输出做归一化处理后的占位符——真实运行耗时被替换掉,以保证快照内容跨平台、跨机器稳定可比。

值得注意的是,preflight 阶段的 11 条 assert 是程序加载/编译阶段的一部分,它们不作为一个独立"测试用例"出现在测试计数中;只有 test 块才会被统计为用例。因此即使 preflight 断言全部通过,最终计数仍是 Tests 1 passed (1)。

五、快照是如何生成的:hangar 框架机制

这份快照并非手写,而是由 hangar 测试框架自动生成并比对的。相关机制可以从 tools/hangar 源码确认:

5.1 快照目录与命名规则

tools/hangar/src/paths.ts 定义了:

tools/hangar/src/utils.ts 中的 createMarkdownSnapshot 函数负责组装快照:它把被测 .w 文件相对于 tests 目录的路径、测试用例名、目标平台拼接成快照文件名(${wingFile}_${testCase}_${target}.md),并生成标题行与各输出文件的代码块。

5.2 测试用例的自动生成

tools/hangar/src/generate_tests.ts 会递归扫描 sdk_tests 目录下所有 .w 文件,为每个文件自动生成两个 vitest 用例:

test("wing compile -t tf-aws", async () => {
  await compileTest(...);
});

test("wing test -t sim", async () => {
  await testTest(...);
});

即每个 SDK 测试文件都要经历两条验证路径:编译到 tf-aws 平台(验证编译器与 Terraform 后端产物)和运行 wing test -t sim(在模拟器上实际执行测试)。本快照记录的就是后者的 testTest 执行结果。

5.3 输出归一化

同一文件中 sanitizeOutput 负责对运行输出做归一化处理,以保证快照可复现:统一换行符、去除绝对路径、去除随机 state 文件路径、把 Duration 时间替换为 <DURATION>、去除端口与时间戳等。快照中的 <DURATION> 正是这一机制的产物。

六、本地复现与验证方法

如果你已构建好 Wing 工具链,可以在本仓库内复现这份快照对应的测试结果:

  1. 运行全部 hangar 端到端测试(含快照比对与更新):

    turbo wing:e2e
    

    该命令是 turbo test -F hangar 的快捷方式(见 docs/contributing/01-start-here/05-development.md)。

  2. 只针对单个测试文件运行:

    pnpm wing -- test tests/sdk_tests/math/fibonacci.test.w
    
  3. 在 sim 平台单独跑测试并观察输出:

    pnpm wing -- test -t sim tests/sdk_tests/math/fibonacci.test.w
    

执行后,你会看到与快照 stdout.log 一致的 pass ─ fibonacci.test.wsim » root/Default/test:inflight fibonacci 输出,以及 Tests 1 passed (1) 的汇总;若运行耗时不同,Duration 行将以真实时间显示,只有写入快照时才被归一化为 <DURATION>。

七、使用建议与边界说明

基于源码与测试的实际情况,使用 math.fibonacci 时有几点值得注意:

  • 输入范围:当前 SDK 未对 n 做显式输入校验。传入负数时,递归会持续向负方向延伸(fibonacci(-1) 不满足 -1 === 0 || -1 === 1,继续递归 -2、-3……),最终导致栈溢出;传入非整数时行为同样不受控。因此调用前应自行保证 n 为非负整数,测试用例覆盖的 0 ≤ n ≤ 10 是安全区间;
  • 计算复杂度:朴素递归实现的性能随 n 指数级增长,大规模计算建议自行实现迭代或记忆化版本;
  • 双阶段可用:math.fibonacci 在 preflight 与 inflight 均可调用,适合在基础设施定义阶段做静态计算,也适合在运行时(如 test 块、云函数内)动态计算;
  • 快照是验证基线:__snapshots__ 下的 Markdown 快照是 CI 中"测试输出是否回归"的比对基线,不应手改;若行为有意变更,通过 hangar 更新快照。

小结

通过这份 fibonacci.test.w_test_sim.md 快照,我们可以完整还原 Wing 数学标准库函数从 API 定义(docs/api/04-standard-library/math/api-reference.md)、递归实现(packages/@winglang/sdk/src/math/math.ts)、双阶段测试(tests/sdk_tests/math/fibonacci.test.w)到端到端验证(tools/hangar)的全链路。这一模式同样适用于 math 模块下的 factorial、combinations、isPrime 等 30 余个函数以及 sdk_tests 下 api、bucket、queue 等其他模块的测试,可作为理解 Wing 标准库开发与测试规范的通用范本。

登录后查看全文
wing