Quartz 定时任务调度原理#

// 通过工厂创建 Scheduler
Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();

// 添加一个任务
scheduler.scheduleJob(jobDetail, trigger);

// 启动调度器
scheduler.start();

// 关闭
scheduler.shutdown();

// ❌ 错误理解：JobDetail 就是 Job
// ✅ 正确理解：JobDetail 是任务的描述信息，Job 是任务执行逻辑

// JobDetail 包含：
// - Job 的类名（用于反射实例化）
// - 任务名称和分组
// - 任务数据 JobDataMap
// - 持久化标记（isDurable）
// - 可恢复标记（requestsRecovery）

// Job 只有一个 execute 方法
public interface Job {
    void execute(JobExecutionContext context) throws JobExecutionException;
}

// 因为 Job 可能被并发执行
// 如果复用同一个实例，成员变量会被多个线程同时修改
public class MyJob implements Job {
    private int count = 0; // ❌ 如果复用，这个值会被并发污染

    @Override
    public void execute(JobExecutionContext context) throws JobExecutionException {
        // 每次触发都是新的 MyJob 实例，count 始终是 0
        count++; // 线程安全
    }
}

// 自定义 JobFactory：让 Spring 注入依赖
public class SpringJobFactory extends AdaptableJobFactory {

    @Autowired
    private AutowireCapableBeanFactory beanFactory;

    @Override
    protected Object createJobInstance(TriggerFiredBundle bundle) throws Exception {
        // 使用 Spring 的 BeanFactory 创建 Job 实例
        Object job = super.createJobInstance(bundle);
        // 自动注入 @Autowired 字段
        beanFactory.autowireBean(job);
        return job;
    }
}

// 在 Spring 配置中使用
@Bean
public SpringJobFactory springJobFactory() {
    return new SpringJobFactory();
}

@Bean
public SchedulerFactoryBean schedulerFactory(SpringJobFactory factory) {
    SchedulerFactoryBean bean = new SchedulerFactoryBean();
    bean.setJobFactory(factory);
    return bean;
}

// 场景：每天早上9点执行一次
SimpleTrigger trigger = newTrigger()
    .withIdentity("myTrigger", "group1")
    .startAt(DateBuilder.todayAt(9, 0, 0))  // 早上9点
    .withSchedule(
        simpleSchedule()
            .withIntervalInHours(24)         // 每24小时
            .repeatForever()                 // 无限重复
    )
    .build();

// 场景：立即执行，每30分钟一次，共执行10次
SimpleTrigger trigger = newTrigger()
    .startAt(DateBuilder.futureDate(0, IntervalUnit.SECOND))
    .withSchedule(
        simpleSchedule()
            .withIntervalInMinutes(30)
            .withRepeatCount(9)  // 共执行10次（1次 + 9次重复）
    )
    .build();

CronTrigger trigger = newTrigger()
    .withIdentity("myCronTrigger", "group1")
    .withSchedule(cronSchedule("0 0 9 ? * MON-FRI"))  // 每周一到周五早上9点
    .build();

// 每天早上9点整
"0 0 9 * * ?"

// 每周一早上9点
"0 0 9 ? * MON"

// 每月1号和15号凌晨2点
"0 0 2 1,15 * ?"

// 每天早上9点到下午6点，每小时整点执行
"0 0 9-18 * * ?"

// 每月最后一个工作日（用L和W组合）
"0 0 18 LW * ?"  // 注意：LW 表示最后一个工作日
// 注意：Quartz 的 L 和 W 组合行为和 Linux cron 不一样！

// 每隔5分钟
"0 0/5 * * * ?"

// 每年1月1日凌晨0点
"0 0 0 1 1 ?"

// Quartz Cron 表达式：6位格式
// 秒  分  时  日  月  周
// 0   0   9   *   *   ?   每天9点整

// 第一位：秒（0-59）
// 第二位：分（0-59）
// 第三位：时（0-23）
// 第四位：日（1-31，* 表示每一天）
// 第五位：月（1-12 或 JAN-DEC）
// 第六位：周（1-7 或 SUN-SAT，? 表示不关心）

// ❌ 错误：日和周同时指定
"0 0 9 15 * MON"  // 矛盾：第15天 AND 周一

// ✅ 正确：固定一个为 ?
"0 0 9 15 * ?"     // 每月15号
"0 0 9 ? * MON"    // 每周一

// L - 最后的值
"0 0 18 L * ?"     // 每月最后一天18点
"0 0 ? * 6L"       // 每月最后一个周五

// W - 最近的工作日
"0 0 9 15W * ?"    // 每月15号最近的工作日（如果15号是周六，则14号执行）

// C - 日历相关
"0 0 9 1C * ?"     // 每月第一天

// 1. 调度器被关闭了一段时间
// 2. 执行节点挂了
// 3. 触发时刻系统负载过高，线程池满了
// 4. Quartz 集群中数据库锁竞争激烈，导致触发延迟

// 比如：任务应该每10秒执行一次
// 但调度器因为数据库锁竞争，15秒后才触发
// 这5秒的延迟就是 Misfire

// SimpleTrigger 的 Misfire 策略
withMisfireHandlingInstructionFireNow()       // 立即触发一次，然后按新规则
withMisfireHandlingInstructionNowWithRemainingCount() // 用剩余次数补发
withMisfireHandlingInstructionNowWithExistingCount()  // 只触发一次，用现有次数
withMisfireHandlingInstructionIgnoreMisfires()         // 忽略所有 Misfire，按正常规则继续

// CronTrigger 的 Misfire 策略
withMisfireHandlingInstructionFireAndProceed()  // 立即触发一次（最常用）
withMisfireHandlingInstructionDoNothing()       // 不触发，等待下一次正常时间
withMisfireHandlingInstructionIgnoreMisfires()  // 忽略 Misfire，按正常规则

// Quartz 默认的 Misfire 阈值是 60000 毫秒（60秒）
// 如果一个任务超过 60 秒没有被触发，就认为发生了 Misfire
// 这个值可以通过配置修改

// quartz.properties
org.quartz.jobStore.misfireThreshold = 60000

// ❌ 错误：Quartz 的 Cron 是从秒开始的6位表达式
"0 9 * * *"   // ❌ 这是5位，Linux cron 格式，不是 Quartz

// ✅ 正确：
"0 0 9 * * ?" // 每天9点整（秒 分 时 日 月 周）
"0 30 9 * * ?" // 每天9点30分

// ❌ 错误：把 JobDetail 当 Job 用
scheduler.deleteJob(new JobKey("myJob")); // 删的是 JobDetail，不是 Job
// 但 Job 类里的代码还在某处...

// ✅ 正确：理解两者的生命周期
// JobDetail 是持久化的任务定义
// Job 是每次触发时实例化的执行者

// ❌ 错误：支付回调任务，Misfire 时不应该重复触发
SimpleTrigger trigger = newTrigger()
    .withSchedule(
        simpleSchedule()
            .withIntervalInHours(1)
            .repeatForever()
            .withMisfireHandlingInstructionFireNow() // ❌ 重复触发！
    )
    .build();

// ✅ 正确：幂等处理
@DisallowConcurrentExecution
public class PaymentCallbackJob implements Job {
    @Override
    public void execute(JobExecutionContext context) throws JobExecutionException {
        JobDataMap dataMap = context.getJobDetail().getJobDataMap();
        String batchId = dataMap.getString("batchId");

        // 通过 Redis 锁保证幂等
        String lockKey = "payment:callback:" + batchId;
        Boolean acquired = redisTemplate.opsForValue().setIfAbsent(lockKey, "1", 1, TimeUnit.HOURS);
        if (!acquired) {
            return; // 已处理过，跳过
        }

        // 执行业务逻辑...
    }
}