Duration(时长)是 Wing 语言标准库中用于表达"一段时间长度"的核心内建类型。无论是云函数超时(timeout)、定时任务触发频率(schedule.rate)、inflight 代码中的 util.sleep,还是轮询重试间隔(util.waitUntil),底层都以 std.Duration 为统一度量单位。本文以仓库中的 duration 单元测试(tests/sdk_tests/std/duration.test.w)及其 tf-aws 编译快照(tools/hangar/snapshots/test_corpus/sdk_tests/std/duration.test.w_compile_tf-aws.md)为主线,结合 SDK 实现与编译器源码,系统讲解 Duration 的字面量语法、七个工厂方法、七个单位属性、负值与零值的边界行为,以及它在 preflight/inflight 阶段的编译与序列化原理。读完本文,你将能够在自己的 Wing 代码中熟练写出无歧义的时间表达式,并理解为什么一个纯数据类型的测试在 tf-aws 平台下编译出的 Terraform 配置如此"干净"。
timeout
schedule.rate
util.sleep
util.waitUntil
std.Duration
duration
tf-aws
本次研讨的关联文档是 hangar 测试框架为 duration.test.w 在 tf-aws 平台下生成的编译快照,全文如下:
duration.test.w
# duration.test.w | compile | tf-aws ## main.tf.json { "//": { "metadata": { "backend": "local", "stackName": "root" }, "outputs": {} }, "provider": { "aws": [ {} ] } }
这份快照看似"空",实际蕴含三条关键信息:
std
main.tf.json
provider
resource
data
output
assert
test
这份 Markdown 快照并非手写文档,而是由仓库中的测试基建 hangar 自动产出:
compileTest
wing compile
.wing
preflight.
inflight.
extern/
proc
.Struct.js
createMarkdownSnapshot
# <源文件> | compile | tf-aws
__snapshots__/test_corpus/...
.md
toMatchFileSnapshot
因此,快照中记录的 main.tf.json 内容就是 wing compile -t tf-aws 对 duration.test.w 的真实编译产物。可以这样在本地复现:
wing compile -t tf-aws
wing compile -t tf-aws tests/sdk_tests/std/duration.test.w
说明:wing CLI 是 Wing 工具链的编译与运行入口,-t tf-aws 指定目标平台为 AWS(Terraform 引擎)。若只做语法与类型检查而不生成产物,可省略平台参数。
wing
-t tf-aws
在展开字面量与换算规则之前,先看 Duration 在 SDK 中的实现,这是理解一切换算公式的钥匙。核心类定义在 packages/@winglang/sdk/src/std/duration.ts:
export class Duration implements ILiftable { public readonly seconds: number; private constructor(seconds: number) { this.seconds = seconds; } public static fromYears(amount: number): Duration { return new Duration(amount * 60 * 60 * 24 * 365); } public static fromMonths(amount: number): Duration { return new Duration((amount * 60 * 60 * 24 * 365) / 12); } public static fromDays(amount: number): Duration { return new Duration(amount * 60 * 60 * 24); } public static fromHours(amount: number): Duration { return new Duration(amount * 60 * 60); } public static fromMinutes(amount: number): Duration { return new Duration(amount * 60); } public static fromSeconds(amount: number): Duration { return new Duration(amount); } public static fromMilliseconds(amount: number): Duration { return new Duration(amount / 1000); } public get milliseconds() { return this.seconds * 1000; } public get minutes() { return this.seconds / 60; } public get hours() { return this.minutes / 60; } public get days() { return this.hours / 24; } public get months() { return this.years * 12; } public get years() { return this.days / 365; } }
由此可以提炼出 Duration 的四个设计事实:
seconds: number
new Duration()
fromXxx(amount)
amount
seconds
fromMilliseconds
milliseconds/minutes/hours/days/months/years
months
years * 12
years
days / 365
ILiftable
ms
fromMilliseconds(x)
x / 1000
s
fromSeconds(x)
x
m
fromMinutes(x)
x * 60
h
fromHours(x)
x * 3600
d
fromDays(x)
x * 86400
mo
fromMonths(x)
x * 2628000
y
fromYears(x)
x * 31536000
注意这里的月被固定为 365 天 ÷ 12 ≈ 30.42 天,年被固定为 365 天,不随自然月的天数或闰年变化。这是 Duration 与日历语义(如 std.Datetime)的本质区别:Duration 只是数学意义上的时间长度,不涉及日历位置。
365 天 ÷ 12 ≈ 30.42 天
365 天
std.Datetime
12ms
12mo
Wing 为 Duration 提供了语法糖——带单位后缀的数字字面量。测试用例开篇即覆盖了全部七种后缀:
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); // 年
这些后缀的合法形态由语言文法定死。在 packages/@winglang/tree-sitter-wing/grammar.js 中:
duration: ($) => choice( $.milliseconds, $.seconds, $.minutes, $.hours, $.days, $.months, $.years ), milliseconds: ($) => seq(field("value", $.number), "ms"), seconds: ($) => seq(field("value", $.number), "s"), minutes: ($) => seq(field("value", $.number), "m"), hours: ($) => seq(field("value", $.number), "h"), days: ($) => seq(field("value", $.number), "d"), months: ($) => seq(field("value", $.number), "mo"), years: ($) => seq(field("value", $.number), "y"),
要点:
12m
literal
string
number
bool
nil_value
duration.fromSeconds
build_duration 负责把带单位的字面量翻译为 AST 调用(见 packages/@winglang/wingc/src/parser.rs):
build_duration
let seconds = match value.kind() { "milliseconds" => value_literal / 1000_f64, "seconds" => value_literal, "minutes" => value_literal * 60_f64, "hours" => value_literal * 3600_f64, "days" => value_literal * 86400_f64, "months" => value_literal * 2628000_f64, "years" => value_literal * 31536000_f64, ... }; // 注释原文:represent duration literals as the AST equivalent of `duration.fromSeconds(value)`
这段代码揭示了一个关键实现细节:所有 Duration 字面量在解析阶段都被统一规约为 duration.fromSeconds(秒数) 调用——即 12ms 变成 duration.fromSeconds(0.012),12mo 变成 duration.fromSeconds(2628000 * 12)。这与 SDK 内部"以秒为唯一存储"的设计完全一致:字面量、工厂方法、内部存储三者共用同一换算基准。duration 本身作为 std 命名空间的全局符号,在 wingc 中以 WINGSDK_DURATION = "std.Duration" 形式登记(见 packages/@winglang/wingc/src/lib.rs)。
duration.fromSeconds(秒数)
duration.fromSeconds(0.012)
duration.fromSeconds(2628000 * 12)
wingc
WINGSDK_DURATION = "std.Duration"
同时,duration 是 Wing 的合法类型注解关键字(与 num、str、bool 等同级),在 packages/@winglang/wingc/src/parser.rs 中解析为 TypeAnnotationKind::Duration,在编译输出中映射为 std.reflect.Type._ofDuration()(见 packages/@winglang/wingc/src/jsify.rs 与 L2332-L2333)。因此可以写出:
num
str
TypeAnnotationKind::Duration
std.reflect.Type._ofDuration()
let timeout: duration = 30s; // 显式注解 + 字面量 let halfSecond: duration = duration.fromMilliseconds(500);
duration.fromXxx
SDK 文档 docs/api/04-standard-library/std/duration.md 列出了 Duration 的全部静态工厂方法,API 签名统一为 duration.fromXxx(amount: num):
Duration
duration.fromXxx(amount: num)
duration.fromMilliseconds(amount: num)
amount / 1000
fromSeconds
duration.fromSeconds(amount: num)
fromMinutes
duration.fromMinutes(amount: num)
amount * 60
fromHours
duration.fromHours(amount: num)
amount * 3600
fromDays
duration.fromDays(amount: num)
amount * 86400
fromMonths
duration.fromMonths(amount: num)
amount * 2628000
fromYears
duration.fromYears(amount: num)
amount * 31536000
测试用例验证了工厂方法与字面量的等价性:
assert(duration.fromMilliseconds(10).seconds == 10ms.seconds); assert(duration.fromMinutes(10).seconds == 10m.seconds); assert(duration.fromSeconds(10).seconds == 10s.seconds); assert(duration.fromHours(10).seconds == 10h.seconds); assert(duration.fromDays(10).seconds == 10d.seconds); assert(duration.fromMonths(10).seconds == 10mo.seconds); assert(duration.fromYears(10).seconds == 10y.seconds);
由于字面量在编译器内部就被规约为 duration.fromSeconds,而工厂方法最终同样归一到 seconds 字段,因此 10m.seconds == duration.fromMinutes(10).seconds 是必然成立的——两条路径殊途同归。
10m.seconds == duration.fromMinutes(10).seconds
duration.seconds
duration.years
Duration 暴露 7 个只读属性,全部为 num 类型,语义是"把这个 Duration 折算成某单位后的总数值":
milliseconds
seconds * 1000
minutes
seconds / 60
hours
minutes / 60
days
hours / 24
测试以 1s 为基准验证了反方向的换算:
1s
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));
测试进一步用"从某单位出发换算到全部其他单位"的方式,对换算链做了穷尽式验证。以天为例:
// 从 days 出发换算到全部单位 assert(duration.fromDays(365).milliseconds == 365d.milliseconds); assert(duration.fromDays(365).seconds == 365d.seconds); assert(duration.fromDays(365).minutes == 365d.minutes); assert(duration.fromDays(365).hours == 365d.hours); assert(duration.fromDays(365).months == 12); // 365 天 = 12 个月 assert(duration.fromDays(365).years == 1); // 365 天 = 1 年
同理还有从 milliseconds(1000)、seconds(60)、minutes(60)、hours(24)、months(12)、years(1) 出发的全量换算断言(见 tests/sdk_tests/std/duration.test.w)。这些断言共同锁定了一个事实:无论从哪个单位进入,只要秒数相同,任意单位属性输出都相同,换算链是自洽且可逆的。
milliseconds(1000)
seconds(60)
minutes(60)
hours(24)
months(12)
years(1)
test "duration" 块中还有一组"单位等价"断言,直接验证了常用的时间等式:
test "duration"
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);
1s == 1000ms 成立是因为两边都被规约为相同的秒数(1 与 1000/1000);12mo == 1y 成立是因为 mo 的秒数常数 2628000 = 31536000 / 12 恰好使 12 个月等于 1 年。这里能直接使用 == 比较两个 Duration,说明 Duration 的相等性基于其内部秒数值。
1s == 1000ms
12mo == 1y
2628000 = 31536000 / 12
==
Duration 的换算公式是纯算术运算,因此天然支持负数和零。测试专门覆盖了这两类边界:
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); assert(duration.fromMilliseconds(-10).seconds == -10ms.seconds); assert(duration.fromMinutes(-10).seconds == -10m.seconds); // ... 其余单位同理
负号可以出现在字面量数字上(-12ms),也可以传给工厂方法(duration.fromMinutes(-10)),两者结果一致。
-12ms
duration.fromMinutes(-10)
assert(0ms.seconds == 0); assert(0s.seconds == 0); assert(0m.seconds == 0); assert(0h.seconds == 0); assert(0d.seconds == 0); assert(0mo.seconds == 0); assert(0y.seconds == 0); assert(duration.fromMilliseconds(0).seconds == 0ms.seconds); // ... 其余单位同理
无论从哪个单位构造,零值最终都是 0 秒。从 SDK 实现看,负数、零之所以能正常工作,是因为所有换算只是 number 上的乘除运算,SDK 层对数值范围没有做任何限制;真正的取值范围约束发生在使用方(例如 cloud.Schedule 要求 rate.seconds >= 60,见下文第七节)。
0
cloud.Schedule
rate.seconds >= 60
Duration 不是孤立的数据类型,它是 Wing 云原语 API 的公共"度量衡"。以下用法都能在 SDK 源码中找到实证。
cloud.Schedule.rate
packages/@winglang/sdk/src/cloud/schedule.ts 中 ScheduleProps.rate 的类型就是 Duration:
ScheduleProps.rate
export interface ScheduleProps { /** * Trigger events at a periodic rate. * @example 1m */ readonly rate?: Duration; readonly cron?: string; }
构造器对 rate 做了分钟级下限校验(见 packages/@winglang/sdk/src/cloud/schedule.ts):
rate
if (rate && rate.seconds < 60) { throw new Error("rate can not be set to less than 1 minute."); }
也就是说 new cloud.Schedule(this, "s", { rate: 30s }) 会在运行时抛错,而 { rate: 1m } 合法——校验直接读取 Duration 的 seconds 属性,这正是"以秒为内部存储"带来的便利。
new cloud.Schedule(this, "s", { rate: 30s })
{ rate: 1m }
packages/@winglang/sdk/src/util/util.ts 定义了 inflight 阶段的休眠 API:
public static async sleep(delay: Duration): Promise<void> { ... }
配合 docs/by-example/20-sleep.md 的示例:
bring util; bring cloud; // util.sleep 是 inflight API,preflight 代码中不可使用 inflight () => { util.sleep(40s); }; let longTask = new cloud.Function(inflight () => { util.sleep(5s); });
同一文件中的 WaitUntilProps(packages/@winglang/sdk/src/util/util.ts)用 Duration 表达超时与重试间隔:
WaitUntilProps
export interface WaitUntilProps { /** 持续尝试 predicate 的超时时间,默认 1m */ readonly timeout?: Duration; /** predicate 重试之间的间隔,默认 0.1s */ readonly interval?: Duration; readonly throws?: boolean; }
对应默认值(packages/@winglang/sdk/src/util/util.ts):
const timeout = props.timeout ?? Duration.fromMinutes(1); const interval = props.interval ?? Duration.fromSeconds(0.1);
Duration 还被广泛用于 cloud.Function 的 timeout、队列与容器的相关配置等场景,例如 packages/@winglang/sdk/src/target-tf-aws/queue.ts、packages/@winglang/sdk/src/target-sim/queue.ts 与 packages/@winglang/sdk/src/target-sim/container.inflight.ts 都引用了 duration 相关工厂方法。也就是说:只要 Wing API 的某个配置项是"时间长度",它的类型几乎都是 Duration,掌握本文的换算规则即可正确传参。
cloud.Function
docs/by-example/37-duration.md 给出了一个可直接运行的综合示例,覆盖了"从大单位取小单位"的实际诉求:
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 中的输出为:
{"msInHour":3600000,"msInSeconds":30000,"secondsInDay":86400,"hoursInDay":24,"hoursInMonth":730,"daysInYear":365}
注意 hoursInMonth 是 730——这正是"月 = 365/12 天"的实证:1mo = 2628000 秒 = 730 小时。
hoursInMonth
730
1mo = 2628000 秒 = 730 小时
结合以上全部机制,可以完整解读开头那份快照的含义:
test "duration" { ... }
testTest
sim
_test_sim
provider.aws
//
这份快照也因此承担着双重职责:作为回归测试,它锁定"Duration 测试在 tf-aws 下编译通过且无资源泄漏"的稳定行为;作为文档,它向读者展示了"纯数值/纯类型测试"在 Wing 编译体系中的真实产物形态。
n / 1000
n
n * 60
n * 3600
n * 86400
n * 2628000
n * 31536000
60s == 1m
60m == 1h
24h == 1d
365d == 1y
3600s == 1h
86400s == 1d
31536000s == 1y
seconds * 1000 = milliseconds
seconds / 60 = minutes
minutes / 60 = hours
hours / 24 = days
days / 365 = years
years * 12 = months