简介：这份资源面向具备一定Java Web基础的开发者，聚焦SSM框架与Quartz调度器的整合实践，解决定时任务配置分散、无法动态管理的问题。包内共55个文件，以40个jar依赖包为主，辅以7个xml配置文件、3个properties配置、2个jsp页面及少量class与清单文件，压缩包约28.2MB，涵盖Spring、MyBatis、Quartz、Shiro等核心组件，可直接导入运行。资源完整呈现了将JobDetail与Trigger持久化到数据库的实现思路，通过MyBatis操作Quartz相关数据表，配合Spring MVC接口完成定时任务的动态增删改查，并附带任务管理页面用于列表展示与表单操作。目前已有706人学习下载，适合需要构建可维护调度模块的开发者参考，帮助理解任务持久化、线程池与并发策略等关键配置，快速搭建可扩展的定时任务管理骨架。
1. 从一次定时任务翻车说起：SSM 整合 Quartz 并持久化到数据库到底解决什么问题
很多做 Java Web 的朋友都遇到过这种场景：项目里需要每天凌晨跑一次对账、每隔十分钟同步一次状态、某个活动结束后自动关闭入口。一开始用@Scheduled注解或者Timer也能凑合，但只要需求方说一句“这个任务我想在后台页面上手动改时间、临时停掉、再加一个新的”，纯注解方案立刻就不够用了。因为注解写死在代码里，改一次时间就得重新打包发版，运维和开发都得陪着加班。
这个资源要解决的，就是把 Quartz 这颗老牌调度引擎塞进 SSM（Spring + SpringMVC + MyBatis）框架里，并且把任务、触发器这些调度元数据持久化到数据库，从而实现任务的动态增删改查。说白了，就是让定时任务从“写死在代码里”变成“存在数据库里、能在页面上管”。它适合正在维护传统 SSM 项目、又不想引入 Spring Boot 那一整套的从业者，也适合想搞明白 Quartz 持久化机制到底怎么落地的同学。下面我按自己拆包复现的顺序，把配置、建表、动态操作和踩过的坑一条条讲清楚。
2. Quartz 持久化原理与 SSM 整合的选型账：为什么不是 @Scheduled
2.1 Quartz 三件套与数据库持久化的关系
Quartz 的核心概念其实就三个：Job（干什么活）、Trigger（什么时候干）、Scheduler（调度器，负责把前两者撮合到一起）。如果只用内存存储，RAMJobStore会把 Job 和 Trigger 放在内存里，应用一重启，所有动态添加的任务全丢。而持久化用的是JobStoreTX或JobStoreCMT，它会把 JobDetail、Trigger、日历等信息写进数据库的十几张表里，重启后调度器从库里恢复现场。
这里有个容易混淆的点：Quartz 持久化的是“任务定义和触发规则”，不是任务执行到哪一步的业务状态。比如你有个任务要处理 1000 条数据，跑到第 300 条时应用挂了，Quartz 不会帮你记住“已经处理到 300”，它只负责下次触发时间到了再喊你一次。业务上的断点续跑得自己在 Job 里做幂等或进度记录，这是两码事。
选JobStoreTX还是JobStoreCMT，取决于事务由谁管。SSM 里通常用 Spring 的DataSourceTransactionManager，我一般选JobStoreTX，然后让 Spring 把dataSource注入给SchedulerFactoryBean，事务交给 Quartz 自己通过JobStoreTX管理，配置更直观。如果项目用了 JTA 全局事务，才考虑JobStoreCMT。
2.2 为什么不用 @Scheduled 或 Timer
@Scheduled的优点是零配置，缺点是触发规则编译期固定，cron表达式来自注解或配置文件，运行时改不了。Timer更原始，单线程、异常直接终止整个调度。Quartz 的优势在于：触发器可以存库、可以动态注册、支持 misfire 补偿策略、支持集群（多节点抢锁执行）。对于“后台可管理定时任务”这个需求，Quartz 几乎是传统 SSM 项目里最稳的选择。
不过要提醒一句，Quartz 不是分布式任务队列，它的集群能力是“同一时刻只有一个节点触发”，适合任务量不大、对实时性要求不极端的场景。如果任务量大到需要分片、需要可视化编排，那是另一套东西了，别硬拿 Quartz 扛。
2.3 SSM 整合的依赖与版本对齐
整合第一步是把依赖理清楚。Quartz 2.x 和 Spring 4/5 搭配比较成熟，spring-context-support里带了SchedulerFactoryBean，不用自己写工厂。下面是我复现时用的 Maven 依赖片段，版本号按你项目实际锁定的来，别盲目追新。
<!-- Quartz 调度核心 --> <dependency> <groupId>org.quartz-scheduler</groupId> <artifactId>quartz</artifactId> <version>2.3.2</version> </dependency> <!-- Spring 对 Quartz 的封装，提供 SchedulerFactoryBean --> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-context-support</artifactId> <version>5.3.30</version> </dependency> <!-- 连接池，Quartz 持久化需要 --> <dependency> <groupId>com.mchange</groupId> <artifactId>c3p0</artifactId> <version>0.9.5.5</version> </dependency>依赖说明：quartz是引擎本体；spring-context-support提供整合入口；连接池不是必须用 c3p0，用 Druid 也行，关键是 Quartz 的JobStoreTX需要一个能独立管理事务的数据源。如果项目里已经有 Druid，直接复用即可，不必额外引 c3p0，避免多套连接池打架。
3. 建表、配置与第一个可持久化的 Job：把调度元数据落进 MySQL
3.1 Quartz 官方建表脚本怎么选、怎么改
Quartz 发行包里docs/dbTables目录下有一堆建表 SQL，按数据库类型分。MySQL 用tables_mysql_innodb.sql，因为要事务支持，别用 MyISAM 版本。一共 11 张表，核心几张是：
| 表名 | 作用 |
|---|---|
| QRTZ_JOB_DETAILS | 存 JobDetail，任务定义 |
| QRTZ_TRIGGERS | 存 Trigger 基本信息 |
| QRTZ_CRON_TRIGGERS | 存 cron 类型的触发器表达式 |
| QRTZ_SIMPLE_TRIGGERS | 存 simple 类型触发器 |
| QRTZ_FIRED_TRIGGERS | 存正在触发的实例，集群抢锁用 |
| QRTZ_LOCKS | 集群锁表，单机也建议保留 |
| QRTZ_SCHEDULER_STATE | 调度器实例状态 |
建表时有个血泪经验：表名前缀默认是QRTZ_，如果你项目里数据库规范要求统一前缀，可以在SchedulerFactoryBean里配tablePrefix，但建表脚本里的表名也得同步改，两边必须一致，否则启动就报Table 'xxx.QRTZ_TRIGGERS' doesn't exist。我一般不改前缀，省得对不上。
-- 以 MySQL 为例，执行官方脚本后确认表结构 -- 关键字段：JOB_NAME、JOB_GROUP 联合唯一标识一个任务 -- TRIGGER_NAME、TRIGGER_GROUP 联合唯一标识一个触发器 -- 动态增删改查本质就是操作这几张表对应的 API执行完脚本后，用SHOW TABLES LIKE 'QRTZ%';确认 11 张表都在。如果少了QRTZ_LOCKS，集群模式下会出问题，单机虽然能跑，但建议一并建上。
3.2 SchedulerFactoryBean 配置与 dataSource 注入
Spring 配置文件里，核心是把SchedulerFactoryBean声明出来，把数据源、事务、Quartz 属性灌进去。下面是我复现时用的配置，注释写清了每个参数的作用。
<bean id="schedulerFactoryBean" class="org.springframework.scheduling.quartz.SchedulerFactoryBean"> <!-- 注入项目数据源，Quartz 持久化靠它 --> <property name="dataSource" ref="dataSource"/> <!-- 事务管理器，JobStoreTX 需要 --> <property name="transactionManager" ref="transactionManager"/> <!-- 覆盖 Quartz 自带 quartz.properties 的关键项 --> <property name="quartzProperties"> <props> <!-- 使用数据库持久化 JobStore --> <prop key="org.quartz.jobStore.class">org.quartz.impl.jdbcjobstore.JobStoreTX</prop> <!-- 数据库方言，MySQL 用 StdJDBCDelegate --> <prop key="org.quartz.jobStore.driverDelegateClass">org.quartz.impl.jdbcjobstore.StdJDBCDelegate</prop> <!-- 表前缀，和建表脚本保持一致 --> <prop key="org.quartz.jobStore.tablePrefix">QRTZ_</prop> <!-- 集群开关，单机设 false --> <prop key="org.quartz.jobStore.isClustered">false</prop> <!-- misfire 阈值，超过这个时间没触发就按补偿策略处理 --> <prop key="org.quartz.jobStore.misfireThreshold">60000</prop> <!-- 线程池大小，按任务并发量调 --> <prop key="org.quartz.threadPool.threadCount">10</prop> </props> </property> <!-- 应用启动时延迟几秒再启动调度器，等 Spring 容器就绪 --> <property name="startupDelay" value="10"/> <!-- 优雅关闭，等待正在执行的任务结束 --> <property name="waitForJobsToCompleteOnShutdown" value="true"/> <!-- 自动启动 --> <property name="autoStartup" value="true"/> </bean>参数说明：driverDelegateClass选错是高频翻车点，MySQL 用StdJDBCDelegate，Oracle 用OracleDelegate，PostgreSQL 用PostgreSQLDelegate，选错会在写库时报语法错误。isClustered单机一定设 false，设 true 会去抢QRTZ_LOCKS的锁，单节点虽然也能跑，但多一层无谓开销。misfireThreshold默认 60000 毫秒，意思是触发器该触发但调度器忙不过来，超过 60 秒才认定为 misfire，然后按触发器的 misfire 策略处理。
3.3 写一个能被持久化调度的 Job
Quartz 2.x 推荐 Job 类继承QuartzJobBean或实现Job接口。如果要在 Job 里用 Spring 管理的 Service，得让 Job 能被 Spring 注入，常见做法是继承QuartzJobBean并在executeInternal里拿业务逻辑，或者用JobDataMap传参。下面是一个可持久化的 Job 示例。
public class SyncStatusJob extends QuartzJobBean { // Spring 管理的 Service，通过 setter 注入 private SyncService syncService; public void setSyncService(SyncService syncService) { this.syncService = syncService; } @Override protected void executeInternal(JobExecutionContext context) throws JobExecutionException { // 从 JobDataMap 取动态参数，比如业务类型 JobDataMap dataMap = context.getMergedJobDataMap(); String bizType = dataMap.getString("bizType"); try { syncService.syncByType(bizType); } catch (Exception e) { // 包装成 JobExecutionException，决定是否重试 throw new JobExecutionException(e, false); } } }逻辑说明：executeInternal是实际执行入口，context.getMergedJobDataMap()能同时拿到 JobDetail 和 Trigger 上挂的参数。JobExecutionException(e, false)第二个参数表示不立即重试，避免异常时疯狂重跑。如果业务需要重试，可以传 true 或设置setRefireImmediately。注意 Job 类本身不要存可变状态，Quartz 可能并发实例化，状态放 JobDataMap 或数据库里。
4. 动态增删改查的落地：用 Scheduler API 操作数据库里的任务
4.1 新增任务：JobDetail + CronTrigger 的组装
动态新增的本质是：构造JobDetail和Trigger，调scheduler.scheduleJob，Quartz 会把它们写进QRTZ_JOB_DETAILS和QRTZ_TRIGGERS等表。下面是一个 Service 层方法。
@Service public class QuartzManageService { @Autowired private Scheduler scheduler; public void addJob(String jobName, String jobGroup, String cron, Class<? extends Job> jobClass, Map<String, Object> params) throws SchedulerException { // 1. 构造 JobDetail，指定任务名、组名、实现类 JobDetail jobDetail = JobBuilder.newJob(jobClass) .withIdentity(jobName, jobGroup) .usingJobData(new JobDataMap(params)) // 动态参数 .storeDurably() // 没有触发器也保留，便于后续绑定 .build(); // 2. 构造 CronTrigger，绑定 cron 表达式 CronTrigger trigger = TriggerBuilder.newTrigger() .withIdentity(jobName + "_trigger", jobGroup) .forJob(jobDetail) .withSchedule(CronScheduleBuilder.cronSchedule(cron) .withMisfireHandlingInstructionDoNothing()) // misfire 不补跑 .build(); // 3. 交给调度器，写库 scheduler.scheduleJob(jobDetail, trigger); } }参数说明：withIdentity的 name + group 是联合主键，重复添加会抛ObjectAlreadyExistsException，所以新增前一般先查是否存在。storeDurably()让 JobDetail 在没有 Trigger 时也保留在库里，适合“先建任务、后配触发器”的场景。withMisfireHandlingInstructionDoNothing()表示错过触发时间就不补，适合对账这类过了点就没意义的任务；如果是必须补跑的，用withMisfireHandlingInstructionFireAndProceed()。
4.2 修改任务：rescheduleJob 与 TriggerKey 的坑
修改分两种：只改触发时间，用rescheduleJob；连 JobDetail 一起改，得先删再建。只改 cron 的写法如下。
public void updateCron(String jobName, String jobGroup, String newCron) throws SchedulerException { TriggerKey triggerKey = TriggerKey.triggerKey(jobName + "_trigger", jobGroup); // 构造新的 Trigger，替换旧的 CronTrigger newTrigger = TriggerBuilder.newTrigger() .withIdentity(triggerKey) .withSchedule(CronScheduleBuilder.cronSchedule(newCron)) .build(); scheduler.rescheduleJob(triggerKey, newTrigger); }这里有个坑：rescheduleJob的 TriggerKey 必须和原来存库的完全一致，包括 name 和 group。如果你新增时触发器名字是jobName + "_trigger"，修改时也得用同样规则拼，否则报Trigger does not exist。我见过有人新增用默认触发器名，修改时自己拼了一个，结果库里多出一条孤儿触发器。稳妥做法是把触发器命名规则封装成一个方法，新增、修改、删除都调它。
4.3 删除、暂停与恢复：状态字段背后的表操作
删除任务用scheduler.deleteJob(JobKey.jobKey(jobName, jobGroup))，它会级联删掉关联的 Trigger。暂停用scheduler.pauseJob，恢复用scheduler.resumeJob。暂停不是删库，而是把QRTZ_TRIGGERS里对应记录的TRIGGER_STATE改成PAUSED，恢复时改回WAITING。
public void deleteJob(String jobName, String jobGroup) throws SchedulerException { JobKey jobKey = JobKey.jobKey(jobName, jobGroup); if (scheduler.checkExists(jobKey)) { scheduler.deleteJob(jobKey); // 级联删除触发器 } } public void pauseJob(String jobName, String jobGroup) throws SchedulerException { scheduler.pauseJob(JobKey.jobKey(jobName, jobGroup)); } public void resumeJob(String jobName, String jobGroup) throws SchedulerException { scheduler.resumeJob(JobKey.jobKey(jobName, jobGroup)); }逻辑说明：checkExists先判断再删，避免任务不存在时抛异常影响页面提示。暂停和恢复只改状态，不丢定义，适合“临时停用但保留配置”的场景。如果页面需要展示任务列表，直接查QRTZ_JOB_DETAILS和QRTZ_TRIGGERS关联查询即可，但更推荐用scheduler.getJobKeys和getTriggerKeys走 API，避免直接读表绕过 Quartz 的缓存。
4.4 查询任务列表与状态映射
页面上要展示任务名、cron、下次触发时间、状态。用 API 查询比直接写 SQL 稳，因为 Quartz 内部有状态缓存。
public List<Map<String, Object>> listJobs() throws SchedulerException { List<Map<String, Object>> result = new ArrayList<>(); for (JobKey jobKey : scheduler.getJobKeys(GroupMatcher.anyJobGroup())) { JobDetail detail = scheduler.getJobDetail(jobKey); List<? extends Trigger> triggers = scheduler.getTriggersOfJob(jobKey); for (Trigger trigger : triggers) { Map<String, Object> row = new HashMap<>(); row.put("jobName", jobKey.getName()); row.put("jobGroup", jobKey.getGroup()); row.put("triggerState", scheduler.getTriggerState(trigger.getKey()).name()); row.put("nextFireTime", trigger.getNextFireTime()); if (trigger instanceof CronTrigger) { row.put("cron", ((CronTrigger) trigger).getCronExpression()); } result.add(row); } } return result; }参数说明：GroupMatcher.anyJobGroup()匹配所有组，也可以按组过滤。getTriggerState返回NORMAL、PAUSED、COMPLETE、ERROR、BLOCKED等枚举，页面展示时建议做一层中文映射，别直接把英文状态甩给用户。getNextFireTime可能为 null，比如触发器已暂停或已完成，前端要处理空值。
5. 避坑与排查：Quartz 持久化最容易翻车的五个地方
5.1 启动报表不存在或字段不匹配
现象：应用启动时抛SQLSyntaxErrorException或Table 'QRTZ_TRIGGERS' doesn't exist。原因通常是建表脚本没执行、表前缀和配置不一致、或者用了 MyISAM 版本脚本导致事务相关字段缺失。解决：确认quartzProperties里的tablePrefix和实际表名一致，MySQL 用 InnoDB 脚本，执行后用DESC QRTZ_TRIGGERS核对字段。
5.2 任务重复触发或集群下多节点同时跑
现象：单机环境任务跑两次，或者集群里两个节点同时执行同一个任务。原因：单机重复多半是SchedulerFactoryBean被实例化了两次，或者应用部署了两个实例但isClustered设了 false。解决：确保 Spring 容器里只有一个SchedulerFactoryBean；集群部署时isClustered必须设 true，并保证各节点时钟同步，否则抢锁判断会出偏差。
5.3 cron 表达式写错导致任务不触发
现象：任务加进去了，状态是 NORMAL，但永远不触发。原因：cron 表达式字段顺序写错，Quartz 是「秒 分 时 日 月 周 年」，和 Linux crontab 的「分 时 日 月 周」不一样。解决：用在线 cron 校验工具先验证，或者写个单元测试调CronExpression.isValidExpression。另外注意?和*的区别，日和周通常一个用?一个用具体值。
5.4 Job 类里注入的 Service 为 null
现象：任务触发时抛NullPointerException，发现syncService是 null。原因：Job 实例是 Quartz 通过反射创建的，不走 Spring 容器，@Autowired不生效。解决：用QuartzJobBean配合SchedulerFactoryBean的jobFactory设置AutowiringSpringBeanJobFactory，或者用JobDataMap把 Service 传进去（不推荐，序列化麻烦）。我一般配一个自定义JobFactory，让 Job 也能享受 Spring 注入。
5.5 修改 cron 后不生效或旧触发器残留
现象：调了修改接口，数据库里 cron 变了，但实际触发时间还是旧的。原因：Quartz 有本地缓存，或者修改时 TriggerKey 拼错导致新建了一个触发器而旧的没删。解决：修改后调scheduler.rescheduleJob并确认返回非 null；如果返回 null 说明旧触发器没找到，去QRTZ_TRIGGERS里查一下是不是有同名不同组的残留记录。命名规则统一能省掉这类玄学问题。
6. 进阶技巧：用 JobDataMap 传参、misfire 策略与一个自检习惯
动态任务真正难的不是增删改查，而是“任务执行时怎么拿到运行时参数”和“错过触发时间怎么办”。JobDataMap是 Quartz 传参的标准方式，但要注意：如果 Job 类没有实现Serializable，或者用了JobStoreTX持久化，放进JobDataMap的对象必须可序列化，否则写库时报NotSerializableException。我一般只放 String、Integer 这类基本类型，复杂对象存业务表主键，Job 里再查一次。
misfire 策略是另一个容易忽略的点。下面这张表是我整理的各策略适用场景：
| 策略 | 行为 | 适用场景 |
|---|---|---|
| withMisfireHandlingInstructionDoNothing | 错过的不补，等下次 | 对账、日报 |
| withMisfireHandlingInstructionFireAndProceed | 立即补跑一次，再按计划 | 状态同步 |
| withMisfireHandlingInstructionIgnoreMisfires | 全部补跑 | 数据补偿 |
| withMisfireHandlingInstructionNextWithRemainingCount | 按剩余次数继续 | 有限次任务 |
验证持久化是否真的生效，我有个固定习惯：新增一个任务后，重启应用，看任务是否还在、下次触发时间是否正确。如果重启后任务消失，说明JobStoreTX没配好，或者dataSource没注入进去。再进一步，直接去QRTZ_JOB_DETAILS里SELECT JOB_NAME, JOB_GROUP FROM QRTZ_JOB_DETAILS;，能看到记录才算落库成功。
还有一个细节：SchedulerFactoryBean的waitForJobsToCompleteOnShutdown设 true 后，应用关闭会等正在执行的任务跑完，但等待时间受org.quartz.scheduler.interruptJobsOnShutdownWithWait等参数影响。如果任务执行很久，关闭可能卡住，生产环境要评估任务时长，必要时设超时。
从那以后我每次整合 Quartz，都强制走一遍「建表核对 → 单机新增 → 重启验证 → 集群开关确认」这四步，少一步都可能在上线后收到“任务没跑”的告警。希望帮到你。
本文还有配套的精品资源，点击获取
