定时事件接口规范 0.1.0

本包让应用在定时事件（cron 触发）里读取触发这次调用的 cron 表达式和计划时刻。读取定时事件 只在当前事件是定时事件时可用，也就是[网页入站接口](../网页入站/规范.汉语.md)的 读取入站事件种类 返回 scheduled；应用据此选择自己的定时处理入口。返回 JSON 文字，形如 {"cron":"*/10 * * * *","scheduledTime":1758801600000}。cron 是触发这次调用的 cron 表达式原文；scheduledTime 是平台约定的计划触发时刻，Unix 毫秒整数（自 1970-01-01T00:00:00Z 起），可能早于程序实际开始运行的时刻；手动或测试触发时平台可以给出触发的那一瞬。整数按十进制原文交给应用，不经过浮点。在其他事件里调用（例如普通 HTTP 请求）会失败，并抛出可用「尝试运行」捕获的豫言异常，不是宿主故障。

事件寿命

定时事件的寿命等于豫言程序的一次运行：宿主让平台的定时调用一直等到程序运行结束（等待同时交给 waitUntil），应用在入口内做完的全部工作，包括等待外部请求和写存储，都算在同一次定时调用之内；程序返回后这次调用即告结束，平台可以回收尚未完成的后台工作。程序抛出未捕获的豫言异常时，这次定时调用被平台记为失败，是否重试由平台的定时策略决定，本接口不提供 noRetry。定时事件里没有 HTTP 响应，应用不得调用网页答复包的函数。应用不应假定同一计划时刻只会被投递一次，需要幂等时自行保证。

一致性样例

| 情境 | 必须观察到 | | --- | --- | | cron 为 */10 * * * *，计划时刻 1758801600000 | 返回的 JSON 解析后 cron 相等，scheduledTime 是整数 1758801600000 | | 计划时刻为 0 或 8640000000000000 | 整数原样返回，不出现小数点或指数 | | cron 含双引号、反斜线 | JSON 转义后可无损解析回原文 | | 在普通 HTTP 请求里调用 | 抛出可捕获的豫言异常，消息说明当前事件不是定时事件 | | 程序在定时事件里等待一次异步写入后返回 | 定时调用在写入完成之后才结束 | | 程序在定时事件里抛出未捕获异常 | 定时调用失败，异常不被宿主吞掉 |

边界

本包不解析 cron 表达式，不枚举部署的 cron 清单，不承诺计划时刻与实际执行时刻的间隔，也不提供 noRetry、重试计数或同一计划时刻的去重。云工适配把 scheduled 事件映射到本接口；其他平台可以用等价的定时器实现，只要 cron 与 scheduledTime 的含义和事件寿命一致。