尧图网页设计 
Spring和Quartz这对组合我前前后后用了得有六七年。从最早的Spring 3 Quartz 1.8到后来的Spring Boot Quartz 2.3再到Quartz 3.x支持Spring Boot的starter一路踩坑一路填坑。现在提到定时任务很多人第一反应是Scheduled注解但一旦涉及到动态创建、任务持久化、集群部署Scheduled就完全不够用了。这篇文章我就把自己在实际项目中配置Spring Quartz的完整思路、配置细节和踩过的坑都整理出来给正好需要用这套方案的同行一个参考。我不打算把这篇文章写成那种规规矩矩的API文档更多是分享我在真实项目里怎么想、怎么配、为什么这么配的过程。无论你是刚接手老项目需要改定时任务的配置还是新项目要在Spring Boot里集成Quartz做动态任务调度这篇内容应该都能帮到你——尤其是那些文档里查不到、只有实际动手才会发现的细节。1. 为什么用Quartz而不是只用Scheduled先说一个最基础的问题为什么Spring已经有了Scheduled还要引入Quartz这个重量级调度框架很多初学者都问过我这个我的回答一般就一句话Scheduled解决的是固定死的周期任务Quartz解决的是会变化的、可以管理起来的任务。1.1 Scheduled的局限在哪Scheduled最大的优点是配置简单在方法上加个注解、写个cron表达式就能跑。但你真在项目里用起来就会发现几个绕不开的问题任务执行时间和频率是写死在代码里的。业务方说这个报表任务从每天早上八点改成晚上十点你得改代码重新发布。如果运营希望完全不经过开发就能调整任务时间Scheduled根本做不到。任务状态完全没有管理。任务上一次跑没跑成功下次什么时候跑哪个任务的触发时间是什么这些信息在你没有额外记录的情况下完全没有。顺便说一句Scheduled在Spring容器启动一个线程池执行如果任务执行时间超过了触发间隔它会等上一个任务执行完才触发下一次这在某些场景下是隐患。没有持久化。应用重启之后Scheduled的任务只是重新注册一遍历史执行记录、任务状态全都没有更不用提集群环境下的分布式协调。1.2 Quartz核心解决的问题Quartz把定时任务这件事抽象成了三个核心概念理解了这三个概念就理解了Quartz的大半JobDetail任务详情、Trigger触发器、Scheduler调度器。打个比方JobDetail就像是你写好的一张菜谱Trigger像是一个闹钟Scheduler就像是一个不断看着闹钟、时间一到就照着菜谱做菜的厨师。菜谱可以有很多张闹钟可以有很多个一个厨师可以同时看着很多闹钟一个闹钟响了就做对应的菜。JobDetail定义任务的类型和参数。你写一个类实现Quartz的Job接口这个类就是任务逻辑JobDetail则是这个任务逻辑在调度器里的注册信息可以附带参数。Trigger决定任务何时触发。最常用的是CronTrigger用cron表达式定义复杂的触发计划还有SimpleTrigger适合那种每隔多少秒执行一次的简单周期。Scheduler调度容器。JobDetail和Trigger都要注册到Scheduler里才能跑。Scheduler本身是一个独立组件有自己的生命周期可以启动、暂停、关闭。除了这三个概念Quartz真正比Scheduled强的地方在于Trigger可以被动态创建、修改、删除Job和Trigger的状态可以被持久化到数据库JobStore支持集群部署多个节点共享同一个调度状态任务执行可以记录到历史表里做审计。所以在项目里我一般的原则是如果只是极少数固定的内置任务比如凌晨清理临时文件这种用Scheduled就够但只要任务数量和变动频率上来了或者要接入运营配置、将来可能多机部署直接上Quartz省得后面重构。1.3 Spring整合Quartz的版本考量Spring Quartz的整合方式这些年有过几次明显变化。最初在Spring 3.x时代官方推荐用MethodInvokingJobDetailFactoryBean配合SimpleTriggerBean或CronTriggerBean在XML里配置。到了Spring 4、Spring Boot时代有了JobDetailFactoryBean和CronTriggerFactoryBean。而Quartz 2.3版本开始Spring Boot官方直接提供了spring-boot-starter-quartz模块自动配置了Scheduler、JobStore等基础组件我们只需要聚焦业务任务本身。这篇文章主要基于Spring Boot 2.x Quartz 2.3的方式写这类组合在目前的生产环境里最普及。后文我也会简单提及老项目的XML配置路径方便维护老系统的朋友有个对比参考。2. Spring Boot下Quartz的基础配置咱们直接动手。先说整体思路整合Spring Boot Quartz第一步是加依赖第二步是准备Job类第三步是配置JobDetail和Trigger的Bean第四步是确认Scheduler自动注册了这些Bean。就这四步跑通基础流程之后再去玩高级功能。2.1 引入依赖如果你的项目是Spring Boot 2.x直接用官方starter最省事dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-quartz/artifactId /dependency这个starter做了一件非常重要的事自动创建并配置一个SchedulerFactoryBean把它注册到Spring容器里。同时Spring Boot还自动为Quartz实例了一个调度线程池。你不需要自己手动定义SchedulerFactoryBean这一点和很多老教程里写的都不一样我见过不少同事用旧版的配置来Spring Boot项目里写一遍然后调度器重复初始化算是很典型的低级踩坑。如果用传统Spring非Boot项目要显式引入Quartz的jar。通常Maven坐标是这样的dependency groupIdorg.quartz-scheduler/groupId artifactIdquartz/artifactId version2.3.2/version /dependency再加上Spring上下文里自己声明SchedulerFactoryBean后面我会给出一个完整示例。2.2 写一个最普通的Job类定义了org.quartz.Job接口任务类要实现它的execute方法public class SampleJob implements Job { Override public void execute(JobExecutionContext context) throws JobExecutionException { System.out.println(定时任务执行了 LocalDateTime.now()); } }一个特别重要的细节Job类每次执行时都是Quartz通过反射new的新实例。不要指望任务类里有状态、Quartz会复用同一个对象不是的。execute方法里的局部变量、JobDataMap里取出来的参数、通过Spring容器注入的Service这些才是跨执行之间活下来的东西。如果你的Job类里要用Spring容器管理的Service最简单的方式是直接Autowired。Quartz虽然会new任务类的实例但Spring Boot的自动配置里给Scheduler设置了一个SpringBeanJobFactory实际上是SpringLink的JobFactory它会在实例化Job之后把Spring容器里的依赖注入进去。所以你的Job类可以直接写Component public class SampleJob implements Job { Autowired private ReportService reportService; Override public void execute(JobExecutionContext context) throws JobExecutionException { reportService.generateDailyReport(); } }注意两个前提Job类要能被Spring管理到。要么标Component交给Spring扫描要么在手动配置JobDetail时需要能在Spring容器里找到这个Bean。另外Job类得有public的无参构造方法Quartz反射创建实例才不会有问题。2.3 配置JobDetail和TriggerJob类写好了接下来就是把JobDetail和Trigger交给Spring容器管理。在Spring Boot里Configuration public class QuartzConfig { Bean public JobDetailFactoryBean sampleJobDetail() { JobDetailFactoryBean factoryBean new JobDetailFactoryBean(); factoryBean.setJobClass(SampleJob.class); factoryBean.setName(sampleJob); factoryBean.setGroup(default); factoryBean.setDurability(true); return factoryBean; } Bean public CronTriggerFactoryBean sampleJobTrigger() { CronTriggerFactoryBean factoryBean new CronTriggerFactoryBean(); factoryBean.setJobDetail(sampleJobDetail().getObject()); factoryBean.setCronExpression(0 0 8 * * ?); factoryBean.setName(sampleTrigger); factoryBean.setGroup(default); return factoryBean; } }这里重要的地方在于Spring Boot的QuartzAutoConfiguration会自动收集容器里的Trigger类型的Bean并注册到Scheduler中去。所以只要你的Trigger Bean被Spring管理了调度器启动时任务就会自动挂上去不需要自己手动调度。setDurability(true)的含义是即使这个Job没有绑定任何Trigger也把它的定义保留在调度器中。如果设置false一旦没有触发器指向它调度器会删除这个Job。这个设置看着不起眼在动态添加任务的场景里影响很大。JobDetailFactoryBean和CronTriggerFactoryBean返回的都是FactoryBeanSpring容器里实际存放的是getObject()拿到的对象。所以在写依赖时不要直接注入JobDetailFactoryBean类型要声明成JobDetail接口。2.4 配置文件里的全局参数Spring Boot的spring.quartz.*配置项支持很多全局设置基础且常用的是这几个spring.quartz.scheduler-namemyScheduler spring.quartz.startup-delay0 # 自动启动调度器 spring.quartz.auto-startuptrue # 覆盖已存在的任务定义 spring.quartz.overwrite-existing-jobstruespring.quartz.properties.org.quartz.threadPool.threadCount10 spring.quartz.properties.org.quartz.threadPool.threadPriority5spring.quartz.properties这段是把Quartz原生的配置项透传进去重点是线程池设置。Quartz默认的线程数是1也就是同一时刻只能跑一个任务。如果你的项目里有多个定时任务一定要把这个线程数调大否则任务之间会排队一个任务卡了其他任务全等着。根据我踩过的坑这个threadCount的合理值一般是任务数的1.5倍到2倍比如系统里有10个定时任务就配15到20。任务里如果有耗时操作例如调第三方接口、处理大批量数据这个值还要再往大了调。2.5 传统Spring XML方式回顾如果你的项目还是老一套Spring XML配置或者接手的代码风格是XML配置优先那么传统方式大概是这样的bean idsampleJobDetail classorg.springframework.scheduling.quartz.JobDetailFactoryBean property namejobClass valuecom.example.SampleJob/ property namename valuesampleJob/ property namegroup valuedefault/ /bean bean idsampleTrigger classorg.springframework.scheduling.quartz.CronTriggerFactoryBean property namejobDetail refsampleJobDetail/ property namecronExpression value0 0 8 * * ?/ property namename valuesampleTrigger/ /bean bean classorg.springframework.scheduling.quartz.SchedulerFactoryBean property nametriggers list ref beansampleTrigger/ /list /property /bean核心逻辑其实一样构造JobDetail、构造Trigger、把Trigger塞给SchedulerFactoryBean。理解了这个用Boot也好用XML也好都是换汤不换药。3. 任务参数传递与Spring容器协作定时任务最常见的需求之一是同一个任务类不同参数执行不同任务。比如有一个订单超时处理Job可能是针对不同商家、不同渠道的订单分别有不同的任务实例。Quartz里面用JobDataMap这个参数容器来解决。3.1 JobDataMap的基本用法JobDataMap本质就是一个Map但它只能放在JobDetail或者Trigger上。你可以在配置时把参数塞进去在Job执行时取出来Bean public JobDetailFactoryBean orderJobDetail() { JobDetailFactoryBean factoryBean new JobDetailFactoryBean(); factoryBean.setJobClass(OrderTimeoutJob.class); factoryBean.setName(orderJob); factoryBean.setGroup(order); MapString, Object data new HashMap(); data.put(channel, tmall); data.put(timeoutMinutes, 30); factoryBean.setJobDataMap(new JobDataMap(data)); return factoryBean; }在Job执行时从context.getJobDetail().getJobDataMap()取出这些参数public class OrderTimeoutJob implements Job { Override public void execute(JobExecutionContext context) throws JobExecutionException { JobDataMap dataMap context.getJobDetail().getJobDataMap(); String channel dataMap.getString(channel); Integer timeoutMinutes dataMap.getInt(timeoutMinutes); // 业务逻辑处理渠道、超时分钟数对应的订单 } }这里有一个非常容易混淆的点JobDataMap分两种放JobDetail上的和放Trigger上的。执行时getMergedJobDataMap()方法能把两个map合并到一起拿而且Trigger里的key会覆盖JobDetail里的同名key。官方文档里说标准做法是静态参数放JobDetail与触发时间相关的参数放Trigger但实际项目中多数人两种都用记住合并取用的规则就行。3.2 往JobDataMap里塞复杂对象JobDataMap存的不只是基本类型。Spring管理的Service也可以放进去。我在一个老项目里见过别人这么做——把一个业务Service放在JobDetail的dataMap里Job执行时不用依赖Autowired也能拿到服务对象这样Job类本身甚至可以是独立的不需要Spring扫描。不过这种写法有个条件使用RAMJobStore默认时JobDetail其实只存在内存里塞任何Java对象都还行如果改用JDBCJobStore做持久化存入JobDataMap的对象必须实现java.io.Serializable否则序列化存库直接报错。这个坑我在做任务持久化时踩过后面细说。3.3 关于并发执行的坑默认情况下Quartz对同一个JobDetail可能并发执行。意思就是如果上一个执行还没跑完触发时间又到了Quartz会开新的线程再跑一个。如果业务上不允许多个实例同时操作同一批数据必须在Job类上加注解DisallowConcurrentExecution public class OrderTimeoutJob implements Job { // ... }这个注解加在Job类上Quartz就会保证同一个JobDetail在同一个时刻只有一个实例在执行。注意同一个JobDetail这个限定条件同Job类但名称不同的JobDetail不受影响它们还是并发执行的。如果想全局只跑一个实例那就确保只设计一个JobDetail实例。还要注意区分另一个注解PersistJobDataAfterExecution。官方文档的推荐用法是任务里修改了JobDataMap的值且希望执行后把修改保留下来就加上这个注解。一般和DisallowConcurrentExecution一起用因为并发情况下持久化JobDataMap会产生数据竞争具体表现是任务参数的修改丢失。4. 动态任务的创建、修改与暂停聊到这里前面说的都是静态配置——任务在应用启动时注册之后不再变动。但Quartz真正让人离不开的能力是动态管理运行中随时添加一个新任务、查看任务状态、暂停再恢复、修改触发时间、删除任务。这一套能力用Scheduler的API可以全部实现。4.1 动态添加任务的完整代码先注入SchedulerService public class DynamicJobService { private final Scheduler scheduler; public DynamicJobService(Scheduler scheduler) { this.scheduler scheduler; } public boolean addJob(Class? extends Job jobClass, String jobName, String groupName, String cronExpression, MapString, Object params) { // 构建JobDetail JobDetail jobDetail JobBuilder.newJob(jobClass) .withIdentity(jobName, groupName) .usingJobData(new JobDataMap(params)) .storeDurably() .build(); // 构建CronTrigger CronTrigger trigger TriggerBuilder.newTrigger() .withIdentity(jobName Trigger, groupName) .withSchedule(CronScheduleBuilder.cronSchedule(cronExpression)) .build(); // 注册到调度器 scheduler.scheduleJob(jobDetail, trigger); return true; } }几个值得展开的细节withIdentity必须保证JobKey的唯一性。同一个group里的Job名称重复会抛ObjectAlreadyExistsException。实际项目中我一般用业务ID来当jobName比如orderTimeout-12345保证可读又唯一。storeDurably()和刚才说JobDetailFactoryBean.setDurability(true)是一个意思动态任务建议加上否则任务暂时没绑Trigger或Trigger被删除时会被调度器自动移除。usingJobData就是把参数塞进JobDataMap里内容和静态配置里是一样的。4.2 修改任务触发时间动态任务最常见的操作就是改cron表达式。实现思路是拿到已有的TriggerKey用新的Trigger替换旧的。有几种方式我推荐先pause再reschedule避免替换过程中任务被错误触发public boolean rescheduleJob(String jobName, String groupName, String newCron) { TriggerKey triggerKey new TriggerKey(jobName Trigger, groupName); CronTrigger newTrigger TriggerBuilder.newTrigger() .withIdentity(triggerKey) .withSchedule(CronScheduleBuilder.cronSchedule(newCron)) .build(); scheduler.rescheduleJob(triggerKey, newTrigger); return true; }rescheduleJob方法会把TriggerKey对应的旧Trigger替换掉返回调度的同时执行时间就变了。注意如果新Trigger不确定是否已存在直接用rescheduleJob相比scheduleJob更安全已经存在是正常替换没存在会直接抛异常提示。4.3 暂停、恢复、删除与查询这些API比较直白但每一个都有自己的脾气// 暂停一个触发器 scheduler.pauseTrigger(triggerKey); // 恢复触发器 scheduler.resumeTrigger(triggerKey); // 暂停Job如果该Job有多个Trigger全部暂停 scheduler.pauseJob(jobKey); // 恢复Job scheduler.resumeJob(jobKey); // 删除Job返回boolean标识是否删除成功 boolean deleted scheduler.deleteJob(jobKey);pauseTrigger只是暂停了某个触发器Job本身还在调度器里如果还有其他Trigger指向它其他Trigger不受影响。若要把一个任务整个停掉最准确的是用pauseJob。deleteJob有个特别需要注意的点如果Job不设durable持久化标记删掉Trigger的同时Job可能就被自动删除了设了durable之后删Job可以独立操作任务被删除但定义还在。这俩行为交叉起来很容易让人困惑我建议动态任务统一设storeDurably()然后删除操作统一用deleteJob不要动Trigger。查询任务状态也是高频操作public ListJobDetail getAllJobs() throws SchedulerException { SetJobKey jobKeys scheduler.getJobKeys(GroupMatcher.anyGroup()); ListJobDetail list new ArrayList(); for (JobKey key : jobKeys) { list.add(scheduler.getJobDetail(key)); } return list; } public Trigger.TriggerState getTriggerState(String jobName, String groupName) { TriggerKey triggerKey new TriggerKey(jobName Trigger, groupName); return scheduler.getTriggerState(triggerKey); }getTriggerState返回的值有NONE、NORMAL、PAUSED、COMPLETE、ERROR、BLOCKED几种。其中BLOCKED状态很有参考价值说明到了触发时间但上一步任务还没执行完而且这个Job设了DisallowConcurrentExecution新触发被阻塞了。日志里如果发现任务没跑但状态是BLOCKED基本就是这个原因。4.4 动态任务的两种典型业务场景一种是任务由运营在后台配置。比如运营后台配置一个营销活动选择活动开始时间和推送策略接口一调就创建一个新任务。这种场景将参数活动ID、目标用户群ID放到JobDataMap里Job类实现根据参数处理对应的业务。另一种是多租户场景下每个租户有独立的任务。把tenantId放进JobDataMap同一个Job类支持不同租户。我还遇到过需求的升级版不同租户的任务甚至要跑到不同服务器上去执行。这种情况Quartz就不再是完整答案了得用XXL-Job或者分布式调度框架。但那已经超出本文范围只能说Quartz JDBCJobStore可以做到集群共享调度状态但无法按任务粒度路由到不同机器先在心里留个底。5. JDBC持久化与集群部署配置如果现在的部署方式是单机上面所有内容已经足够日常使用了。但等到要升级到集群部署或者领导提出应用重启后定时任务能恢复不丢就必须上JDBCJobStore——把任务和触发器的元数据存到数据库里多个节点的调度器共享同一份状态。5.1 为什么需要JDBCJobStoreQuartz默认的JobStore是RAMJobStore任务定义、触发计划全在内存里应用一重启就全没了。单机环境下大多数项目无所谓因为静态任务本来也是启动时重新注册的。但集群环境下如果每个节点都只认自己的内存状态会出现两个致命问题同一个任务每个节点都各自注册了一份到点每个节点都会执行数据被处理多遍。一个节点把任务暂停了其他节点不知道状态完全对不上。改成JDBCJobStore之后Job、Trigger、锁、状态都放在数据库共享再用数据库行锁和Quartz自带的锁机制保证同一时刻只有一个节点能执行某个任务从而实现多节点调度、单节点执行。集群心跳和生产环境下的高可用基本都靠这个。5.2 配置JDBCJobStoreSpring Boot的spring.quartz.job-store-type配置一行搞定spring.quartz.job-store-typejdbc spring.quartz.properties.org.quartz.jobStore.driverDelegateClassorg.quartz.impl.jdbcjobstore.StdJDBCDelegate再补充必要的JDBC相关配置项spring.quartz.properties.org.quartz.jobStore.isClusteredtrue spring.quartz.properties.org.quartz.jobStore.clusterCheckinInterval15000 spring.quartz.properties.org.quartz.jobStore.maxMisfiresToHandleAtATime20 spring.quartz.properties.org.quartz.jobStore.misfireThreshold60000在非Spring Boot项目里直接在quartz.properties里写同样格式的键值即可Quartz原生前缀org.quartz.jobStore。这段配置的关键点逐一说isClusteredtrue是集群的开关打开后调度器会定期检查集群中其他节点的心跳并参与任务锁的竞争。只写这一行而不配数据库集群可不会生效。clusterCheckinInterval设置节点向数据库报告存活的间隔。默认15秒。如果某个节点宕机其他节点在这个间隔的若干倍时间内会发现它失联并接管它持有的任务。misfireThreshold是触发延迟阈值。如果任务超过这个时间毫秒还没被触发会被标记为MISFIRE。默认60秒。这个值后面讲misfire策略时还会涉及。JDBCStore还需要数据库表。Quartz的发行包里有脚本在org/quartz/impl/jdbcjobstore/目录下面按数据库类型有对应的SQL文件MySQL版本的脚本叫tables_mysql_innodb.sql。这些表包括QRTZ_JOB_DETAILS、QRTZ_TRIGGERS、QRTZ_CRON_TRIGGERS、QRTZ_LOCKS等直接建到业务库里。项目启动时如果表不存在Quartz不会自动建表必须提前执行脚本。这是一个很容易遗漏的步骤。5.3 配置数据源启用了JDBCStore之后Quartz需要连数据库。Spring Boot自动配置默认会使用项目里的DataSource主数据源。如果你想让Quartz用独立的数据源可以单独配置spring.quartz.datasource.namequartzDataSource然后自己定义一个DataSource类型的quartzDataSourceBean。我实践下来的建议如果业务量不大和主数据源公用一个库也没问题。但要注意Quartz的表默认和业务表在同一个库如果用了读写分离的中间件Quartz的写操作尤其是锁表走从库就麻烦了。要么单独建Quartz库要么确保Quartz的DataSource路由到主库。5.4 集群环境下的任务竞争与重复执行JDBC 集群只能保证多个节点的调度器状态一致但并不是天然就能保证一个任务只在一台机器执行一次。有两个机制在起作用第一层是isClusteredtrue时Quartz会在执行任务前获取QRZT_LOCKS表里的分布式锁。锁名和任务名相关每个节点要执行任务前都要抢这把锁抢到的才真正执行其他节点跳过。第二层是任务执行完成后Quartz更新触发器状态和下次触发时间时也会走数据库由数据库的行锁保证状态更新的原子性。这套机制在正常工作下没问题但有几个前提容易忽略各节点的时间尽量保持同步。虽然Quartz做集群调度依赖的是数据库里的next_fire_time不严格依赖机器时钟但时间相差太大会导致misfire判断错乱。任务代码里如果有幂等性要求依然要自己处理。Quartz的分布式锁机制只管调度层面真正执行时任务本身是不是重复消费了业务数据Quartz帮不了。比如任务里发短信服务端要做好重复通知的兜底。5.5 配置misfire策略Misfire是Quartz里一个很容易被忽视但又极其影响体验的概念。简单说任务到了触发时间却没有正常触发而是延迟了就被标记为MISFIRE。什么情况会导致misfire应用停机期间错过了触发时刻、线程池耗尽导致任务排队过久、集群节点故障导致任务漂移。对于CronTriggermisfire策略主要有两种MISFIRE_INSTRUCTION_FIRE_ONCE_NOW立即补偿执行一次。MISFIRE_INSTRUCTION_DO_NOTHING不执行等下一次正常触发。默认策略是MISFIRE_INSTRUCTION_SMART_POLICYQuartz会自己判断。对于CronTrigger它在大多数场景下等价于FIRE_ONCE_NOW。在实际项目中这个默认策略往往会坑人。举个例子每天凌晨2点跑的任务应用恰好故障停机了20分钟2点05分恢复。默认策略会立即补跑一次业务方收到的数据是补偿产生的但心里会疑惑不是两点的任务吗怎么五分钟前跑的。如果任务本身对时点敏感比如必须在特定时间段执行应该明确设置DO_NOTHINGCronTrigger trigger TriggerBuilder.newTrigger() .withIdentity(triggerKey) .withSchedule(CronScheduleBuilder.cronSchedule(cron) .withMisfireHandlingInstructionDoNothing()) .build();到底用哪种策略取决于业务语义。我的判断标准是任务处理的数据是增量时段数据就用FIRE_ONCE_NOW比如统计昨天一天的订单补跑不补跑其实都还好任务处理的是固定时刻快照就用DO_NOTHING比如凌晨结算当日账单这种时间点错过了再补对业务没有意义。确保策略正确是Quartz线上运维体验好坏的分水岭。6. 常见问题与排查技巧这部分我直接把实践中遇到最多的问题整理成清单每一条都是真实踩过的坑。照着排查能省不少时间。6.1 任务没有按预期触发这是遇到最多的一个问题。排查顺序我一般固定先看调度器状态再看触发器状态最后看cron表达式。调度器可能根本没启动。检查配置里spring.quartz.auto-startup是不是被误设成了false或者初始化时抛异常导致没起来。Spring Boot的日志里只要看到Starting Quartz Scheduler就说明启动成功了。触发器状态不对。用getTriggerState查一次如果是PAUSED状态说明之前有人调过pauseTrigger或pauseAll自己确认一下应用里有没有这类逻辑。cron表达式写错了。6位和7位的差异、年和日字段的冲突都是高频坑。Spring的Scheduled(cron...)支持第二位放秒而Quartz的CronTrigger的cron表达式也是7位时第二段是秒。容易搞混的是0 0 12 * * ?这种写法如果你把周字段写了具体值而日字段没写?Quartz会直接告诉你表达式无效。还有一点要注意很多人在线工具验证用的是Spring的cron规则两个框架对表达式支持度和语法规则细节略有不同在线工具写了有效到了Quartz这边可能提示无效反之亦然。遇到cron报错先确认工具对准了哪个框架。检查这三个点之后还不触发再查线程池。Quartz默认线程池只有一个线程如果有长任务占着线程其他任务永远等不到执行。日志里能看到类似Thread pool is exhausted的字样。线程池问题也是最隐蔽的因为任务在日志里一条错误都没有。6.2 任务执行了多次单机环境下的重复执行多半是因为Scheduler被初始化了多次。常见的原因是Spring Boot自动配置了Scheduler代码里又手写了一个SchedulerFactoryBean容器里出现两个调度器各自注册了一遍同样的Trigger。排查方法启动日志里看出现了多少次Starting Quartz Scheduler出现两次基本就是重复初始化。集群环境下的重复执行首先确认isClusteredtrue配置是否真的生效。一个非常常见的遗漏是只在application.properties里写了spring.quartz.properties.org.quartz.jobStore.isClusteredtrue但job-store-type没有改成jdbc。内存模式下你配再多集群参数也不会生效Quartz只会在同一进程内保证唯一。另一个隐蔽场景是应用部署了多个节点JDBC集群配置正确但某个节点的时间不同步misfire阈值判断会错乱可能导致不同节点在短时间内都想补偿执行最终出现重复。处理办法就是把各节点的时间同步做起来配合NTP自动校时。6.3 任务执行完成但状态没更新Quartz执行任务之后要更新触发器状态比如从等待触发改为下次触发时间如果这一环节出了问题任务虽然每次都触发但状态在数据库里可能是旧值。最常见原因是事务问题。Spring Boot用默认的DataSourceQuartz的JobStore操作都是自行管理事务不受Spring事务传播机制影响一般不会有问题。但如果你的项目里用了Transactional包裹Quartz调度的相关方法就有可能导致事务未提交时读不到最新状态。尽量避免把动态任务的创建/修改操作和业务操作放在同一个大事务里。还有一条经验任务执行里如果抛了异常并且Job类继承了StatefulJob这类有状态Job老版本的写法Quartz会记录ERROR状态。很多时候业务日志里没看到异常但状态已经是ERROR可以去Quartz的日志里翻JobExecutionException。在实际Job里我会显式处理异常try { // 业务逻辑 } catch (Exception e) { // 记录详细日志 throw new JobExecutionException(e); }不抛出JobExecutionExceptionQuartz就认为任务执行成功数据库状态正常推进。但如果你的业务逻辑一半成功一半失败你不显式抛异常Quartz无法知道这是失败的。这个任务执行失败但Quartz状态显示正常的问题在没人看业务表数据的情况下能潜伏很久。6.4 动态任务的参数修改不生效前面提过PersistJobDataAfterExecution和DisallowConcurrentExecution要放一起走。因为如果任务执行时修改了JobDataMap但地图保存回JobDetail是在执行结束后发生的并发时后结束的那次覆盖先结束的那次。如果只是临时想改参数更好的做法是jobName里带上参数特征值比如timeout-30和timeout-60作为不同jobName每次改参数就新建任务删除旧任务彻底避免修改JobDetail的持久化数据。这些都是在线上实践出来的经验。每个坑都对应过一次故障复盘我写出来也是希望阅读这篇文章的人能少走几步弯路——哪怕只避开一两个也算值了。7. 从实践角度总结的配置经验文章最后我不想搞什么结构化总结了就说几个我从使用Spring Quartz这么多年里提炼出来的、最简单的经验判断能用简单的就别上复杂的。如果你只有三五个固定任务永远不需要动态调整老老实实用Scheduled别为了让技术栈显得高级引Quartz进来。Quartz是给你应付复杂度和变化的不是给你表演框架集成能力的。但是一旦上了Quartz就把它的管理能力用满——用数据库存储、把任务增删改查做成接口、统一走JobDataMap传参。很多时候项目上了Quartz却只任务解决能配置cron这一个需求把Quartz用成了复杂版的Scheduled这其实很可惜。动态任务设计里Job类一定要轻参数和工作流一定要松。JOB类只做取参数、调Service、处理结果复杂业务不要直接写死在Job里。这样同一个Job配合不同参数才能像乐高一样组合使用。集群配置里面最简单也最容易忽略的反而是节点的时钟同步。数据库和各种锁都是机制保障时间是一切调度判断的地基。地基歪了上面的一切都没用。最后再分享一个小技巧排查Quartz任务问题时把org.quartz的日志级别临时调到DEBUG你会看到非常完整的任务触发流程图——什么时候检查到了任务、什么时候抢到锁、什么时候执行完毕。信息量比业务日志大得多。曾经有一次线上任务延迟我翻Quartz调试日志一眼就看到了misfire判断和线程池排队很快就定位是执行的线程数配小了省去了很多排查时间。Spring Quartz这套组合说简单也简单说深也深。如果你正在配置过程里希望这篇文章能直接帮到你如果你已经配好了那希望那些我踩过的坑能帮你规避掉你还没踩到的那一个。真遇到问题翻一翻调度器的日志再回来看看这些排查思路大概率能找到答案。 Spring集成Quartz实现动态定时任务与集群部署实战
Spring和Quartz这对组合我前前后后用了得有六七年。从最早的Spring 3 Quartz 1.8到后来的Spring Boot Quartz 2.3再到Quartz 3.x支持Spring Boot的starter一路踩坑一路填坑。现在提到定时任务很多人第一反应是Scheduled注解但一旦涉及到动态创建、任务持久化、集群部署Scheduled就完全不够用了。这篇文章我就把自己在实际项目中配置Spring Quartz的完整思路、配置细节和踩过的坑都整理出来给正好需要用这套方案的同行一个参考。我不打算把这篇文章写成那种规规矩矩的API文档更多是分享我在真实项目里怎么想、怎么配、为什么这么配的过程。无论你是刚接手老项目需要改定时任务的配置还是新项目要在Spring Boot里集成Quartz做动态任务调度这篇内容应该都能帮到你——尤其是那些文档里查不到、只有实际动手才会发现的细节。1. 为什么用Quartz而不是只用Scheduled先说一个最基础的问题为什么Spring已经有了Scheduled还要引入Quartz这个重量级调度框架很多初学者都问过我这个我的回答一般就一句话Scheduled解决的是固定死的周期任务Quartz解决的是会变化的、可以管理起来的任务。1.1 Scheduled的局限在哪Scheduled最大的优点是配置简单在方法上加个注解、写个cron表达式就能跑。但你真在项目里用起来就会发现几个绕不开的问题任务执行时间和频率是写死在代码里的。业务方说这个报表任务从每天早上八点改成晚上十点你得改代码重新发布。如果运营希望完全不经过开发就能调整任务时间Scheduled根本做不到。任务状态完全没有管理。任务上一次跑没跑成功下次什么时候跑哪个任务的触发时间是什么这些信息在你没有额外记录的情况下完全没有。顺便说一句Scheduled在Spring容器启动一个线程池执行如果任务执行时间超过了触发间隔它会等上一个任务执行完才触发下一次这在某些场景下是隐患。没有持久化。应用重启之后Scheduled的任务只是重新注册一遍历史执行记录、任务状态全都没有更不用提集群环境下的分布式协调。1.2 Quartz核心解决的问题Quartz把定时任务这件事抽象成了三个核心概念理解了这三个概念就理解了Quartz的大半JobDetail任务详情、Trigger触发器、Scheduler调度器。打个比方JobDetail就像是你写好的一张菜谱Trigger像是一个闹钟Scheduler就像是一个不断看着闹钟、时间一到就照着菜谱做菜的厨师。菜谱可以有很多张闹钟可以有很多个一个厨师可以同时看着很多闹钟一个闹钟响了就做对应的菜。JobDetail定义任务的类型和参数。你写一个类实现Quartz的Job接口这个类就是任务逻辑JobDetail则是这个任务逻辑在调度器里的注册信息可以附带参数。Trigger决定任务何时触发。最常用的是CronTrigger用cron表达式定义复杂的触发计划还有SimpleTrigger适合那种每隔多少秒执行一次的简单周期。Scheduler调度容器。JobDetail和Trigger都要注册到Scheduler里才能跑。Scheduler本身是一个独立组件有自己的生命周期可以启动、暂停、关闭。除了这三个概念Quartz真正比Scheduled强的地方在于Trigger可以被动态创建、修改、删除Job和Trigger的状态可以被持久化到数据库JobStore支持集群部署多个节点共享同一个调度状态任务执行可以记录到历史表里做审计。所以在项目里我一般的原则是如果只是极少数固定的内置任务比如凌晨清理临时文件这种用Scheduled就够但只要任务数量和变动频率上来了或者要接入运营配置、将来可能多机部署直接上Quartz省得后面重构。1.3 Spring整合Quartz的版本考量Spring Quartz的整合方式这些年有过几次明显变化。最初在Spring 3.x时代官方推荐用MethodInvokingJobDetailFactoryBean配合SimpleTriggerBean或CronTriggerBean在XML里配置。到了Spring 4、Spring Boot时代有了JobDetailFactoryBean和CronTriggerFactoryBean。而Quartz 2.3版本开始Spring Boot官方直接提供了spring-boot-starter-quartz模块自动配置了Scheduler、JobStore等基础组件我们只需要聚焦业务任务本身。这篇文章主要基于Spring Boot 2.x Quartz 2.3的方式写这类组合在目前的生产环境里最普及。后文我也会简单提及老项目的XML配置路径方便维护老系统的朋友有个对比参考。2. Spring Boot下Quartz的基础配置咱们直接动手。先说整体思路整合Spring Boot Quartz第一步是加依赖第二步是准备Job类第三步是配置JobDetail和Trigger的Bean第四步是确认Scheduler自动注册了这些Bean。就这四步跑通基础流程之后再去玩高级功能。2.1 引入依赖如果你的项目是Spring Boot 2.x直接用官方starter最省事dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-quartz/artifactId /dependency这个starter做了一件非常重要的事自动创建并配置一个SchedulerFactoryBean把它注册到Spring容器里。同时Spring Boot还自动为Quartz实例了一个调度线程池。你不需要自己手动定义SchedulerFactoryBean这一点和很多老教程里写的都不一样我见过不少同事用旧版的配置来Spring Boot项目里写一遍然后调度器重复初始化算是很典型的低级踩坑。如果用传统Spring非Boot项目要显式引入Quartz的jar。通常Maven坐标是这样的dependency groupIdorg.quartz-scheduler/groupId artifactIdquartz/artifactId version2.3.2/version /dependency再加上Spring上下文里自己声明SchedulerFactoryBean后面我会给出一个完整示例。2.2 写一个最普通的Job类定义了org.quartz.Job接口任务类要实现它的execute方法public class SampleJob implements Job { Override public void execute(JobExecutionContext context) throws JobExecutionException { System.out.println(定时任务执行了 LocalDateTime.now()); } }一个特别重要的细节Job类每次执行时都是Quartz通过反射new的新实例。不要指望任务类里有状态、Quartz会复用同一个对象不是的。execute方法里的局部变量、JobDataMap里取出来的参数、通过Spring容器注入的Service这些才是跨执行之间活下来的东西。如果你的Job类里要用Spring容器管理的Service最简单的方式是直接Autowired。Quartz虽然会new任务类的实例但Spring Boot的自动配置里给Scheduler设置了一个SpringBeanJobFactory实际上是SpringLink的JobFactory它会在实例化Job之后把Spring容器里的依赖注入进去。所以你的Job类可以直接写Component public class SampleJob implements Job { Autowired private ReportService reportService; Override public void execute(JobExecutionContext context) throws JobExecutionException { reportService.generateDailyReport(); } }注意两个前提Job类要能被Spring管理到。要么标Component交给Spring扫描要么在手动配置JobDetail时需要能在Spring容器里找到这个Bean。另外Job类得有public的无参构造方法Quartz反射创建实例才不会有问题。2.3 配置JobDetail和TriggerJob类写好了接下来就是把JobDetail和Trigger交给Spring容器管理。在Spring Boot里Configuration public class QuartzConfig { Bean public JobDetailFactoryBean sampleJobDetail() { JobDetailFactoryBean factoryBean new JobDetailFactoryBean(); factoryBean.setJobClass(SampleJob.class); factoryBean.setName(sampleJob); factoryBean.setGroup(default); factoryBean.setDurability(true); return factoryBean; } Bean public CronTriggerFactoryBean sampleJobTrigger() { CronTriggerFactoryBean factoryBean new CronTriggerFactoryBean(); factoryBean.setJobDetail(sampleJobDetail().getObject()); factoryBean.setCronExpression(0 0 8 * * ?); factoryBean.setName(sampleTrigger); factoryBean.setGroup(default); return factoryBean; } }这里重要的地方在于Spring Boot的QuartzAutoConfiguration会自动收集容器里的Trigger类型的Bean并注册到Scheduler中去。所以只要你的Trigger Bean被Spring管理了调度器启动时任务就会自动挂上去不需要自己手动调度。setDurability(true)的含义是即使这个Job没有绑定任何Trigger也把它的定义保留在调度器中。如果设置false一旦没有触发器指向它调度器会删除这个Job。这个设置看着不起眼在动态添加任务的场景里影响很大。JobDetailFactoryBean和CronTriggerFactoryBean返回的都是FactoryBeanSpring容器里实际存放的是getObject()拿到的对象。所以在写依赖时不要直接注入JobDetailFactoryBean类型要声明成JobDetail接口。2.4 配置文件里的全局参数Spring Boot的spring.quartz.*配置项支持很多全局设置基础且常用的是这几个spring.quartz.scheduler-namemyScheduler spring.quartz.startup-delay0 # 自动启动调度器 spring.quartz.auto-startuptrue # 覆盖已存在的任务定义 spring.quartz.overwrite-existing-jobstruespring.quartz.properties.org.quartz.threadPool.threadCount10 spring.quartz.properties.org.quartz.threadPool.threadPriority5spring.quartz.properties这段是把Quartz原生的配置项透传进去重点是线程池设置。Quartz默认的线程数是1也就是同一时刻只能跑一个任务。如果你的项目里有多个定时任务一定要把这个线程数调大否则任务之间会排队一个任务卡了其他任务全等着。根据我踩过的坑这个threadCount的合理值一般是任务数的1.5倍到2倍比如系统里有10个定时任务就配15到20。任务里如果有耗时操作例如调第三方接口、处理大批量数据这个值还要再往大了调。2.5 传统Spring XML方式回顾如果你的项目还是老一套Spring XML配置或者接手的代码风格是XML配置优先那么传统方式大概是这样的bean idsampleJobDetail classorg.springframework.scheduling.quartz.JobDetailFactoryBean property namejobClass valuecom.example.SampleJob/ property namename valuesampleJob/ property namegroup valuedefault/ /bean bean idsampleTrigger classorg.springframework.scheduling.quartz.CronTriggerFactoryBean property namejobDetail refsampleJobDetail/ property namecronExpression value0 0 8 * * ?/ property namename valuesampleTrigger/ /bean bean classorg.springframework.scheduling.quartz.SchedulerFactoryBean property nametriggers list ref beansampleTrigger/ /list /property /bean核心逻辑其实一样构造JobDetail、构造Trigger、把Trigger塞给SchedulerFactoryBean。理解了这个用Boot也好用XML也好都是换汤不换药。3. 任务参数传递与Spring容器协作定时任务最常见的需求之一是同一个任务类不同参数执行不同任务。比如有一个订单超时处理Job可能是针对不同商家、不同渠道的订单分别有不同的任务实例。Quartz里面用JobDataMap这个参数容器来解决。3.1 JobDataMap的基本用法JobDataMap本质就是一个Map但它只能放在JobDetail或者Trigger上。你可以在配置时把参数塞进去在Job执行时取出来Bean public JobDetailFactoryBean orderJobDetail() { JobDetailFactoryBean factoryBean new JobDetailFactoryBean(); factoryBean.setJobClass(OrderTimeoutJob.class); factoryBean.setName(orderJob); factoryBean.setGroup(order); MapString, Object data new HashMap(); data.put(channel, tmall); data.put(timeoutMinutes, 30); factoryBean.setJobDataMap(new JobDataMap(data)); return factoryBean; }在Job执行时从context.getJobDetail().getJobDataMap()取出这些参数public class OrderTimeoutJob implements Job { Override public void execute(JobExecutionContext context) throws JobExecutionException { JobDataMap dataMap context.getJobDetail().getJobDataMap(); String channel dataMap.getString(channel); Integer timeoutMinutes dataMap.getInt(timeoutMinutes); // 业务逻辑处理渠道、超时分钟数对应的订单 } }这里有一个非常容易混淆的点JobDataMap分两种放JobDetail上的和放Trigger上的。执行时getMergedJobDataMap()方法能把两个map合并到一起拿而且Trigger里的key会覆盖JobDetail里的同名key。官方文档里说标准做法是静态参数放JobDetail与触发时间相关的参数放Trigger但实际项目中多数人两种都用记住合并取用的规则就行。3.2 往JobDataMap里塞复杂对象JobDataMap存的不只是基本类型。Spring管理的Service也可以放进去。我在一个老项目里见过别人这么做——把一个业务Service放在JobDetail的dataMap里Job执行时不用依赖Autowired也能拿到服务对象这样Job类本身甚至可以是独立的不需要Spring扫描。不过这种写法有个条件使用RAMJobStore默认时JobDetail其实只存在内存里塞任何Java对象都还行如果改用JDBCJobStore做持久化存入JobDataMap的对象必须实现java.io.Serializable否则序列化存库直接报错。这个坑我在做任务持久化时踩过后面细说。3.3 关于并发执行的坑默认情况下Quartz对同一个JobDetail可能并发执行。意思就是如果上一个执行还没跑完触发时间又到了Quartz会开新的线程再跑一个。如果业务上不允许多个实例同时操作同一批数据必须在Job类上加注解DisallowConcurrentExecution public class OrderTimeoutJob implements Job { // ... }这个注解加在Job类上Quartz就会保证同一个JobDetail在同一个时刻只有一个实例在执行。注意同一个JobDetail这个限定条件同Job类但名称不同的JobDetail不受影响它们还是并发执行的。如果想全局只跑一个实例那就确保只设计一个JobDetail实例。还要注意区分另一个注解PersistJobDataAfterExecution。官方文档的推荐用法是任务里修改了JobDataMap的值且希望执行后把修改保留下来就加上这个注解。一般和DisallowConcurrentExecution一起用因为并发情况下持久化JobDataMap会产生数据竞争具体表现是任务参数的修改丢失。4. 动态任务的创建、修改与暂停聊到这里前面说的都是静态配置——任务在应用启动时注册之后不再变动。但Quartz真正让人离不开的能力是动态管理运行中随时添加一个新任务、查看任务状态、暂停再恢复、修改触发时间、删除任务。这一套能力用Scheduler的API可以全部实现。4.1 动态添加任务的完整代码先注入SchedulerService public class DynamicJobService { private final Scheduler scheduler; public DynamicJobService(Scheduler scheduler) { this.scheduler scheduler; } public boolean addJob(Class? extends Job jobClass, String jobName, String groupName, String cronExpression, MapString, Object params) { // 构建JobDetail JobDetail jobDetail JobBuilder.newJob(jobClass) .withIdentity(jobName, groupName) .usingJobData(new JobDataMap(params)) .storeDurably() .build(); // 构建CronTrigger CronTrigger trigger TriggerBuilder.newTrigger() .withIdentity(jobName Trigger, groupName) .withSchedule(CronScheduleBuilder.cronSchedule(cronExpression)) .build(); // 注册到调度器 scheduler.scheduleJob(jobDetail, trigger); return true; } }几个值得展开的细节withIdentity必须保证JobKey的唯一性。同一个group里的Job名称重复会抛ObjectAlreadyExistsException。实际项目中我一般用业务ID来当jobName比如orderTimeout-12345保证可读又唯一。storeDurably()和刚才说JobDetailFactoryBean.setDurability(true)是一个意思动态任务建议加上否则任务暂时没绑Trigger或Trigger被删除时会被调度器自动移除。usingJobData就是把参数塞进JobDataMap里内容和静态配置里是一样的。4.2 修改任务触发时间动态任务最常见的操作就是改cron表达式。实现思路是拿到已有的TriggerKey用新的Trigger替换旧的。有几种方式我推荐先pause再reschedule避免替换过程中任务被错误触发public boolean rescheduleJob(String jobName, String groupName, String newCron) { TriggerKey triggerKey new TriggerKey(jobName Trigger, groupName); CronTrigger newTrigger TriggerBuilder.newTrigger() .withIdentity(triggerKey) .withSchedule(CronScheduleBuilder.cronSchedule(newCron)) .build(); scheduler.rescheduleJob(triggerKey, newTrigger); return true; }rescheduleJob方法会把TriggerKey对应的旧Trigger替换掉返回调度的同时执行时间就变了。注意如果新Trigger不确定是否已存在直接用rescheduleJob相比scheduleJob更安全已经存在是正常替换没存在会直接抛异常提示。4.3 暂停、恢复、删除与查询这些API比较直白但每一个都有自己的脾气// 暂停一个触发器 scheduler.pauseTrigger(triggerKey); // 恢复触发器 scheduler.resumeTrigger(triggerKey); // 暂停Job如果该Job有多个Trigger全部暂停 scheduler.pauseJob(jobKey); // 恢复Job scheduler.resumeJob(jobKey); // 删除Job返回boolean标识是否删除成功 boolean deleted scheduler.deleteJob(jobKey);pauseTrigger只是暂停了某个触发器Job本身还在调度器里如果还有其他Trigger指向它其他Trigger不受影响。若要把一个任务整个停掉最准确的是用pauseJob。deleteJob有个特别需要注意的点如果Job不设durable持久化标记删掉Trigger的同时Job可能就被自动删除了设了durable之后删Job可以独立操作任务被删除但定义还在。这俩行为交叉起来很容易让人困惑我建议动态任务统一设storeDurably()然后删除操作统一用deleteJob不要动Trigger。查询任务状态也是高频操作public ListJobDetail getAllJobs() throws SchedulerException { SetJobKey jobKeys scheduler.getJobKeys(GroupMatcher.anyGroup()); ListJobDetail list new ArrayList(); for (JobKey key : jobKeys) { list.add(scheduler.getJobDetail(key)); } return list; } public Trigger.TriggerState getTriggerState(String jobName, String groupName) { TriggerKey triggerKey new TriggerKey(jobName Trigger, groupName); return scheduler.getTriggerState(triggerKey); }getTriggerState返回的值有NONE、NORMAL、PAUSED、COMPLETE、ERROR、BLOCKED几种。其中BLOCKED状态很有参考价值说明到了触发时间但上一步任务还没执行完而且这个Job设了DisallowConcurrentExecution新触发被阻塞了。日志里如果发现任务没跑但状态是BLOCKED基本就是这个原因。4.4 动态任务的两种典型业务场景一种是任务由运营在后台配置。比如运营后台配置一个营销活动选择活动开始时间和推送策略接口一调就创建一个新任务。这种场景将参数活动ID、目标用户群ID放到JobDataMap里Job类实现根据参数处理对应的业务。另一种是多租户场景下每个租户有独立的任务。把tenantId放进JobDataMap同一个Job类支持不同租户。我还遇到过需求的升级版不同租户的任务甚至要跑到不同服务器上去执行。这种情况Quartz就不再是完整答案了得用XXL-Job或者分布式调度框架。但那已经超出本文范围只能说Quartz JDBCJobStore可以做到集群共享调度状态但无法按任务粒度路由到不同机器先在心里留个底。5. JDBC持久化与集群部署配置如果现在的部署方式是单机上面所有内容已经足够日常使用了。但等到要升级到集群部署或者领导提出应用重启后定时任务能恢复不丢就必须上JDBCJobStore——把任务和触发器的元数据存到数据库里多个节点的调度器共享同一份状态。5.1 为什么需要JDBCJobStoreQuartz默认的JobStore是RAMJobStore任务定义、触发计划全在内存里应用一重启就全没了。单机环境下大多数项目无所谓因为静态任务本来也是启动时重新注册的。但集群环境下如果每个节点都只认自己的内存状态会出现两个致命问题同一个任务每个节点都各自注册了一份到点每个节点都会执行数据被处理多遍。一个节点把任务暂停了其他节点不知道状态完全对不上。改成JDBCJobStore之后Job、Trigger、锁、状态都放在数据库共享再用数据库行锁和Quartz自带的锁机制保证同一时刻只有一个节点能执行某个任务从而实现多节点调度、单节点执行。集群心跳和生产环境下的高可用基本都靠这个。5.2 配置JDBCJobStoreSpring Boot的spring.quartz.job-store-type配置一行搞定spring.quartz.job-store-typejdbc spring.quartz.properties.org.quartz.jobStore.driverDelegateClassorg.quartz.impl.jdbcjobstore.StdJDBCDelegate再补充必要的JDBC相关配置项spring.quartz.properties.org.quartz.jobStore.isClusteredtrue spring.quartz.properties.org.quartz.jobStore.clusterCheckinInterval15000 spring.quartz.properties.org.quartz.jobStore.maxMisfiresToHandleAtATime20 spring.quartz.properties.org.quartz.jobStore.misfireThreshold60000在非Spring Boot项目里直接在quartz.properties里写同样格式的键值即可Quartz原生前缀org.quartz.jobStore。这段配置的关键点逐一说isClusteredtrue是集群的开关打开后调度器会定期检查集群中其他节点的心跳并参与任务锁的竞争。只写这一行而不配数据库集群可不会生效。clusterCheckinInterval设置节点向数据库报告存活的间隔。默认15秒。如果某个节点宕机其他节点在这个间隔的若干倍时间内会发现它失联并接管它持有的任务。misfireThreshold是触发延迟阈值。如果任务超过这个时间毫秒还没被触发会被标记为MISFIRE。默认60秒。这个值后面讲misfire策略时还会涉及。JDBCStore还需要数据库表。Quartz的发行包里有脚本在org/quartz/impl/jdbcjobstore/目录下面按数据库类型有对应的SQL文件MySQL版本的脚本叫tables_mysql_innodb.sql。这些表包括QRTZ_JOB_DETAILS、QRTZ_TRIGGERS、QRTZ_CRON_TRIGGERS、QRTZ_LOCKS等直接建到业务库里。项目启动时如果表不存在Quartz不会自动建表必须提前执行脚本。这是一个很容易遗漏的步骤。5.3 配置数据源启用了JDBCStore之后Quartz需要连数据库。Spring Boot自动配置默认会使用项目里的DataSource主数据源。如果你想让Quartz用独立的数据源可以单独配置spring.quartz.datasource.namequartzDataSource然后自己定义一个DataSource类型的quartzDataSourceBean。我实践下来的建议如果业务量不大和主数据源公用一个库也没问题。但要注意Quartz的表默认和业务表在同一个库如果用了读写分离的中间件Quartz的写操作尤其是锁表走从库就麻烦了。要么单独建Quartz库要么确保Quartz的DataSource路由到主库。5.4 集群环境下的任务竞争与重复执行JDBC 集群只能保证多个节点的调度器状态一致但并不是天然就能保证一个任务只在一台机器执行一次。有两个机制在起作用第一层是isClusteredtrue时Quartz会在执行任务前获取QRZT_LOCKS表里的分布式锁。锁名和任务名相关每个节点要执行任务前都要抢这把锁抢到的才真正执行其他节点跳过。第二层是任务执行完成后Quartz更新触发器状态和下次触发时间时也会走数据库由数据库的行锁保证状态更新的原子性。这套机制在正常工作下没问题但有几个前提容易忽略各节点的时间尽量保持同步。虽然Quartz做集群调度依赖的是数据库里的next_fire_time不严格依赖机器时钟但时间相差太大会导致misfire判断错乱。任务代码里如果有幂等性要求依然要自己处理。Quartz的分布式锁机制只管调度层面真正执行时任务本身是不是重复消费了业务数据Quartz帮不了。比如任务里发短信服务端要做好重复通知的兜底。5.5 配置misfire策略Misfire是Quartz里一个很容易被忽视但又极其影响体验的概念。简单说任务到了触发时间却没有正常触发而是延迟了就被标记为MISFIRE。什么情况会导致misfire应用停机期间错过了触发时刻、线程池耗尽导致任务排队过久、集群节点故障导致任务漂移。对于CronTriggermisfire策略主要有两种MISFIRE_INSTRUCTION_FIRE_ONCE_NOW立即补偿执行一次。MISFIRE_INSTRUCTION_DO_NOTHING不执行等下一次正常触发。默认策略是MISFIRE_INSTRUCTION_SMART_POLICYQuartz会自己判断。对于CronTrigger它在大多数场景下等价于FIRE_ONCE_NOW。在实际项目中这个默认策略往往会坑人。举个例子每天凌晨2点跑的任务应用恰好故障停机了20分钟2点05分恢复。默认策略会立即补跑一次业务方收到的数据是补偿产生的但心里会疑惑不是两点的任务吗怎么五分钟前跑的。如果任务本身对时点敏感比如必须在特定时间段执行应该明确设置DO_NOTHINGCronTrigger trigger TriggerBuilder.newTrigger() .withIdentity(triggerKey) .withSchedule(CronScheduleBuilder.cronSchedule(cron) .withMisfireHandlingInstructionDoNothing()) .build();到底用哪种策略取决于业务语义。我的判断标准是任务处理的数据是增量时段数据就用FIRE_ONCE_NOW比如统计昨天一天的订单补跑不补跑其实都还好任务处理的是固定时刻快照就用DO_NOTHING比如凌晨结算当日账单这种时间点错过了再补对业务没有意义。确保策略正确是Quartz线上运维体验好坏的分水岭。6. 常见问题与排查技巧这部分我直接把实践中遇到最多的问题整理成清单每一条都是真实踩过的坑。照着排查能省不少时间。6.1 任务没有按预期触发这是遇到最多的一个问题。排查顺序我一般固定先看调度器状态再看触发器状态最后看cron表达式。调度器可能根本没启动。检查配置里spring.quartz.auto-startup是不是被误设成了false或者初始化时抛异常导致没起来。Spring Boot的日志里只要看到Starting Quartz Scheduler就说明启动成功了。触发器状态不对。用getTriggerState查一次如果是PAUSED状态说明之前有人调过pauseTrigger或pauseAll自己确认一下应用里有没有这类逻辑。cron表达式写错了。6位和7位的差异、年和日字段的冲突都是高频坑。Spring的Scheduled(cron...)支持第二位放秒而Quartz的CronTrigger的cron表达式也是7位时第二段是秒。容易搞混的是0 0 12 * * ?这种写法如果你把周字段写了具体值而日字段没写?Quartz会直接告诉你表达式无效。还有一点要注意很多人在线工具验证用的是Spring的cron规则两个框架对表达式支持度和语法规则细节略有不同在线工具写了有效到了Quartz这边可能提示无效反之亦然。遇到cron报错先确认工具对准了哪个框架。检查这三个点之后还不触发再查线程池。Quartz默认线程池只有一个线程如果有长任务占着线程其他任务永远等不到执行。日志里能看到类似Thread pool is exhausted的字样。线程池问题也是最隐蔽的因为任务在日志里一条错误都没有。6.2 任务执行了多次单机环境下的重复执行多半是因为Scheduler被初始化了多次。常见的原因是Spring Boot自动配置了Scheduler代码里又手写了一个SchedulerFactoryBean容器里出现两个调度器各自注册了一遍同样的Trigger。排查方法启动日志里看出现了多少次Starting Quartz Scheduler出现两次基本就是重复初始化。集群环境下的重复执行首先确认isClusteredtrue配置是否真的生效。一个非常常见的遗漏是只在application.properties里写了spring.quartz.properties.org.quartz.jobStore.isClusteredtrue但job-store-type没有改成jdbc。内存模式下你配再多集群参数也不会生效Quartz只会在同一进程内保证唯一。另一个隐蔽场景是应用部署了多个节点JDBC集群配置正确但某个节点的时间不同步misfire阈值判断会错乱可能导致不同节点在短时间内都想补偿执行最终出现重复。处理办法就是把各节点的时间同步做起来配合NTP自动校时。6.3 任务执行完成但状态没更新Quartz执行任务之后要更新触发器状态比如从等待触发改为下次触发时间如果这一环节出了问题任务虽然每次都触发但状态在数据库里可能是旧值。最常见原因是事务问题。Spring Boot用默认的DataSourceQuartz的JobStore操作都是自行管理事务不受Spring事务传播机制影响一般不会有问题。但如果你的项目里用了Transactional包裹Quartz调度的相关方法就有可能导致事务未提交时读不到最新状态。尽量避免把动态任务的创建/修改操作和业务操作放在同一个大事务里。还有一条经验任务执行里如果抛了异常并且Job类继承了StatefulJob这类有状态Job老版本的写法Quartz会记录ERROR状态。很多时候业务日志里没看到异常但状态已经是ERROR可以去Quartz的日志里翻JobExecutionException。在实际Job里我会显式处理异常try { // 业务逻辑 } catch (Exception e) { // 记录详细日志 throw new JobExecutionException(e); }不抛出JobExecutionExceptionQuartz就认为任务执行成功数据库状态正常推进。但如果你的业务逻辑一半成功一半失败你不显式抛异常Quartz无法知道这是失败的。这个任务执行失败但Quartz状态显示正常的问题在没人看业务表数据的情况下能潜伏很久。6.4 动态任务的参数修改不生效前面提过PersistJobDataAfterExecution和DisallowConcurrentExecution要放一起走。因为如果任务执行时修改了JobDataMap但地图保存回JobDetail是在执行结束后发生的并发时后结束的那次覆盖先结束的那次。如果只是临时想改参数更好的做法是jobName里带上参数特征值比如timeout-30和timeout-60作为不同jobName每次改参数就新建任务删除旧任务彻底避免修改JobDetail的持久化数据。这些都是在线上实践出来的经验。每个坑都对应过一次故障复盘我写出来也是希望阅读这篇文章的人能少走几步弯路——哪怕只避开一两个也算值了。7. 从实践角度总结的配置经验文章最后我不想搞什么结构化总结了就说几个我从使用Spring Quartz这么多年里提炼出来的、最简单的经验判断能用简单的就别上复杂的。如果你只有三五个固定任务永远不需要动态调整老老实实用Scheduled别为了让技术栈显得高级引Quartz进来。Quartz是给你应付复杂度和变化的不是给你表演框架集成能力的。但是一旦上了Quartz就把它的管理能力用满——用数据库存储、把任务增删改查做成接口、统一走JobDataMap传参。很多时候项目上了Quartz却只任务解决能配置cron这一个需求把Quartz用成了复杂版的Scheduled这其实很可惜。动态任务设计里Job类一定要轻参数和工作流一定要松。JOB类只做取参数、调Service、处理结果复杂业务不要直接写死在Job里。这样同一个Job配合不同参数才能像乐高一样组合使用。集群配置里面最简单也最容易忽略的反而是节点的时钟同步。数据库和各种锁都是机制保障时间是一切调度判断的地基。地基歪了上面的一切都没用。最后再分享一个小技巧排查Quartz任务问题时把org.quartz的日志级别临时调到DEBUG你会看到非常完整的任务触发流程图——什么时候检查到了任务、什么时候抢到锁、什么时候执行完毕。信息量比业务日志大得多。曾经有一次线上任务延迟我翻Quartz调试日志一眼就看到了misfire判断和线程池排队很快就定位是执行的线程数配小了省去了很多排查时间。Spring Quartz这套组合说简单也简单说深也深。如果你正在配置过程里希望这篇文章能直接帮到你如果你已经配好了那希望那些我踩过的坑能帮你规避掉你还没踩到的那一个。真遇到问题翻一翻调度器的日志再回来看看这些排查思路大概率能找到答案。