Wing 云语言 math 标准库 fibonacci 函数实战:从递归实现到 sim 平台测试快照验证
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);
}
文件包含两个测试层面:
-
文件顶层的 preflight 断言:
bring math;引入标准库 math 模块后,直接在文件作用域以assert验证fibonacci(0)到fibonacci(10)的返回值。这 11 条断言在 preflight 阶段执行,即程序"定义基础设施"时便完成校验。Fibonacci 序列的前几项0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55与断言一一对应。 -
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 定义了:
sdkTestsDir = testDir/sdk_tests(即 tests/sdk_tests);snapshotDir = hangarDir/__snapshots__(即 tools/hangar/snapshots)。
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 工具链,可以在本仓库内复现这份快照对应的测试结果:
-
运行全部 hangar 端到端测试(含快照比对与更新):
turbo wing:e2e该命令是
turbo test -F hangar的快捷方式(见 docs/contributing/01-start-here/05-development.md)。 -
只针对单个测试文件运行:
pnpm wing -- test tests/sdk_tests/math/fibonacci.test.w -
在 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 标准库开发与测试规范的通用范本。