Skip to content

定时任务与异步 ​

一句话:业务只实现 JobHandler,Quartz 的 JobHandlerInvoker 负责取参数、写任务日志、失败重试;@TenantJob 让一个任务按租户循环执行,@Async 则靠 TTL 装饰器把登录态与租户带进线程池。

适用场景:新增一个定时任务;排查「任务没跑」「跑了两次」「日志只有半边」;写异步方法时上下文丢失。

不适用场景:一次性延迟任务(用 MQ 延迟消息或 stream);分布式任务的抢占(Quartz 的并发控制按 JobDetail,不是业务锁)。

1. 一条任务的三个角色 ​

角色类作用
业务实现JobHandler#execute(String param)(#L8-L18)只写业务,返回字符串作为执行结果
Quartz 壳JobHandlerInvoker(#L29)取 JobDataMap、写日志、调 handler、处理重试
调度管理SchedulerManageradd/update/pause/resume/trigger/delete,封装 Quartz API

1.1 JobHandlerInvoker 做了什么 ​

executeInternal(#L38-L66):

  1. 从 JobDataMap 取 JOB_ID、JOB_HANDLER_NAME、JOB_HANDLER_PARAM、refireCount、retryCount、retryInterval(#L40-L45);
  2. 先落一条 RUNNING 日志:jobLogFrameworkService.createJobLog(jobId, startTime, handlerName, param, refireCount + 1)(#L54),executeIndex 就是第几次执行;
  3. executeInternal(name, param) 通过 applicationContext.getBean(jobHandlerName, JobHandler.class) 拿到 Bean(#L70),所以 Bean 名必须等于任务配置里的 handlerName;
  4. finally 里 updateJobLogResultAsync 回填结果(#L62);
  5. 异常交给 handleException(#L93-L111)。

重试语义(#L93-L111):refireCount >= retryCount 时抛 JobExecutionException 结束;否则 sleep(retryInterval) 后 throw new JobExecutionException(exception, true)——第二个参数 true 表示立即重新触发,不是按原 cron 等下一轮。

@DisallowConcurrentExecution(#L26)保证同一个 JobDetail 不会并发执行;@PersistJobDataAfterExecution(#L27)让 refireCount 能跨重试保留。

1.2 JobLog 落库 ​

JobLogServiceImpl:

  • createJobLog 插入 status=RUNNING 的记录并返回 ID(#L29-L37);
  • updateJobLogResultAsync 带 @Async(#L40),回填 endTime、duration、status、result(#L39-L51),失败只记日志不影响调度;
  • 日志清理 cleanJobLog(exceedDay, deleteLimit)(#L55-L68)按批删,deleteCount < deleteLimit 就停,避免长事务。

因为 create 是同步、update 是异步,看到 RUNNING 不代表任务卡住,可能只是回填线程还没写完;判断卡住要看 startTime 与 monitorTimeout。

2. 注册与调度 ​

JobServiceImpl#createJob(#L45-L69)的顺序值得记:

  1. 校验 cron(#L48);
  2. 按 handlerName 查重(#L50-L52,同名任务只能有一个);
  3. validateJobHandlerExists:SpringUtil.getBean(handlerName),不是 JobHandler 抛类型错,找不到抛「Bean 不存在」(#L94-L104);
  4. 先插 DB(status=INIT),再 schedulerManager.addJob(...)(#L63-L64),最后把状态改成 NORMAL(#L66-L67)。

「先库后调度」的好处是失败可补偿:syncJob()(#L140-L158)会删掉所有 Quartz 任务再按库重建,STOP 状态的重建后补一次 pause。

SchedulerManager 用 handlerName 同时作为 JobKey 与 TriggerKey(#L13-L17),这就是「同名任务只能一个」的根因。addJob 里 JobBuilder.newJob(JobHandlerInvoker.class).withIdentity(jobHandlerName)(#L45-L48),业务类本身不注册进 Quartz。

状态约束:只有 NORMAL 的任务能改配置(#L78-L80 抛 JOB_UPDATE_ONLY_NORMAL_STATUS),因为暂停状态下改 Quartz 会让任务意外开始执行。

3. @TenantJob:一个任务跑遍所有租户 ​

TenantJobAspect(#L34-L56):

java
tenantIds.parallelStream().forEach(tenantId ->
    TenantUtils.execute(tenantId, () -> joinPoint.proceed()));
  • 并行流,每个租户独立上下文(TenantUtils.execute 内部强制 setIgnore(false) 并在结束后还原);
  • 每个租户的结果/异常分别收集(#L49-L52),最后返回 JSON Map(#L56);某个租户失败不会中断其它租户;
  • 因此日志里的一条记录实际包含 N 个租户的执行结果。

硬性要求:业务必须幂等。因为重试是「整个 JobDetail 重跑」,已经成功的租户会再跑一遍(源码类注释明确写了这一点)。示例见 pmforge-module-system/.../job/DemoJob.java#L19-L25:方法上标 @TenantJob,内部直接 adminUserMapper.selectList(),靠租户拦截器自动隔离。

反向场景:全局任务(如清理所有租户的过期日志)不要加 @TenantJob,而应加 @TenantIgnore 跳过租户条件——JobLogCleanJob#L33 就是这样,配合常量 JOB_CLEAN_RETAIN_DAY=14(#L25)、DELETE_LIMIT=100(#L30)。

4. @Async 与线程池 ​

PmforgeAsyncAutoConfiguration(#L15-L16)只做两件事:@EnableAsync + 给容器里已有的线程池装 TTL 装饰器(#L19-L43),把 ThreadPoolTaskExecutor 与 SimpleAsyncTaskExecutor 的 TaskDecorator 设为 TtlRunnable::get。

它不定义线程池,所以默认用的是 Spring Boot 的 applicationTaskExecutor(spring.task.execution.*),项目 yaml 里没有覆盖,即默认 8 个核心线程、无界队列。

由此带来的约定:

  • @Async 方法要 public、不能同类自调用(Spring 代理限制);
  • 上下文(LoginUser、TenantContextHolder)能传过去,是因为 TTL 装饰器 + TransmittableThreadLocalSecurityContextHolderStrategy(安全 starter 里 SecurityContextHolder.setStrategyName);
  • 但事务不会传:异步方法里查不到调用方未提交的数据;需要「提交后再做」就用 TransactionSynchronizationManager 或 MQ。

现成用法:ApiAccessLogCommonApi#L27、OperateLogCommonApi#L27、JobLogServiceImpl#L40。

5. 本地如何触发一次 ​

管理后台:PUT /admin-api/infra/job/trigger?id=xxx,权限点 infra:job:trigger(JobController#L94-L97)。

底层链路:JobService#triggerJob(#L131-L138)校验任务存在 → SchedulerManager#triggerJob(#L121-L130)手动塞 JOB_ID/JOB_HANDLER_NAME/JOB_HANDLER_PARAM 后 scheduler.triggerJob(new JobKey(handlerName), data)。

注意手动触发不带 retryCount/retryInterval(#L125-L128),所以失败不会重试;cron 仍按原计划继续。

本地开发也可以直接调 Handler Bean,但会绕过任务日志,只适合验证业务逻辑。

⚠️ local 配置默认没有 Scheduler:application-local.yaml#L10 把 QuartzAutoConfiguration 放进了 spring.autoconfigure.exclude(注释「默认 local 环境,不开启 Quartz 的自动配置」)。因此在 local 下打开任务管理页点「执行」会得到 NOT_IMPLEMENTED;要么切到 dev profile,要么从 exclude 里去掉这一行。

6. 集群部署注意 ​

application-dev.yaml 里的 Quartz 配置(#L70-L95)已经按集群来配了:job-store-type: jdbc(#L73)、LocalDataSourceJobStore(#L85)、isClustered: true(#L86)、clusterCheckinInterval: 15000(#L87)、wait-for-jobs-to-complete-on-shutdown: true(#L74)、threadCount: 25(#L91)、initialize-schema: NEVER(#L95,表结构要手工初始化)。

在此之上还要注意:

  • 并发控制靠 @DisallowConcurrentExecution,它约束的是同一个 JobDetail,前提是各节点连同一个 Quartz 库;如果换成内存 JobStore,每个节点会各跑一份。
  • TenantJobAspect 用 parallelStream,在容器里默认走 ForkJoinPool.commonPool;租户很多时会把公共池打满,影响同一 JVM 的其它并行流。需要限流就给任务加自己的线程池,或在 handler 内串行。
  • 任务日志的 create 是同步的,集群下每个节点都会写自己的记录,executeIndex=1 不代表「全局第一次」。
  • syncJob() 会短时间删除并重建全部 Trigger,集群滚动发布时不要频繁调用。
  • 长任务要考虑 monitorTimeout(默认 0,见 JobServiceImpl#L209-L213),否则「卡住」只能靠人工看日志。

7. 排错清单 ​

症状先看判断依据
任务建了但不跑JobServiceImpl#L63-L67DB 状态是否 NORMAL;Quartz 是否 pause;cron 是否合法
local 点「执行」报 501application-local.yaml#L10local 默认排除了 Quartz 自动配置,没有 Scheduler
启动报 handler 不存在#L94-L104Bean 名与任务配置的 handlerName 不一致,或没加 @Component
任务跑了两次@DisallowConcurrentExecution、JobStore集群各节点独立 JobStore;或手动 trigger 与 cron 撞车
日志一直 RUNNINGJobLogServiceImpl#L39-L51异步回填失败(只记日志);或任务真的卡住
重试次数不对JobHandlerInvoker#L93-L111refireCount 从 JobDataMap 来;手动触发不带重试参数
某租户数据串了TenantJobAspect#L44-L52handler 内自己开了线程且没走 TenantUtils;或误加 @TenantIgnore
部分租户成功、部分失败TenantJobAspect#L49-L52每个租户结果独立,重跑会全部重来 → 必须幂等
异步方法里租户为空PmforgeAsyncAutoConfiguration#L19-L43线程池不是 Spring 管理的,装饰器没生效
异步方法查不到刚写的数据事务边界主事务未提交,异步线程读不到