Spring + Quartz 定時任務實戰：從 HelloWorld 到生產級配置最佳實踐

核心組件關係圖

SchedulerFactoryBean (Spring 管理調度器)
    │
    ├── Triggers (觸發器列表)
    │       ├── CronTriggerBean (Cron 表達式)
    │       └── SimpleTriggerBean (固定頻率/延遲)
    │
    └── JobDetails (作業詳情)
            └── MethodInvokingJobDetailFactoryBean (調用 Bean 方法)
                    ├── targetObject (目標 Bean)
                    ├── targetMethod (目標方法)
                    └── concurrent (是否允許並發)

最小化 HelloWorld

1. 業務 Bean

package com.task;
public class TestJob {
    public void execute() {
        System.out.println("業務邏輯執行: " + LocalDateTime.now());
    }
}

2. Spring XML 配置 (beans.xml)

3. 啟動測試

public class Test {
    public static void main(String[] args) {
        new ClassPathXmlApplicationContext("com/task/beans.xml");
        System.out.println("容器啟動，定時任務開始運行...");
        // 主線程不退出，觀察控制台輸出
    }
}

常見啟動錯誤與依賴包

NoClassDefFoundError: org/apache/commons/collections/SetUtils

原因：Quartz 1.x 依賴 `commons-collections`。
解決：加入 Maven 依賴：

    commons-collections
    commons-collections
    3.2.2


    org.quartz-scheduler
    quartz
    1.8.6 

生產級進階配置

1. 持久化 JobStore (集群/重啟不丟失)

    
    
    
    
        
            org.quartz.impl.jdbcjobstore.JobStoreTX
            org.quartz.impl.jdbcjobstore.StdJDBCDelegate
            QRTZ_
            true
            AUTO
        
    
    
        
    

需預先執行 Quartz 官方建表 SQL (`tables_mysql.sql` 等)。

2. 彈性 Cron 表達式外置配置

task.cron.expression=0 0 2 * * ?  # 每天凌晨 2 點

3. 異常處理與監控

• 實現 `JobExecutionListener` 記錄執行時間、異常堆棧。
• 整合 Micrometer/Prometheus 暴露 `quartz_job_duration_seconds`、`quartz_job_failure_total` 指標。
• 關鍵任務配置郵件/釘釘告警。

4. 避免「擁擠效應」

• `concurrent=false` 防止並發疊加。
• 長任務拆分為「主任務發布子任務到消息隊列」+「消費者異步處理」。
• 使用 `@DisallowConcurrentExecution` (Quartz 2.2+ 註解) 標記 Job 類。

Spring Boot 2.x/3.x 現代化寫法

@Configuration
@EnableScheduling // 啟用排程支援
public class QuartzConfig {

    @Bean
    public JobDetail jobDetail() {
        return JobBuilder.newJob(TestJob.class) // 實現 Job 介面
            .storeDurably()
            .build();
    }

    @Bean
    public Trigger trigger(JobDetail jobDetail) {
        return TriggerBuilder.newTrigger()
            .forJob(jobDetail)
            .withSchedule(CronScheduleBuilder.cronSchedule("0 0 2 * * ?"))
            .build();
    }
}

// 業務 Job 實現 Job 介面
@Component
public class TestJob implements Job {
    @Override
    public void execute(JobExecutionContext context) {
        // 業務邏輯
    }
}

總結

Spring + Quartz 以 `SchedulerFactoryBean` 為核心，`JobDetail` 定義「做什麼」，`Trigger` 定義「何時做」。掌握 **Cron 表達式、持久化 JobStore、集群模式、並發控制、監控告警** 五大支柱，即可構建企業級可靠定時任務系統。