Quartz 定時任務框架核心原理與 Spring Boot 整合實戰

Quartz 核心組件架構

獨立 Java 應用快速啟動

public class SimpleJob implements Job {
    @Override
    public void execute(JobExecutionContext ctx) {
        String name = ctx.getJobDetail().getJobDataMap().getString("name");
        System.out.println("Job 執行: " + name + " @ " + new Date());
    }
}

public class StandaloneDemo {
    public static void main(String[] args) throws SchedulerException {
        Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();

        JobDetail job = JobBuilder.newJob(SimpleJob.class)
            .withIdentity("demoJob", "group1")
            .usingJobData("name", "獨立模式測試")
            .build();

        Trigger trigger = TriggerBuilder.newTrigger()
            .withIdentity("demoTrigger", "group1")
            .startNow()
            .withSchedule(SimpleScheduleBuilder.simpleSchedule()
                .withIntervalInSeconds(3)
                .repeatForever())
            .build();

        scheduler.scheduleJob(job, trigger);
        scheduler.start();
        System.out.println("調度器已啟動，按 Ctrl+C 停止");
    }
}

Web 環境部署：Servlet 初始化方案

<!-- web.xml -->
<servlet>
    <servlet-name>QuartzInitializer</servlet-name>
    <servlet-class>org.quartz.ee.servlet.QuartzInitializerServlet</servlet-class>
    <init-param>
        <param-name>config-file</param-name>
        <param-value>quartz.properties</param-value>
    </init-param>
    <init-param>
        <param-name>shutdown-on-unload</param-name>
        <param-value>true</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

quartz.properties 關鍵配置

# 調度器基礎
org.quartz.scheduler.instanceName = MyScheduler
org.quartz.scheduler.instanceId = AUTO

# 線程池
org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool
org.quartz.threadPool.threadCount = 10
org.quartz.threadPool.threadPriority = 5

# 持久化到數據庫（集群必備）
org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreTX
org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.StdJDBCDelegate
org.quartz.jobStore.dataSource = myDS
org.quartz.jobStore.tablePrefix = QRTZ_
org.quartz.jobStore.isClustered = true
org.quartz.jobStore.clusterCheckinInterval = 20000

# 數據源
org.quartz.dataSource.myDS.driver = com.mysql.cj.jdbc.Driver
org.quartz.dataSource.myDS.URL = jdbc:mysql://localhost:3306/quartz?useSSL=false
org.quartz.dataSource.myDS.user = quartz
org.quartz.dataSource.myDS.password = password
org.quartz.dataSource.myDS.maxConnections = 20

# XML 任務自動加載插件
org.quartz.plugin.jobInitializer.class = org.quartz.plugins.xml.JobInitializationPlugin
org.quartz.plugin.jobInitializer.fileName = quartz_jobs.xml
org.quartz.plugin.jobInitializer.overWriteExistingJobs = true
org.quartz.plugin.jobInitializer.failOnFileNotFound = false

quartz_jobs.xml 宣告式任務定義

<?xml version="1.0" encoding="UTF-8"?>
<quartz>
  <job>
    <job-detail>
      <name>reportJob</name>
      <group>reportGroup</group>
      <job-class>com.example.ReportJob</job-class>
      <job-data-map>
        <entry><key>templateId</key><value>TPL_001</value></entry>
      </job-data-map>
    </job-detail>
    <trigger>
      <cron>
        <name>reportTrigger</name>
        <group>reportGroup</group>
        <job-name>reportJob</job-name>
        <job-group>reportGroup</job-group>
        <cron-expression>0 0 8 * * ?</cron-expression>  <!-- 每天 08:00 -->
      </cron>
    </trigger>
  </job>
</quartz>

Spring Boot 2.x/3.x 整合最佳實踐

@Configuration
public class QuartzConfig {
    @Bean
    public SchedulerFactoryBean schedulerFactoryBean(DataSource dataSource) {
        SchedulerFactoryBean factory = new SchedulerFactoryBean();
        factory.setDataSource(dataSource);
        factory.setOverwriteExistingJobs(true);
        factory.setAutoStartup(true);
        factory.setStartupDelay(30); // 應用啟動 30s 後啟動調度器

        // 載入 XML 任務定義
        factory.setConfigLocation(new ClassPathResource("quartz_jobs.xml"));

        // 集群屬性
        Properties props = new Properties();
        props.setProperty("org.quartz.jobStore.isClustered", "true");
        factory.setQuartzProperties(props);
        return factory;
    }
}

Spring 管理的 Job 寫法

@Component
public class ReportJob extends QuartzJobBean { // 支援 @Autowired 注入 Spring Bean
    @Autowired private ReportService reportService;

    @Override
    protected void executeInternal(JobExecutionContext ctx) {
        String templateId = ctx.getMergedJobDataMap().getString("templateId");
        reportService.generateDailyReport(templateId);
    }
}

Cron 表達式速查

常用範例：0 0 12 * * ? (每天中午12點) | 0 0/5 * * * ? (每5分鐘) | 0 0 0 ? * MON (每周一午夜)

總結

Quartz 以 Job/Trigger/JobDetail 解耦業務與調度，CronTrigger 表達式支撐複雜時間規則，JDBCJobStore + 集群模式 保證高可用。Spring Boot 整合後，配合 @Component Job 與 SchedulerFactoryBean，即可獲得企業級定時任務平台能力：持久化、集群、動態增刪改、監控追蹤。