Spring定时任务之fixedRateString的实现示例_Java

在 spring framework 的开发中，@scheduled 注解是我们实现定时任务的利器。其中，fixedratestring 属性允许我们通过字符串来配置任务执行的固定速率。从 spring 5 开始，为了更好地支持 java 8 的日期时间 api，fixedratestring（以及 fixeddelaystring, initialdelaystring）开始支持 java.time.duration 的格式进行解析。

这为我们提供了比毫秒数字更优雅、更易读的配置方式。今天，我们就来深入探讨一下这个强大的功能。

从毫秒到 duration：为何要改变？

在旧版本中，我们通常这样配置：

@scheduled(fixedrate = 5000) // 每5秒执行一次
public void dotask() {
    // 任务逻辑
}

或者使用字符串形式（为了支持占位符）：

@scheduled(fixedratestring = "5000") // 从配置文件中读取，例如：scheduled.rate=5000
public void dotask() {
    // 任务逻辑
}

这种方式虽然直接，但可读性较差。看到 5000，你需要反应一下才知道是 5 秒。而 duration 格式则一目了然：

@scheduled(fixedratestring = "pt5s") // 清晰明了：period of time 5 seconds
public void dotask() {
    // 任务逻辑
}

核心：java.time.duration.parse 支持的格式

spring 底层使用 java.time.duration.parse(charsequence) 方法来解析 fixedratestring 的值。该方法遵循 iso-8601 持续时间格式。

其正则表达式定义如下： ([-+]?)p(?:([-+]?[0-9]+)d)?(t(?:([-+]?[0-9]+)h)?(?:([-+]?[0-9]+)m)?(?:([-+]?[0-9]+)(?:[.,]([0-9]{0,9}))?s)?)?

看起来复杂，但其结构非常清晰，可以分解为：

基本结构： p[n]y[n]m[n]w[n]d[t[n]h[n]m[n]s]]

p (必需): 是“period”的缩写，表示持续时间段的开始。
t (可选): 是“time”的缩写，用于分隔日期部分和时间部分。如果要指定小时、分钟或秒，则必须有 t。

日期部分 (在 p 之后，t 之前)：

y - 年
m - 月
w - 周
d - 天

时间部分 (在 t 之后)：

h - 小时
m - 分钟
s - 秒 (可以包含小数，使用 . 或 , 分隔，例如 pt30.5s 是 30.5 秒)

重要提示：对于 duration 类型，它主要用于衡量精确的时间段，而不是用于基于日历的、不精确的时间段。因此，在解析时，年（y） 和 月（m） 会被忽略（一个月的天数不固定，无法精确转换为 duration）。周（w） 和 天（d） 则会被正常转换（1天=24小时，1周=7天）。

这意味着，虽然格式允许 y 和 m，但在 duration 的语境下，它们是没有意义的。你应该专注于使用 d, h, m, s。

实战示例

让我们看一些在 @scheduled 中有效的配置示例：

5 秒: pt5s
30 分钟: pt30m 或 pt1800s
2 小时: pt2h
2 小时 30 分钟: pt2h30m
1 天: p1d (相当于 pt24h)
1 天 6 小时: p1dt6h
1.5 秒 (1500毫秒): pt1.5s

从配置文件读取:

application.properties:

my.task.rate=pt10s
my.task.delay=p1dt12h

java code:

@scheduled(fixedratestring = "${my.task.rate}", initialdelaystring = "${my.task.delay}")
public void doscheduledtask() {
    // 应用启动后，先延迟 1天半 (36小时)，然后每10秒执行一次
}

常见错误与陷阱

忘记 t 分隔符：
- 错误: p1h30m (试图在日期部分指定小时)
- 正确: pt1h30m (必须用 t 引入时间部分)
使用 y 或 m：
- 无效: p1m (期望是1个月，但实际会被解析为 0)
- 无效: p1y1m (年份和月份都会被忽略，解析结果也是 0)
- 如果需要“大约一个月”这种基于日历的概念，duration 不是正确的工具，应考虑 cron 表达式。
负值：格式支持负值（-pt5s），但这在调度场景中没有意义，会导致异常。