Skip to content

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::getquartz/config/PmforgeAsyncAutoConfiguration.java
JobHandler业务实现接口:String execute(String param) throws Exceptionquartz/core/handler/JobHandler.java
JobHandlerInvokerQuartzJobBean 实现:取 JobDataMap → applicationContext.getBean(jobHandlerName) → 执行 → 按重试策略 refirequartz/core/handler/JobHandlerInvoker.java
JobDataKeyEnumJOB_ID/JOB_HANDLER_NAME/JOB_HANDLER_PARAM/JOB_RETRY_COUNT/JOB_RETRY_INTERVALquartz/core/enums/JobDataKeyEnum.java
SchedulerManager以 jobHandlerName 同时作 JobKey 与 TriggerKey:addJob/updateJob/deleteJob/pauseJob/resumeJob/triggerJobquartz/core/scheduler/SchedulerManager.java
JobLogFrameworkServicecreateJobLog(...) + updateJobLogResultAsync(...);实现由业务模块提供quartz/core/service/JobLogFrameworkService.java
CronUtilsisValid(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.quartzjob-store-type无默认(示例 jdbc)Quartz 存储方式
spring.quartz.properties.org.quartz.jobStoreclass无默认(示例 org.springframework.scheduling.quartz.LocalDataSourceJobStore)JobStore 实现
spring.quartz.properties.org.quartz.jobStoredriverDelegateClass由 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。
  • 记录执行日志:实现 JobLogFrameworkService Bean(接口已定好,executeIndex 从 1 开始,等于 refireCount + 1)。
  • 异步任务上下文:直接用 @Async 即可,TaskDecorator 已经帮你传 TransmittableThreadLocal;自定义线程池记得也加 TtlRunnable。
  • Cron 校验:前端提交 cron 前用 CronUtils.isValid 与 getNextTimes 给预览。

6. 常见坑 ​

  1. jobHandlerName 必须是 Spring Bean 名:JobHandlerInvoker 用 applicationContext.getBean(jobHandlerName, JobHandler.class),类名 ≠ Bean 名(默认首字母小写)时启动不报错、执行时才 NoSuchBeanDefinitionException。
  2. 重试是「立即 refire」而非新调度:refireCount 达到 retryCount 才抛 JobExecutionException 终止;否则 retryInterval > 0 时先 ThreadUtil.sleep 再 throw new JobExecutionException(e, true)——注意它占用同一个 Quartz 执行线程。
  3. SchedulerManager 的方法都先 validateScheduler():Quartz 未启用时不会 NPE,而是抛 NOT_IMPLEMENTED + 那句「请修改根 pom.xml 与 apps/pmforge-server/pom.xml」的提示,看到这句就知道是依赖问题。
  4. @DisallowConcurrentExecution 在 JobHandlerInvoker 上是全局语义:同一个 JobDetail 不会并发执行,但不同租户跑同一个 Job(@TenantJob)是串行还是并行取决于租户切面,不要假设并行安全。
  5. triggerJob(立即执行)不带重试参数:手动触发走的是默认 JobDataMap,之前配的 retryCount/retryInterval 不会带入。

7. 关联页面 ​