Quartz 2.x Scheduler triggerJob 方法傳遞 JobDataMap 參數獲取詳解

問題背景

Quartz 2.x 中 Scheduler.triggerJob(JobKey, JobDataMap) 重載方法允許在手動觸發任務時傳遞額外參數。但開發者發現：在 Job 實現類的 execute(JobExecutionContext) 方法中，context.getMergedJobDataMap() 取不到傳入的參數，甚至 context 為 null。

原因分析

• triggerJob(JobKey, JobDataMap) 僅用於立即觸發一次執行，不會持久化 JobDetail。
• 傳入的 JobDataMap 會與 JobDetail 自帶的 JobDataMap 合併，但合併結果只在該次觸發的上下文中有效。
• 若 Job 類未正確實現 execute 簽名，或上下文傳遞異常，會導致取值失敗。

正確獲取參數的方式

public class MyJob implements Job {
    @Override
    public void execute(JobExecutionContext context) throws JobExecutionException {
        // 1. 合併後的完整 JobDataMap（含 JobDetail 定義 + triggerJob 傳入）
        JobDataMap mergedMap = context.getMergedJobDataMap();
        
        // 2. 僅 triggerJob 傳入的參數（不含 JobDetail 原有值）
        JobDataMap triggerMap = context.getTrigger().getJobDataMap();
        
        String param1 = mergedMap.getString("param1");
        String param2 = mergedMap.getString("param2");
        // 後續業務邏輯...
    }
}

常見誤區

1. 直接用 context.getJobDetail().getJobDataMap()：只能拿到 JobDetail 定義時的靜態值，不含動態傳入參數。
2. 誤以為 context 為 null：實際上 Quartz 保證 execute 時 context 不為 null；若為 null，請檢查 Job 類是否被多線程併發導致上下文丟失，或 Quartz 版本 Bug。
3. 參數名稱大小寫不一致：JobDataMap 區分大小寫，存取時需完全一致。

最佳實踐建議

• 優先使用 context.getMergedJobDataMap() 獲取完整參數集。
• 若需區分來源，可對比 context.getJobDetail().getJobDataMap() 與 context.getTrigger().getJobDataMap()。
• 單元測試時模擬 triggerJob 呼叫，驗證參數傳遞鏈路。

掌握合併機制，即可在 Quartz 動態觸發場景下靈活傳遞運行時參數。