Wing 语言 math.hypot 函数实战：从 SDK 实现到 hangar 快照验证

本篇技术指南围绕 Wing 语言标准库中的 math.hypot 数学函数展开，结合当前仓库内 hypot 测试用例、SDK 源码实现 以及 hangar 快照文件，完整讲解 hypot 的数学语义、API 签名、preflight/inflight 双阶段调用方式，以及 Wing 工具链如何通过 hangar 快照测试自动验证该函数在 sim（模拟器）与 tf-aws（Terraform + AWS）两个平台上的正确性。读完本文，你将掌握 math.hypot 的正确用法、精度处理技巧，并能理解 Wing 项目"测试用例 + 快照"的双重验证机制。

一、从快照文件说起：一份测试证据的解读

关联文档 hypot.test.w_test_sim.md 是 Wing 仓库 hangar 测试套件为 hypot.test.w 生成的 sim 平台运行快照，全文是测试通过的 stdout 日志：

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

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

快照揭示了几条关键信息：

• 测试入口：测试名为 inflight hypot，路径为 root/Default/test:inflight hypot，说明被测逻辑运行在 inflight（飞行时） 阶段；
• 判定结果：pass 表示断言全部通过，Tests 1 passed (1) 确认该测试文件中共有 1 个用例；
• 快照机制：Snapshots 1 skipped 表明运行器跳过了该快照自身的重写（即本次运行结果与已存储快照一致，无需更新）；
• 平台标识：文件名后缀 _test_sim 表示该快照记录的是 sim（本地模拟器）平台 下的 wing test 执行结果。

hangar 是 Wing 的端到端测试工具链（见 tools/hangar/README.md），它会为 tests/sdk_tests/math/ 目录下的每个 .w 测试文件生成多份快照：既包括上面这份 sim 运行快照，也包括一份 tf-aws 编译快照。后者展示 hypot.test.w 在 tf-aws 平台编译后的 main.tf.json——由于纯数学调用不产生任何云资源，生成的 Terraform 配置仅包含 AWS provider 的空声明与 backend: "local" 元数据，这从侧面印证了 hypot 是纯函数运算，不涉及基础设施资源。

二、math.hypot 的数学语义与 SDK 实现

hypot 是 Wing 标准库 math 模块提供的静态方法，用于计算"从原点出发、以给定坐标数组为端点的向量长度"。在数学上，它对应多维空间中的欧几里得范数：

hypot([x1, x2, ..., xn]) = sqrt(x1² + x2² + ... + xn²)

其 SDK 实现在 packages/@winglang/sdk/src/math/math.ts：

/**
 * Calculate the length of the vector from the origin to the point given by the coordinates
 * @param coordinates Array of coordinates
 * @returns
 */
public static hypot(coordinates: number[]): number {
  return Math.hypot(...coordinates);
}

从源码结构看，Wing 的 math.hypot 直接委托给底层 JS 引擎的 Math.hypot，并通过展开运算符 ...coordinates 将坐标数组展开为变长参数传入。这意味着 Wing 的 hypot 完整继承了 ECMAScript Math.hypot 的标准行为，包括两个重要特性：

• 任意维度支持：传入 2 个、3 个乃至更多坐标都能计算，例如 hypot([3, 4, 5]) 计算三维向量 (3,4,5) 的长度 √50 ≈ 7.07；
• 数值稳定性：原生 Math.hypot 采用避免中间平方溢出的算法，当坐标中存在极大或极小值时，比朴素实现 sqrt(a*a + b*b) 更不容易出现 Infinity 或下溢为 0 的问题，这是从 ECMAScript 标准语义可以合理推断的实现细节。

此外，hypot 对负坐标天然兼容——由于先平方再开方，hypot([-5]) 的结果是 5，这与绝对值运算在语义上等价。

三、API 签名与参数约定

根据 docs/api/04-standard-library/math/api-reference.md 中的 API 参考，hypot 的完整签名如下：

bring math;

math.hypot(coordinates: MutArray<num>);

参数说明：

项目	说明
函数名称	hypot，位于 math 标准库命名空间下
参数 coordinates	必填，类型为 MutArray<num>（可变的 num 数组），即各维度的坐标值
返回值	num 类型，向量长度
调用前提	文件顶部必须先 bring math; 引入标准库 math 模块

需要特别注意的是，Wing 中该参数的类型标注是 MutArray<num>（可变数组）。这意味着在传参时可以传入普通数组字面量 [3, 4]（类型推断时会按上下文适配），也可以传入一个可变的 Array<num> 变量；但不可变数组 Array<num>（Wing 中以 Array 表示的只读容器）在此签名下属于不同类型，直接传入可能触发类型不匹配的诊断——这一点从 API 参考中参数类型声明可以明确确认。

四、测试用例深度解读：preflight 与 inflight 双阶段验证

hangar 快照验证的对象是 tests/sdk_tests/math/hypot.test.w，其完整内容如下：

bring math;

assert(math.hypot([3, 4]) == 5);
assert(math.hypot([5, 12]) == 13);
assert(math.round(math.hypot([3, 4, 5]), decimalPlaces: 2) == 7.07);
assert(math.hypot([-5]) == 5);

test "inflight hypot" {
  assert(math.hypot([3, 4]) == 5);
  assert(math.hypot([5, 12]) == 13);
  assert(math.round(math.hypot([3, 4, 5]), decimalPlaces: 2) == 7.07);
  assert(math.hypot([-5]) == 5);
}

这份测试覆盖了 hypot 的四个关键行为：

1. 经典勾股三元组：hypot([3, 4]) == 5、hypot([5, 12]) == 13，验证二维平面中最常见的整数边长场景；
2. 多维向量：hypot(<a href="https://link.gitcode.com/i/1862400e164df02a77884dab76ce0044" target="_blank">3, 4, 5]) 的结果 √50 ≈ 7.071...，因为不是整数，测试借助 math.round(..., decimalPlaces: 2) 将结果四舍五入到小数点后两位，与期望值 7.07 比较——展示了浮点断言前先做精度规整的工程技巧（round 的 decimalPlaces 参数实现见 [math.ts，其原理是乘以 10^decimalPlaces 后取整再除回）；
3. 负数与一维向量：hypot([-5]) == 5，验证平方项消去了符号影响，单坐标向量长度即其绝对值；
4. 双阶段执行：文件顶部的 4 条 assert 在 preflight（预飞行，编译期/资源定义期） 执行，而 test "inflight hypot" 块内的相同断言在 inflight（飞行时，运行时） 执行。快照中 pass ─ ...test:inflight hypot 正是对 inflight 分支运行通过的记录。

这种"顶部断言 + test 块"的双层结构是 Wing 测试的标准范式：preflight 层验证函数在构造阶段可用，inflight 层验证其在运行时环境可用。math 作为纯计算模块在两阶段行为完全一致（源码中通过 InflightClient.forType(__filename, this.name) 生成 inflight 客户端，见 math.ts），因此两组断言的结果相同。

五、在 hangar 测试套件中的定位与运行方式

hypot.test.w 位于 tests/sdk_tests/math/ 目录，与 abs、sqrt、log、trigonometry（sin/cos/tan）、floor_ceil_round 等 30 余个数学函数测试文件并列，共同构成 math 标准库的行为回归矩阵。每个测试文件都由 hangar 工具链驱动，产出 sim 与 tf-aws 两套快照：

• sim 平台（_test_sim 快照）：在本机模拟器上运行 wing test，验证函数在模拟环境中的行为，即本文剖析的 hypot.test.w_test_sim.md；
• tf-aws 平台（_compile_tf-aws 快照）：将测试源码编译为 Terraform 配置并核对生成的 main.tf.json，验证纯计算代码不会意外产生云资源，见 hypot.test.w_compile_tf-aws.md。

想要在本地复现这份快照对应的测试，可在仓库根目录执行：

wing test tests/sdk_tests/math/hypot.test.w

wing test 是 Wing 内置的轻量级测试命令（详见 docs/by-example/32-testing.md），它会以 test 关键字声明的用例为单位执行 inflight 代码并汇总结果；assert 失败时测试以非零状态退出，保证 CI 中断。当测试行为发生变化时，hangar 会提示快照不匹配，需人工审阅后更新快照，从而保证对 SDK 行为的每次改动都可追溯。

六、典型应用场景与注意事项

math.hypot 适合在以下场景中使用：

• 几何/距离计算：计算二维或三维空间中两点间的欧几里得距离（先做坐标差再求 hypot），例如在模拟器或数据处理任务中计算玩家与目标的距离；
• 向量归一化：先 hypot 求模长，再逐分量除以模长得到单位向量；
• 多轴合成：计算多维度量的合成幅度，如加速度、力或传感器信号的合成强度；
• 数值稳定性敏感场景：当坐标绝对值跨度很大时，原生 Math.hypot 的抗溢出特性优于朴素平方和开方。

使用时需要注意：

1. 必须 bring math;：math 是标准库模块，使用前需显式引入（API 参考中的示例签名已给出该前置语句）；
2. 参数为数组而非变长实参：与某些语言不同，Wing 的 math.hypot 接收一个 MutArray<num>，调用时必须把坐标打包成数组字面量（如 [3, 4]）；
3. 浮点比较先规整精度：非整数结果（如 hypot([3, 4, 5])）直接与浮点字面量比较可能因精度抖动而不稳定，测试中的标准做法是结合 math.round(..., decimalPlaces: 2) 规整后再断言；
4. 空数组边界：从实现看，Math.hypot(...[]) 在 ECMAScript 中返回 0，即空坐标数组的长度为 0，但该行为未在测试用例中显式覆盖，依赖此边界时建议自行补充断言。

结语

math.hypot 是 Wing 标准库中"小而完整"的纯计算函数代表：它有清晰的数学语义、直接映射到 JS 引擎的稳定实现、覆盖 preflight 与 inflight 两阶段的测试用例，以及 hangar 工具链在 sim 与 tf-aws 两个平台上自动生成的回归快照。通过研读 测试源码、SDK 实现 与 快照证据 三者的对应关系，你可以把同样的"源码 + 测试 + 快照"研究路径迁移到 math 模块的其他函数（如 sqrt、log、三角系列），快速建立对整个标准库行为边界的准确认知。