Wing 语言中的 Duration 时间类型:字面量、工厂方法、单位换算与 tf-aws 编译全解析

原创2026-10-14 09:32:501,680 阅读
文章标签:编程语言编译器云原生语言运行时

Wing 语言中的 Duration 时间类型:字面量、工厂方法、单位换算与 tf-aws 编译全解析

Wing 语言中的 Duration 时间类型:字面量、工厂方法、单位换算与 tf-aws 编译全解析

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 配置如此"干净"。

一、快照文档说明了什么

本次研讨的关联文档是 hangar 测试框架为 duration.test.w 在 tf-aws 平台下生成的编译快照,全文如下:

# duration.test.w | compile | tf-aws

## main.tf.json
{
  "//": {
    "metadata": {
      "backend": "local",
      "stackName": "root"
    },
    "outputs": {}
  },
  "provider": {
    "aws": [
      {}
    ]
  }
}

这份快照看似"空",实际蕴含三条关键信息:

  1. 测试来源:被编译的源码是 tests/sdk_tests/std/duration.test.w,它是 SDK 标准库在 std 命名空间下的行为测试之一。
  2. 编译目标:tf-aws,即通过 CDKTF 生成 Terraform 配置,输出文件为 main.tf.json。
  3. 结果形态:main.tf.json 中只有 provider(AWS provider 空配置)和元数据,没有任何 resource、data、output 块——因为 duration.test.w 只在 preflight 阶段执行纯数值断言(assert),并声明了一个名为 duration 的 test 块,没有创建任何云资源,因此不会产生任何 Terraform 资源。

快照由 hangar 自动生成

这份 Markdown 快照并非手写文档,而是由仓库中的测试基建 hangar 自动产出:

  • compileTest(见 tools/hangar/src/generated_test_targets.ts)在临时目录中以 tf-aws 平台执行 wing compile,然后把产物目录中的 main.tf.json 与 .wing 目录下匹配 preflight.、inflight.、extern/、proc、.Struct.js 的文件收集成文件映射。
  • createMarkdownSnapshot(见 tools/hangar/src/utils.ts)将文件映射序列化为 # <源文件> | compile | tf-aws 的标题格式,并把每个文件以对应扩展名的代码块写入 __snapshots__/test_corpus/... 下的 .md 快照文件,再通过 toMatchFileSnapshot 与既有快照比对。

因此,快照中记录的 main.tf.json 内容就是 wing compile -t tf-aws 对 duration.test.w 的真实编译产物。可以这样在本地复现:

wing compile -t tf-aws tests/sdk_tests/std/duration.test.w

说明:wing CLI 是 Wing 工具链的编译与运行入口,-t tf-aws 指定目标平台为 AWS(Terraform 引擎)。若只做语法与类型检查而不生成产物,可省略平台参数。

二、Duration 的本质:以秒为唯一内部存储

在展开字面量与换算规则之前,先看 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 的四个设计事实:

  1. 单字段存储:内部只保存 seconds: number,构造器是私有的,唯一入口是七个静态工厂方法,杜绝了直接 new Duration() 的滥用。
  2. 工厂方法本质是换算:fromXxx(amount) 只是把 amount 乘以对应的秒数常数再存入 seconds。唯一的例外是 fromMilliseconds,它做的是除以 1000 的换算。
  3. 属性本质是反换算:milliseconds/minutes/hours/days/months/years 全部由 seconds 派生,其中 months 通过 years * 12 计算、years 通过 days / 365 计算,形成闭合换算链。
  4. 实现 ILiftable:Duration 实现了 ILiftable 接口(定义于 packages/@winglang/sdk/src/std/resource.ts),说明它可被 lift 到 inflight 环境,这是它能在 preflight 与 inflight 两个阶段间传递的前提。

各单位的秒数常数

单位 秒数常数 换算公式
毫秒 ms 1/1000 秒 fromMilliseconds(x) → x / 1000
秒 s 1 秒 fromSeconds(x) → x
分钟 m 60 秒 fromMinutes(x) → x * 60
小时 h 3600 秒 fromHours(x) → x * 3600
天 d 86400 秒 fromDays(x) → x * 86400
月 mo 2628000 秒(365 天/12) fromMonths(x) → x * 2628000
年 y 31536000 秒(365 天) fromYears(x) → x * 31536000

注意这里的月被固定为 365 天 ÷ 12 ≈ 30.42 天,年被固定为 365 天,不随自然月的天数或闰年变化。这是 Duration 与日历语义(如 std.Datetime)的本质区别:Duration 只是数学意义上的时间长度,不涉及日历位置。

三、字面量语法: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); // 年

语法定义来自 tree-sitter 文法

这些后缀的合法形态由语言文法定死。在 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"),

要点:

  • 后缀必须紧贴数字(12ms),ms、s、m、h、d、mo、y 是唯一合法后缀;
  • 12m 是 12 分钟(month 的缩写是 mo,不存在歧义);
  • 字面量出现在文法中 literal 的位置(与 string、number、bool、nil_value 并列),说明它是一等公民表达式。

编译器如何把它翻译成 duration.fromSeconds

build_duration 负责把带单位的字面量翻译为 AST 调用(见 packages/@winglang/wingc/src/parser.rs):

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 是 Wing 的合法类型注解关键字(与 num、str、bool 等同级),在 packages/@winglang/wingc/src/parser.rs 中解析为 TypeAnnotationKind::Duration,在编译输出中映射为 std.reflect.Type._ofDuration()(见 packages/@winglang/wingc/src/jsify.rs 与 L2332-L2333)。因此可以写出:

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):

方法 签名 说明 底层换算
fromMilliseconds duration.fromMilliseconds(amount: num) 以毫秒为单位创建 amount / 1000 秒
fromSeconds duration.fromSeconds(amount: num) 以秒为单位创建 amount 秒
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 是必然成立的——两条路径殊途同归。

五、七个只读属性:duration.seconds 到 duration.years

Duration 暴露 7 个只读属性,全部为 num 类型,语义是"把这个 Duration 折算成某单位后的总数值":

属性 类型 计算链
milliseconds num seconds * 1000
seconds num 内部存储本体
minutes num seconds / 60
hours num minutes / 60
days num hours / 24
months num years * 12
years num days / 365

测试以 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)。这些断言共同锁定了一个事实:无论从哪个单位进入,只要秒数相同,任意单位属性输出都相同,换算链是自洽且可逆的。

单位等价的恒等式

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 的相等性基于其内部秒数值。

六、边界行为:负值与零

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)),两者结果一致。

零值

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,见下文第七节)。

七、Duration 在真实云 API 中的落地用法

Duration 不是孤立的数据类型,它是 Wing 云原语 API 的公共"度量衡"。以下用法都能在 SDK 源码中找到实证。

1. 定时任务频率:cloud.Schedule.rate

packages/@winglang/sdk/src/cloud/schedule.ts 中 ScheduleProps.rate 的类型就是 Duration:

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):

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 属性,这正是"以秒为内部存储"带来的便利。

2. 休眠:util.sleep

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);
});

3. 轮询与超时:util.waitUntil

同一文件中的 WaitUntilProps(packages/@winglang/sdk/src/util/util.ts)用 Duration 表达超时与重试间隔:

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);

4. 云函数超时等(更多用法)

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,掌握本文的换算规则即可正确传参。

5. 官方 by-example 综合示例

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 小时。

八、回到快照:为什么 tf-aws 编译产物如此干净

结合以上全部机制,可以完整解读开头那份快照的含义:

  • duration.test.w 的所有断言都发生在 preflight 阶段:它们只是数值计算与比较,既不创建资源,也不触发 inflight 执行;
  • 文件中的 test "duration" { ... } 块声明了一个测试(在 Wing 中,test 块默认在模拟器/测试运行器中以 sim 平台执行,见 hangar 的 testTest 逻辑 tools/hangar/src/generated_test_targets.ts,它使用 sim 平台并生成 _test_sim 快照),因此在 tf-aws 编译视角下不产生任何基础设施;
  • 于是 wing compile -t tf-aws 只输出一个骨架 main.tf.json:provider.aws 空块(平台默认注入的 AWS provider 声明)、// 元数据(backend、stackName、outputs)。整个编译过程验证的是 Duration 相关的类型检查、字面量解析与 jsify 代码生成是否在 tf-aws 目标下正确通过。

这份快照也因此承担着双重职责:作为回归测试,它锁定"Duration 测试在 tf-aws 下编译通过且无资源泄漏"的稳定行为;作为文档,它向读者展示了"纯数值/纯类型测试"在 Wing 编译体系中的真实产物形态。

九、速查手册

字面量后缀

后缀 含义 秒数
ms 毫秒 n / 1000
s 秒 n
m 分钟 n * 60
h 小时 n * 3600
d 天 n * 86400
mo 月(365/12 天) n * 2628000
y 年(365 天) n * 31536000

常用恒等式

  • 1s == 1000ms、60s == 1m、60m == 1h、24h == 1d
  • 365d == 1y、12mo == 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

关键代码位置

登录后查看全文
wing