Spring 整合 Quartz 定時任務完整配置指南：從 XML 到常見坑點避雷

依賴坐標（Maven）

<dependencies>
    <!-- Quartz 核心 -->
    <dependency>
        <groupId>org.quartz-scheduler</groupId>
        <artifactId>quartz</artifactId>
        <version>2.3.2</version>  <!-- 建議升級至 2.x -->
    </dependency>

    <!-- Spring Context Support（含 Quartz 整合類） -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context-support</artifactId>
        <version>5.3.25</version>
    </dependency>
</dependencies>

註：原文使用 1.8.5 版本屬於舊世代，生產環境建議升級至 2.3.x，API 有變動但核心概念一致。

核心 Bean 定義（XML 風格）

<beans xmlns="https://www.springframework.org/schema/beans"
       xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="https://www.springframework.org/schema/beans
       https://www.springframework.org/schema/beans/spring-beans.xsd">

    <!-- 1. 任務執行類 -->
    <bean id="rewardTask" class="com.example.quartz.GenerateRewardListTask"/>

    <!-- 2. JobDetail：封裝目標對象與方法 -->
    <bean id="jobDetail" class="org.springframework.scheduling.quartz.MethodInvokingJobDetailFactoryBean">
        <property name="targetObject" ref="rewardTask"/>
        <property name="targetMethod" value="generate"/>
        <property name="concurrent" value="false"/> <!-- 禁止並發執行 -->
    </bean>

    <!-- 3. CronTrigger：定義執行時間表達式 -->
    <bean id="cronTrigger" class="org.springframework.scheduling.quartz.CronTriggerFactoryBean">
        <property name="jobDetail" ref="jobDetail"/>
        <!-- 每天 23:00 執行 -->
        <property name="cronExpression" value="0 0 23 * * ?"/>
        <!-- 若需指定年份：0 0 23 10 11 ? 2016（僅 2016-11-10 23:00） -->
    </bean>

    <!-- 4. SchedulerFactoryBean：統一管理觸發器 -->
    <bean class="org.springframework.scheduling.quartz.SchedulerFactoryBean">
        <property name="triggers">
            <list><ref bean="cronTrigger"/></list>
        </property>
        <property name="overwriteExistingJobs" value="true"/>
        <property name="startupDelay" value="30"/> <!-- 啟動 30s 後啟動調度，避免搶資源 -->
    </bean>
</beans>

任務執行類範例

@Slf4j
public class GenerateRewardListTask {
    @Autowired private GiftReceiveRecordService giftReceiveRecordService;

    public void generate() {
        try {
            log.info("開始生成獎勵名單...");
            giftReceiveRecordService.generateRewardMember();
            log.info("獎勵名單生成完成");
        } catch (Exception e) {
            log.error("定時任務異常", e);
            // 建議拋出 JobExecutionException 讓 Quartz 記錄失敗狀態
            throw new JobExecutionException(e);
        }
    }
}

Cron 表達式速查

格式：秒 分 時 日 月 周 [年]
*  通配符
?  不指定值（日/周二擇一）
/  遞增（0/15 = 每 15 秒）
-  範圍
,  列舉

常用範例：
0 0 2 * * ?       每天 02:00
0 0/5 * * * ?     每 5 分鐘
0 10,44 14 ? 3 WED  三月每週三 14:10 和 14:44
0 0 23 10 11 ? 2016  2016-11-10 23:00 單次

四大避雷指南

現代化替代方案

• Spring Boot 2.x+：@EnableScheduling + @Scheduled(cron = "0 0 23 * * ?") 即可，無需 XML。
• XXL-JOB / PowerJob：分佈式任務調度平台，支援分片廣播、故障轉移、可視化管理，適合微服務架構。

總結

Spring + Quartz XML 配置核心四件套：Task Bean → JobDetail → CronTrigger → SchedulerFactoryBean。牢記「不寫死年份、不改系統時間測試、集群必開 isClustered」，即可避開 90% 生產事故。