Wing 语言 math.sec 正割函数实战:从 API 用法到 sim 平台测试快照全解析

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

Wing 语言 math.sec 正割函数实战:从 API 用法到 sim 平台测试快照全解析

导读

本文围绕 Wing 语言标准库 math 模块中的 sec(正割)函数展开,以仓库内 sec.test.w 的 sim 平台测试快照 为切入点,完整还原其 API 签名、TypeScript 底层实现(1 / Math.cos(value))、边界值数学特性,以及 Hangar 测试框架自动生成快照的完整链路。读完本文,你将掌握 math.sec 在 preflight 与 inflight 两阶段中的正确调用方式,理解快照中每行输出(pass ─ sec.test.wsim » root/Default/test:inflight secant)的准确含义,并能在本地用 wing test -t sim 复现同样结果。

快照文件说了什么:一个可复现的测试证据

sec.test.w_test_sim.md 是 Wing 仓库中由 Hangar 测试套件自动生成的 Markdown 快照,位于 tools/hangar/snapshots/test_corpus/sdk_tests/math/ 目录,标题行注明了它的来源与执行环境:

# <a href="https://link.gitcode.com/i/d4102aab1491e1109a400602d9036446" target="_blank">sec.test.w</a> | test | sim

这一行揭示了三个关键信息:

  • 被测文件:tests/sdk_tests/math/sec.test.w,即仓库 SDK 测试语料中针对 sec 函数的测试用例;
  • 操作类型:test,即执行 Wing 测试(而非 compile 编译);
  • 目标平台:sim,即 Wing 内置的本地模拟器(simulator)平台,无需任何云账号即可运行。

快照正文记录了完整的标准输出(stdout.log):

pass ─ sec.test.wsim » root/Default/test:inflight secant

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

逐行解读:

输出行 含义
pass ─ sec.test.wsim » root/Default/test:inflight secant 名为 inflight secant 的测试用例通过。sec.test.wsim 是在 sim 平台上编译后生成的测试产物名称,root/Default/test:inflight secant 是该测试在应用树(application tree)中的完整路径:根节点 root → 默认作用域 Default → test 隐式测试作用域 → 用例 inflight secant
Tests 1 passed (1) 共 1 个测试,全部通过
Snapshots 1 skipped 本次测试未产生 Terraform 快照对比(sim 平台不生成 main.tf.json),故跳过 1 项快照校验
Test Files 1 passed (1) 1 个测试文件通过
Duration <DURATION> 执行时长被快照清洗机制归一化为占位符(原因见下文 Hangar 章节)

被测对象:Wing math.sec 的 API 形态

sec 是 Wing 标准库 math 模块 Util 类的静态函数。根据官方 API 参考 docs/api/04-standard-library/math/api-reference.md,其签名与语义为:

bring math;

math.sec(value: num);
  • 功能:计算角度的正割值(secant),参数单位为弧度(radians);
  • 参数:value: num,类型为 Wing 的 num(双精度浮点数);
  • 返回值:该角度的正割值,类型为 num。

调用前必须先通过 bring math; 引入模块。在 math 模块中,sec 与 csc(余割)、cot(余切)共同构成三角函数族,它们的逆函数分别是 asec、acsc、acot;此外模块还提供 sin、cos、tan、asin、acos、atan、atan2 等标准三角函数,以及 PI、TAU、E、INF 四个常量。sec 的核心数学关系为:

sec(x) = 1 / cos(x)

即正割是余弦的倒数,仅在 cos(x) ≠ 0 时有定义。

底层实现:一个表达式背后的设计

sec 在仓库中的实现位于 SDK 的 TypeScript 源码 packages/@winglang/sdk/src/math/math.ts,Util 类的第 346~348 行:

public static sec(value: number): number {
  return 1 / Math.cos(value);
}

可以看到,Wing 的 sec 并非独立实现三角函数,而是直接复用了 JavaScript 引擎的 Math.cos,再取倒数。这一点可以从源码结构推导出两个重要事实:

  1. 精度行为与宿主引擎一致:sec 的数值结果完全取决于运行时 JavaScript 引擎的 Math.cos 精度,因此快照中 sec(1) 断言为 1.8508157176809255 这类双精度尾数,在不同引擎间可能存在最后一位的差异,这也是 Wing 在断言中直接写死全精度字面量的原因。
  2. 奇点行为由 cos 决定:当输入角度使 cos 趋近于 0 时(如 PI / 2),sec 会趋向无穷大。由于 Math.cos(PI / 2) 在 IEEE-754 双精度下并非精确为 0(约为 6.123233995736766e-17),sec(PI / 2) 实际会返回一个极大而非 INF 的有限值。与 sec 对称,同文件中的 csc 实现为 1 / Math.sin(value),cot 实现为 1 / Math.tan(value),三者共享同一套“倒数 + 基础函数”的简洁模式。

测试用例逐行拆解:preflight 与 inflight 的双重验证

快照对应的测试源码位于 tests/sdk_tests/math/sec.test.w,全文如下:

bring math;

assert(math.sec(-0) == 1);
assert(math.sec(0) == 1);
assert(math.sec(1) == 1.8508157176809255);
assert(math.sec(-5) == 3.5253200858160887);
assert(math.sec(math.PI) == -1);
assert(math.sec(math.TAU) == 1);

test "inflight secant" {
  assert(math.sec(-0) == 1);
  assert(math.sec(0) == 1);
  assert(math.sec(1) == 1.8508157176809255);
  assert(math.sec(-5) == 3.5253200858160887);
  assert(math.sec(math.PI) == -1);
  assert(math.sec(math.TAU) == 1);
}

这段测试文件体现了 Wing 语言"一语言、两阶段"的核心设计:

  • preflight 阶段(文件顶层):assert 语句在编译期/预检阶段执行,用于在基础设施编排期校验函数行为;
  • inflight 阶段(test "inflight secant" { ... }):测试体在运行时以云函数语义执行,快照输出中的 root/Default/test:inflight secant 正是该用例在应用树中的注册路径。

六个断言的含义

输入(弧度) 期望值 数学解释
-0 1 余弦是偶函数,cos(-0) = cos(0) = 1,故 sec(-0) = 1;同时验证了 Wing 对 IEEE-754 负零值的正确处理
0 1 基准点:sec(0) = 1 / cos(0) = 1
1 1.8508157176809255 非特殊角验证:sec(1) ≈ 1.8508157,验证了通用数值路径的精度
-5 3.5253200858160887 负角验证:cos(-5) = cos(5),sec(-5) ≈ 3.5253201
math.PI -1 半周期点:cos(PI) = -1,sec(PI) = -1,验证了符号翻转
math.TAU 1 整周期点:TAU = 2π,cos(TAU) = 1,验证周期性

其中 math.PI、math.TAU 是 Util 类导出的常量,对应 TypeScript 源码中的 PI = Math.PI 与 TAU = 2 * Math.PI(见 math.ts 第 20~24 行)。TAU 在这里被用作"完成一圈"的周期锚点,配合 PI 形成对 secant 周期性的完整覆盖。

快照是怎么生成的:Hangar 测试框架链路

这份快照并非手写产物,而是 Wing 仓库测试基建 Hangar 自动生成的。其生成链路可以从源码中得到完整印证:

  1. 入口函数 testTest(tools/hangar/src/generated_test_targets.ts):

    • 将 platforms 固定为 ["sim"],执行参数为 ["test"];
    • 仅对入口文件(*.test.w、*.main.w 等)执行测试;
    • 设置环境变量 WING_HIDE_CONTAINER_LOGS: "1" 屏蔽容器日志;
    • 将命令的 stdout 写入 fileMap["stdout.log"],stderr 写入 fileMap["stderr.log"]。
  2. 命令执行 runWingCommand(tools/hangar/src/utils.ts):以 --no-update-check --no-analytics test <file> -t sim 形式调用 wing CLI,通过 execa 捕获输出。

  3. 输出清洗 sanitizeOutput(utils.ts):这是快照稳定性的关键——它会将绝对路径替换为 <ABSOLUTE>、把 Duration 3m12.5s 这类耗时归一化为 Duration <DURATION>、将端口、时间戳、IP 等易变信息替换为占位符。这正是快照中 Duration <DURATION> 的来历:快照只关心"是否通过"这一确定性结论,而非具体的毫秒级耗时。

  4. 快照落盘 createMarkdownSnapshot:将 fileMap 中的 stdout.log 连同标题(文件相对路径 + test + sim)组装成 Markdown 文件,写入 tools/hangar/snapshots/ 目录。仓库内 csc.test.w_test_sim.md、cos.test.w_test_sim.md 等同构快照均出自同一机制。

跨平台对照:sim 测试快照与 tf-aws 编译快照

同目录下还存在 sec.test.w_compile_tf-aws.md,它记录了同一文件在 tf-aws 平台的编译结果:

{
  "//": {
    "metadata": {
      "backend": "local",
      "stackName": "root"
    },
    "outputs": {}
  },
  "provider": {
    "aws": [
      {}
    ]
  }
}

两者形成互补:

  • test_sim 快照验证运行时行为:sec 的函数逻辑是否正确执行、断言是否全部通过;
  • compile_tf-aws 快照验证编译产物:由于 sec.test.w 是纯函数测试、不含任何云资源,编译到 AWS 平台后只生成一个空的 Terraform 配置(仅有 provider 声明,无 resource),outputs 为空。这从侧面印证了 math 模块是纯计算库——它不绑定云资源,因此在任意平台(sim、tf-aws 等)都能以相同语义运行。

从 generated_test_targets.ts 的源码可以看到,编译测试还包含对 .wing 产物目录的检查(包含 preflight.、inflight.、extern/ 等文件),并禁止快照中出现绝对路径 require——确保测试在任何机器上可复现。

本地复现:如何在你的机器上跑出同样的结果

快照给出了权威的"期望结果",你可以在本地复现验证(仓库只读,以下命令仅为查看与运行方式):

# 在仓库根目录安装依赖后,直接对测试文件执行 sim 平台测试
wing test tests/sdk_tests/math/sec.test.w -t sim

或使用 pnpm workspace 内的工具链执行 Hangar 测试套件(运行方式可参考 tools/hangar/README.md 与仓库根 package.json 中的脚本约定)。若一切正常,终端应输出与快照一致的 pass ─ sec.test.wsim » root/Default/test:inflight secant。

若要扩展验证,可参照仓库中 csc.test.w 的写法补充 sec(PI / 2) 等奇点附近的用例,注意此时返回值会是一个极大有限值而非 INF,断言前应先确认宿主引擎的实际精度行为。

小结

  • 用法上:math.sec 是 bring math 后的一个静态函数,入参为弧度制 num,语义即 1 / cos(x);
  • 实现上:SDK 源码 math.ts 以 1 / Math.cos(value) 一行完成,精度与奇点行为继承自宿主引擎;
  • 验证上:sec.test.w 在 preflight 与 inflight 两阶段各覆盖 6 个断言,其通过结果被 Hangar 框架固化为 sec.test.w_test_sim.md 快照,并辅以 tf-aws 编译快照证明该函数与平台无关。

这份快照不仅是"一个测试通过了"的标记,更是 Wing 语言测试基建(Hangar + 快照清洗 + sim 模拟器)如何保障标准库数学函数行为长期稳定的完整样本:任何对 sec 实现的回归改动,都会在与快照的对比中立即暴露。

登录后查看全文
wing