Wing 语言 duration 时间类型全解析:字面量、单位换算与 hangar 快照测试验证
Wing 语言 duration 时间类型全解析:字面量、单位换算与 hangar 快照测试验证
Wing 是一门面向云原生场景、将基础设施与运行时代码统一为单一语言的编程语言。本篇围绕仓库中的 duration.test.w 及其 hangar 快照测试文档,系统讲解 Wing 标准库中 duration(时间持续)类型的字面量语法、七个单位之间的换算规则、SDK 底层实现原理,以及它在 sim 模拟目标与 tf-aws 编译目标下如何被验证。读完本文,你将掌握 duration 的完整单位换算表、工厂方法用法,以及如何通过快照测试确认这些换算行为在编译器与运行时两层的一致性。
从 hangar 快照说起:一张测试结果文档读出的信息
关联文档 duration.test.w_test_sim.md 是 Wing 官方测试编排工具 hangar 为 duration.test.w 在 sim(模拟器)目标下生成的快照:
pass ─ duration.test.wsim » root/Default/test:duration
Tests 1 passed (1)
Snapshots 1 skipped
Test Files 1 passed (1)
Duration <DURATION>
这份快照本身很简短,但它指向了三个关键事实:
- 测试源码位于 tests/sdk_tests/std/duration.test.w,文件内包含一个名为
duration的test用例; - 在 sim 目标下,该用例一次性通过(
Tests 1 passed (1)),说明源码中全部assert断言都成立; - 快照中的
Duration <DURATION>是占位符,由 hangar 在比对时统一替换,表示测试执行耗时不计入快照内容。
同目录下还有它的编译快照 duration.test.w_compile_tf-aws.md,其 main.tf.json 仅包含空的 aws provider 配置、没有任何云资源——这是因为 duration 属于纯数据(data-only)类型,单纯的时间换算测试不会产生任何基础设施资源,因此 tf-aws 编译产物是"空栈"。这两份快照合在一起,正好勾勒出 duration 类型的全貌:语言层面有字面量语法,运行时层面有换算语义,而测试层面用断言与快照锁定了行为。
duration 是什么:语言参考中的内置类型
Wing 语言参考 docs/api/05-language-reference.md 将 Duration(别名 duration)定义为"表示一段时间长度(time duration)"的类型:
let oneMinute = 1m;
let twoSeconds = 2s;
let threeHours = 3h;
let halfMinute: duration = 0.5m;
三个核心特征:
- 字面量后缀语法:数字直接跟单位后缀即可构造 duration,支持
ms(毫秒)、s(秒)、m(分钟)、h(小时)、d(天)、mo(月)、y(年)七种后缀,也支持0.5m这样的小数; - 可立即换算:
oneMinute.seconds == 60、halfMinute.seconds == 30、threeHours.minutes == 180; - 不可变且可跨阶段引用:文档明确写道 "Duration objects are immutable and can be referenced across inflight context"——即 duration 对象不可变,且可以在 preflight(预飞阶段)与 inflight(运行阶段)之间安全传递,这一点在 SDK 实现里通过
ILiftable接口得到了印证。
底层换算公式:从字面量到 fromSeconds 的编译器降级
duration 字面量并不是魔法,编译器把每个字面量都降级(desugar)为一次 duration.fromSeconds(...) 调用。在编译器源码 packages/@winglang/wingc/src/parser.rs#L561-L594 的 build_duration 函数中,可以看到明确的换算系数:
| 字面量后缀 | 换算为秒的系数 | 对应源码分支 |
|---|---|---|
ms |
数值 ÷ 1000 | "milliseconds" => value_literal / 1000_f64 |
s |
数值 × 1 | "seconds" => value_literal |
m |
数值 × 60 | "minutes" => value_literal * 60_f64 |
h |
数值 × 3600 | "hours" => value_literal * 3600_f64 |
d |
数值 × 86400 | "days" => value_literal * 86400_f64 |
mo |
数值 × 2,628,000 | "months" => value_literal * 2628000_f64 |
y |
数值 × 31,536,000 | "years" => value_literal * 31536000_f64 |
其中 2,628,000 = 31,536,000 ÷ 12,即"1 年 = 365 天,1 月 = 年 ÷ 12"。最终生成的 AST 等价于 duration.fromSeconds(value) 的调用表达式(源码注释也直接写明 "represent duration literals as the AST equivalent of duration.fromSeconds(value)")。也就是说,字面量只是语法糖,统一语义锚点是"秒"。
SDK 实现:Duration 类的七个工厂与七个只读属性
在标准库源码 packages/@winglang/sdk/src/std/duration.ts 中,Duration 类实现了 ILiftable 接口,其设计非常精简:
- 内部只存一个字段
seconds: number,所有单位换算都由它派生; - 构造函数是私有的(
private constructor(seconds: number)),外部只能通过 7 个静态工厂方法创建实例; - 7 个静态工厂:
fromMilliseconds(amount)、fromSeconds(amount)、fromMinutes(amount)、fromHours(amount)、fromDays(amount)、fromMonths(amount)、fromYears(amount),每个都返回以秒为内部表示的Duration; - 7 个只读属性(getter):
milliseconds、seconds、minutes、hours、days、months、years,用于把任意 duration 换算到目标单位。
换算实现(即 getter 的推导链):
| 属性 | 公式 | 说明 |
|---|---|---|
milliseconds |
seconds * 1000 |
秒 → 毫秒 |
seconds |
内部字段 | 秒是基准单位 |
minutes |
seconds / 60 |
|
hours |
minutes / 60 |
即 seconds / 3600 |
days |
hours / 24 |
即 seconds / 86400 |
months |
years * 12 |
先换算为年再乘 12 |
years |
days / 365 |
即 seconds / 31536000 |
注意 months 与 years 的换算关系:years = days / 365,months = years * 12,因此 1 月严格等于 31,536,000 / 12 = 2,628,000 秒,与编译器降级系数完全一致——这正是快照测试能够全部通过的前提:语法层(wingc)与运行时层(SDK)必须使用同一套换算系数。
此外,Duration 还实现了 _toInflight() 方法,在生成 inflight 代码时通过 require(...).Duration(seconds) 重建对象,从而兑现语言参考中"可跨 inflight 上下文引用"的承诺。
测试源码逐段解读:快照背后的 80+ 条断言
hangar 快照的 pass 结果来自 tests/sdk_tests/std/duration.test.w 中大量 assert。该文件分为两部分:文件顶层的 preflight 断言,以及 test "duration" 用例内的断言。按主题可归纳为以下几组:
1. 字面量到秒的换算
覆盖全部七个后缀与预飞阶段:
assert(12ms.seconds == 12 / 1000);
assert(12s.seconds == 12);
assert(12m.seconds == 12 * 60);
assert(12h.seconds == 12 * 60 * 60);
assert(12d.seconds == 12 * 60 * 60 * 24);
assert(12mo.seconds == (12 * 60 * 60 * 24 * 365) / 12);
assert(12y.seconds == 12 * 60 * 60 * 24 * 365);
2. 工厂方法与字面量的等价性
duration.fromX(10) 必须与 10X 字面量完全一致,例如 duration.fromMilliseconds(10).seconds == 10ms.seconds、duration.fromMonths(10).seconds == 10mo.seconds、duration.fromYears(10).seconds == 10y.seconds。这条约束保证了"工厂创建"与"字面量创建"两条路径殊途同归。
3. 1 秒在各单位下的值
assert(1s.milliseconds == 1000);
assert(1s.minutes == 1 / 60);
assert(1s.hours == 1 / (60 * 60));
assert(1s.days == 1 / (60 * 60 * 24));
assert(1s.months == 1 / ((60 * 60 * 24 * 365) / 12));
assert(1s.years == 1 / (60 * 60 * 24 * 365));
4. 单位间等价关系
这是理解"大单位"换算的关键断言组:
assert(1s == 1000ms);
assert(60s == 1m);
assert(60m == 1h);
assert(24h == 1d);
assert(365d == 1y);
assert(12mo == 1y);
assert(3600s == 1h);
assert(86400s == 1d);
assert(31536000s == 1y);
5. 从任一基准单位向全单位换算
测试对 fromMilliseconds(1000)、fromSeconds(60)、fromMinutes(60)、fromHours(24)、fromDays(365)、fromMonths(12)、fromYears(1) 分别验证其换算到其余所有单位的结果,例如:
assert(duration.fromHours(24).milliseconds == 24h.milliseconds);
assert(duration.fromHours(24).days == 1);
assert(duration.fromDays(365).months == 12);
assert(duration.fromDays(365).years == 1);
assert(duration.fromMonths(12).years == 1);
6. 负值与零值
duration 支持负数与零:-12m.seconds == -12 * 60、-12mo.seconds == (-12 * 60 * 60 * 24 * 365) / 12,以及 0ms.seconds == 0、0y.seconds == 0 等。这说明换算对任意数值(含负数、零、小数)都成立,而不仅仅针对正整数值。
7. API 参考中的完整方法签名
标准库 API 文档 docs/api/04-standard-library/std/duration.md 给出了每个方法的完整签名与参数类型,例如:
duration.fromDays(amount: num);
duration.fromHours(amount: num);
duration.fromMilliseconds(amount: num);
duration.fromMinutes(amount: num);
duration.fromMonths(amount: num);
duration.fromSeconds(amount: num);
duration.fromYears(amount: num);
所有工厂方法的参数 amount 类型均为 num(对应 SDK 源码中的 number),且为必填参数;全部属性(days/hours/milliseconds/minutes/months/seconds/years)的类型也都是 num。
实战示例:用 duration 做跨单位计算
官方 by-example 文档 docs/by-example/37-duration.md 提供了一个可直接运行于 Wing Console 的完整示例:
let msInHour = duration.fromHours(1).milliseconds;
let msInSeconds = duration.fromSeconds(30).milliseconds;
let secondsInDay = duration.fromDays(1).seconds;
let hoursInDay = duration.fromDays(1).hours;
let hoursInMonth = duration.fromMonths(1).hours;
let daysInYear = duration.fromYears(1).days;
let durations = {
msInHour,
msInSeconds,
secondsInDay,
hoursInDay,
hoursInMonth,
daysInYear
};
log(Json.stringify(durations));
在 Wing Console 中本地运行(wing console)的输出为:
{"msInHour":3600000,"msInSeconds":30000,"secondsInDay":86400,"hoursInDay":24,"hoursInMonth":730,"daysInYear":365}
这些数字可以直接用前面推导的公式验证:fromHours(1).milliseconds = 1*3600*1000 = 3,600,000;fromMonths(1).hours = 2,628,000 / 3600 = 730;fromYears(1).days = 365。duration 非常适合用于云场景中的超时(timeout)、重试间隔、调度周期等配置,例如队列/函数的 timeout 参数、定时任务周期等。
相等性规则与已知边界
语言参考 docs/api/05-language-reference.md 的相等性章节指出:两个 duration 值相等当且仅当它们拥有相同的毫秒数("Two duration values are equal if they have the same number of milliseconds")。这与 SDK 以秒为内部基准、毫秒由秒派生的设计自洽——换算到毫秒后比较即可判定等价(例如 1s == 1000ms、60m == 1h 这类断言本质上就是在验证这一点)。
同时文档附有一则注意:duration 的相等性检查尚未完全实现,详见仓库历史 issue #2941 的追踪。因此在涉及 duration 相等性比较的代码中,应留意这一已知边界,优先使用换算后的数值比较而非直接依赖语言内置相等语义。
如何查看与复现这套验证
- 阅读快照:本仓库的 test_corpus/sdk_tests/std/ 目录下按
*.test.w_test_sim.md(sim 运行结果)与*.test.w_compile_tf-aws.md(tf-aws 编译产物)两种维度组织快照,duration与array、bool、json、string等标准库类型并列; - 复现测试:
duration.test.w属于 tests/sdk_tests/std/ 标准库测试集,可通过项目根目录 package.json 与 pnpm-workspace.yaml 中定义的 workspace 脚本,结合 hangar(位于 tools/hangar/)在本地运行;duration.test.w在 sim 目标下应得到Tests 1 passed (1)的结果,编译到 tf-aws 目标则产生不含云资源的空 Terraform 栈; - 深入源码:字面量语法在 wingc/src/parser.rs 的
build_duration中实现,运行时换算在 sdk/src/std/duration.ts 中实现,两层系数完全一致,这是快照稳定通过的根本保证。
小结
duration 是 Wing 中一个"小而完整"的内置类型:语法层用七种字面量后缀降低表达成本,编译器统一降级为 fromSeconds 调用,SDK 以秒为唯一内部基准派生全部单位,测试层用 80+ 条断言覆盖正数、负数、零以及全单位交叉换算。而 hangar 快照文档则把这一切固化为可自动比对的结果——duration.test.w 在 sim 目标的 pass 与 tf-aws 目标的空栈产物,共同证明了该类型在语言、运行时与云编译目标三层的稳定一致。对于要在云函数超时、调度周期、重试窗口等场景使用时间单位的开发者来说,掌握 duration 的换算规则与工厂方法,就能写出更精确、可验证的 Wing 代码。