主题
starter-job
1. 职责
把 Quartz 的调度操作收敛成一个 SchedulerManager(增删改、暂停、恢复、立即执行),并把「任务」抽象成业务只写 JobHandler 接口的实现类——任务参数、重试次数、执行日志全部走框架约定。
它同时开了 @Async 并给线程池装 TtlRunnable,让 @Async 方法里还能拿到 LoginUser 与租户上下文。
它不解决:任务配置的增删改查界面与存储(在 pmforge-module-infra 的定时任务模块)、任务日志落库(JobLogFrameworkService 只定义接口)、分片与集群选主(Quartz 自身基于数据库锁)。
本节路径均省略公共前缀
framework/pmforge-spring-boot-starter-job/src/main/java/com/pmforge/framework/。
2. 关键类
| 类 | 作用 | 路径 |
|---|---|---|
PmforgeQuartzAutoConfiguration | @EnableScheduling + SchedulerManager(Quartz 未启用时传 null 并打提示) | quartz/config/PmforgeQuartzAutoConfiguration.java |
PmforgeAsyncAutoConfiguration | @EnableAsync;给 ThreadPoolTaskExecutor/SimpleAsyncTaskExecutor 设 TaskDecorator = TtlRunnable::get | quartz/config/PmforgeAsyncAutoConfiguration.java |
JobHandler | 业务实现接口:String execute(String param) throws Exception | quartz/core/handler/JobHandler.java |
JobHandlerInvoker | QuartzJobBean 实现:取 JobDataMap → applicationContext.getBean(jobHandlerName) → 执行 → 按重试策略 refire | quartz/core/handler/JobHandlerInvoker.java |
JobDataKeyEnum | JOB_ID/JOB_HANDLER_NAME/JOB_HANDLER_PARAM/JOB_RETRY_COUNT/JOB_RETRY_INTERVAL | quartz/core/enums/JobDataKeyEnum.java |
SchedulerManager | 以 jobHandlerName 同时作 JobKey 与 TriggerKey:addJob/updateJob/deleteJob/pauseJob/resumeJob/triggerJob | quartz/core/scheduler/SchedulerManager.java |
JobLogFrameworkService | createJobLog(...) + updateJobLogResultAsync(...);实现由业务模块提供 | quartz/core/service/JobLogFrameworkService.java |
CronUtils | isValid(cron)、getNextTimes(cron, n) | quartz/core/util/CronUtils.java |
3. 自动配置
| 配置类 | 生效条件 | 注册了什么 |
|---|---|---|
PmforgeQuartzAutoConfiguration | 始终装配 | @EnableScheduling;SchedulerManager(Optional<Scheduler>)——没有 Scheduler 时传 null,只打一行 log.info("[定时任务 - 已禁用][如需启用,请修改根 pom.xml 与 apps/pmforge-server/pom.xml]") |
PmforgeAsyncAutoConfiguration | 始终装配 | @EnableAsync;BeanPostProcessor 给线程池设 setTaskDecorator(TtlRunnable::get) |
Scheduler 本身由 spring-boot-starter-quartz 提供;本模块不引入 Quartz 的 starter,所以「定时任务被禁用」通常意味着依赖没加或 spring.quartz 没配。
4. 配置项
| 前缀 | 键 | 默认值 | 说明 |
|---|---|---|---|
| — | 无 | — | 本模块没有 @ConfigurationProperties |
spring.quartz | job-store-type | 无默认(示例 jdbc) | Quartz 存储方式 |
spring.quartz.properties.org.quartz.jobStore | class | 无默认(示例 org.springframework.scheduling.quartz.LocalDataSourceJobStore) | JobStore 实现 |
spring.quartz.properties.org.quartz.jobStore | driverDelegateClass | 由 starter-mybatis 的 IdTypeEnvironmentPostProcessor 按数据库类型自动填 | 如 PostgreSQL 填 PostgreSQLDelegate、达梦/人大金仓填 StdJDBCDelegate |
任务本身的数据(cron、重试次数、参数)存在 JobDataMap 里,键是 JobDataKeyEnum 的 5 个常量,不走 yaml。
5. 扩展点
- 写一个任务:
@Component("demoJob") class DemoJob implements JobHandler { public String execute(String param) {...} },Bean 名就是jobHandlerName。 - 调度:业务模块注入
SchedulerManager,调addJob(jobId, jobHandlerName, param, cron, retryCount, retryInterval);改 cron 用updateJob,立即跑一次用triggerJob。 - 记录执行日志:实现
JobLogFrameworkServiceBean(接口已定好,executeIndex从 1 开始,等于refireCount + 1)。 - 异步任务上下文:直接用
@Async即可,TaskDecorator已经帮你传TransmittableThreadLocal;自定义线程池记得也加TtlRunnable。 - Cron 校验:前端提交 cron 前用
CronUtils.isValid与getNextTimes给预览。
6. 常见坑
jobHandlerName必须是 Spring Bean 名:JobHandlerInvoker用applicationContext.getBean(jobHandlerName, JobHandler.class),类名 ≠ Bean 名(默认首字母小写)时启动不报错、执行时才NoSuchBeanDefinitionException。- 重试是「立即 refire」而非新调度:
refireCount达到retryCount才抛JobExecutionException终止;否则retryInterval > 0时先ThreadUtil.sleep再throw new JobExecutionException(e, true)——注意它占用同一个 Quartz 执行线程。 SchedulerManager的方法都先validateScheduler():Quartz 未启用时不会 NPE,而是抛NOT_IMPLEMENTED+ 那句「请修改根 pom.xml 与 apps/pmforge-server/pom.xml」的提示,看到这句就知道是依赖问题。@DisallowConcurrentExecution在JobHandlerInvoker上是全局语义:同一个 JobDetail 不会并发执行,但不同租户跑同一个 Job(@TenantJob)是串行还是并行取决于租户切面,不要假设并行安全。triggerJob(立即执行)不带重试参数:手动触发走的是默认JobDataMap,之前配的retryCount/retryInterval不会带入。
7. 关联页面
- starter-mybatis:
driverDelegateClass自动填充的出处 - starter-biz-tenant:
@TenantJob多租户执行 - starter-mq:Redis Stream 的补偿/清理任务也依赖调度
- 定时任务、横切机制