📚简介

CronUtil 是 Hutool-cron 模块提供的全局静态定时任务调度入口，其内部持有一个单例的 Scheduler 实例，适用于大多数简单到中等复杂度的单机定时任务场景。

⚠️ 注意： 本类适用于轻量级、非高并发隔离需求的场景； 若需多调度器隔离（如不同业务线任务互不影响），请直接使用 Scheduler 实例。

🍭特性

特性	说明
✅ 全局单例调度器	所有通过 CronUtil 添加的任务共享同一个 Scheduler
✅ 支持配置文件驱动	自动加载 config/cron.setting 或 cron.setting
✅ 秒级/分级 Cron 模式切换	通过 setMatchSecond() 控制表达式粒度
✅ 动态任务管理	支持运行时添加、移除、更新任务
✅ 线程模式可控	支持守护线程（isDaemon = true）或非守护线程启动
✅ 表达式校验	提供 isValidExpression() 静态校验方法

🔫使用

1. 分级定时任务

// 添加任务：每2分钟执行一次任务
CronUtil.schedule("*/2 * * * *", () -> Console.log("Task executed."));
// 启动调度器（非守护线程）
CronUtil.start();

⚠️ 注意： */2 * * * * 5位分别表示分 时 日 月 周，兼容Linux的crontab表达式。 测试时，需要在main方法中调用，或者在非守护线程中启动调度器，Junit单元测试中可以加上ThreadUtil.waitForDie()等待线程。

2. 秒级定时任务

考虑到Quartz和Spring等表达式的兼容性，且存在对于秒级别精度匹配的需求，Hutool可以通过设置使用秒匹配模式来兼容：

// 启用秒级匹配
CronUtil.setMatchSecond(true);

// 添加任务：每3秒打印一次
CronUtil.schedule("0/3 * * * * ?", () -> Console.log("Task executed."));
// 启动调度器（非守护线程）
CronUtil.start();

⚠️ 注意： 0/3 * * * * ? 6位分表表示秒 分 时 日 月 周，0/3表示从每分钟的0秒开始，每3秒执行一次

3、基于配置文件

对于Maven项目，首先在src/main/resources/config下放入cron.setting文件（默认是这个路径的这个文件），然后在文件中放入定时规则，规则如下：

# 我是注释
[com.company.aaa.job]
TestJob.run = */10 * * * *
TestJob2.run = */10 * * * *

中括号表示分组，也表示需要执行的类或对象方法所在包的名字，这种写法有利于区分不同业务的定时任务。

TestJob.run表示需要执行的类名和方法名（通过反射调用，不支持Spring和任何框架的依赖注入），*/10 * * * *表示定时任务表达式，此处表示每10分钟执行一次，以上配置等同于：

com.company.aaa.job.TestJob.run = */10 * * * *
com.company.aaa.job.TestJob2.run = */10 * * * *

然后只需启动定时任务即可：

CronUtil.start();

如果想让执行的作业和定时任务线程同时结束，可以将定时任务设为守护线程，需要注意的是，此模式下会在调用stop时立即结束所有作业线程，请确保你的作业可以被中断：

//使用deamon模式，
CronUtil.start(true);

4、关闭

CronUtil.stop();

自定义配置文件

默认的，CronUtil会从classpath的config/cron.setting或cron.setting加载配置文件，如果想自定义配置文件的路径和名称，可以使用如下方式：

// 方式1：传入 Setting 实例（已加载）
Setting mySetting = new Setting("my-cron.setting");
CronUtil.setCronSetting(mySetting);

// 方式2：传入配置文件路径（自动加载）
CronUtil.setCronSetting("custom/my-cron.setting");

⚠️ 注意： 配置文件和通过CronUtil.schedule方法动态加入的定时任务，都会被加载到全局调度器中，但是动态加入的任务不会被写入到配置文件中。

5、任务管理

方法	说明
schedule(String pattern, Task task)	添加任务，自动生成唯一ID，返回生成的 taskId（可用于后续管理）
schedule(String id, String pattern, Task task)	添加任务，指定任务ID，ID 重复时会覆盖原任务，推荐用于需动态更新的场景
schedule(Setting setting)	批量从 Setting 加载任务（内部使用，一般不直接调）
remove(String taskId)	移除指定ID任务，返回 true 表示成功移除；false 表示任务不存在
updatePattern(String id, CronPattern pattern)	动态修改调度规则，无需重启，实时生效，任务必须已存在

6、表达式校验

// 校验表达式是否合法，不区分秒级或分级模式
boolean isValid = CronUtil.isValidExpression("0/3 * * * * ?");
Console.log(isValid); // true

最佳实践

以下是您提供内容整理后的 Markdown 表格形式：

场景	建议
Web 应用	在 ServletContextListener.contextInitialized() 或 Spring 的 @PostConstruct 方法中调用 CronUtil.start()；在 contextDestroyed() 中调用 CronUtil.stop()
CLI 工具	启动后注册 JVM Shutdown Hook：Runtime.getRuntime().addShutdownHook(() -> CronUtil.stop());
任务 ID 管理	使用语义化 ID（如 "backup-db"），避免使用自动生成的 UUID，以提升可读性与可维护性