2. Quartz 核心概念回顾：Job、Trigger、Scheduler、JobDetail、JobDataMap

在深入 OpenAPI 适配方案之前，必须重新建立对 Quartz 调度引擎核心抽象的共同理解。Quartz 的体系围绕五个核心概念构建：Job（任务）、Trigger（触发器）、Scheduler（调度器）、JobDetail（任务详情）和 JobDataMap（任务数据映射）。这五个概念构成了 Quartz 调度的最小完整单元，也是后续 API 设计、迁移映射和兼容性测试的基础。

2.1 核心概念关系总览

下图展示了五个核心概念之间的静态关系与协作流程。Scheduler 作为调度中枢，管理 JobDetail 与 Trigger 的注册与绑定；JobDetail 描述任务类型与实例元数据；Trigger 定义触发时间规则；JobDataMap 则作为数据载体在 Job 与 Trigger 之间传递参数。

Quartz 核心概念关系图 Quartz 核心概念关系图 Scheduler 调度器（核心引擎） JobDetail 任务详情 / 元数据 Job 任务执行逻辑 Trigger 触发器（时间规则） JobDataMap 任务数据映射 注册 注册 实例化 关联 JobDataMap 可附加到 JobDetail 核心协作流程 Scheduler 绑定 JobDetail + Trigger → 到达触发时间 → 实例化 Job → 执行 execute()

2.2 概念定义与职责

概念 接口 / 类 核心职责 生命周期
Job org.quartz.Job 定义任务执行逻辑，唯一方法 execute(JobExecutionContext) 每次触发时实例化，执行后销毁（默认）
JobDetail org.quartz.JobDetail 描述 Job 的元数据：名称、组、类、持久化策略、关联的 JobDataMap 持久化存储，与 Scheduler 生命周期一致
Trigger org.quartz.Trigger 定义任务触发的时间规则（cron、简单间隔、日历排除等） 可重复使用，可暂停/恢复/删除
Scheduler org.quartz.Scheduler 调度引擎核心：管理 JobDetail 与 Trigger 的注册、绑定、启动、暂停、关闭 应用级单例，启动后持续运行
JobDataMap org.quartz.JobDataMap 继承 java.util.Map，存储任务执行所需的配置参数和状态数据 随 JobDetail 或 Trigger 持久化

2.3 Job 与 JobDetail：任务定义与实例化

Job 接口是 Quartz 中最基础的执行单元。开发者实现 execute() 方法，编写具体的业务逻辑。但 Quartz 不会直接操作 Job 类，而是通过 JobDetail 来间接管理。

关键设计原则： JobDetail 是 Job 的“描述符”，而非 Job 实例本身。Quartz 在每次触发时，通过 JobDetail 中存储的 jobClass 反射创建新的 Job 实例。这种设计实现了任务元数据与执行逻辑的分离，也支持同一个 Job 类被多个 JobDetail 以不同参数复用。

// 定义 Job 实现类
public class SendNotificationJob implements Job {
    @Override
    public void execute(JobExecutionContext context) throws JobExecutionException {
        JobDataMap dataMap = context.getJobDetail().getJobDataMap();
        String recipient = dataMap.getString("recipient");
        String template = dataMap.getString("template");
        // 执行发送通知逻辑
        System.out.println("Sending to: " + recipient + " with template: " + template);
    }
}

// 创建 JobDetail，绑定 Job 类并注入参数
JobDetail jobDetail = JobBuilder.newJob(SendNotificationJob.class)
    .withIdentity("notificationJob", "group1")
    .usingJobData("recipient", "user@example.com")
    .usingJobData("template", "welcome")
    .storeDurably()
    .build();

2.4 Trigger：时间规则的表达

Trigger 负责定义“何时执行”。Quartz 提供两种主要触发器类型，以及一个用于日历排除的辅助机制。

触发器类型 适用场景 核心属性 示例
CronTrigger 复杂的日历时间表达式（秒、分、时、日、月、周、年） cronExpression、timeZone 0 0 8 * * ?（每天 8:00）
SimpleTrigger 固定间隔重复执行，或指定次数/总时长 repeatInterval、repeatCount 每 5 分钟执行一次，共 10 次
CalendarIntervalTrigger 按日历单位（天、月、年）间隔执行，自动处理夏令时 repeatIntervalUnit、repeatInterval 每月第一天执行

迁移适配提示： 在 OpenAPI 适配方案中，CronTrigger 是最常见的迁移目标。需要特别注意 cron 表达式的秒位兼容性（Quartz 支持秒级，部分目标平台不支持）以及时区处理差异。

2.5 JobDataMap：参数传递与状态共享

JobDataMap 是 Quartz 中唯一内置的上下文数据传递机制。它本质上是一个 Map<String, Object>，但增加了对基本类型和字符串的便捷存取方法。

JobDataMap 有两种挂载位置：

  • JobDetail 级别： 通过 JobBuilder.usingJobData() 设置，在 Job 执行时通过 context.getJobDetail().getJobDataMap() 获取。适用于任务本身的固定配置参数。
  • Trigger 级别： 通过 TriggerBuilder.usingJobData() 设置，在 Job 执行时通过 context.getTrigger().getJobDataMap() 获取。适用于每次触发时可能变化的参数（如执行批次号）。
// 在 Trigger 级别设置动态参数
Trigger trigger = TriggerBuilder.newTrigger()
    .withIdentity("myTrigger", "group1")
    .withSchedule(CronScheduleBuilder.cronSchedule("0 0/5 * * * ?"))
    .usingJobData("batchId", UUID.randomUUID().toString())
    .build();

// Job 执行时合并两个 JobDataMap
public void execute(JobExecutionContext context) {
    JobDataMap mergedMap = context.getMergedJobDataMap();
    // mergedMap 包含 JobDetail 和 Trigger 两层的所有参数
    // Trigger 级别的参数会覆盖 JobDetail 级别的同名参数
}

2.6 Scheduler：调度中枢

Scheduler 是 Quartz 的门面接口，负责所有调度操作的统一入口。其核心生命周期与操作如下：

Scheduler 核心操作流程 Scheduler 核心操作流程 start() scheduleJob() pauseJob() shutdown() Scheduler 关键特性 • 支持 Job 与 Trigger 的独立注册与动态绑定 • 提供暂停/恢复/删除单个 Job 或整个组的能力 • 支持持久化（JDBC JobStore）与内存（RAMJobStore）两种存储模式

迁移风险提示： 在 OpenAPI 适配过程中，Scheduler 的 scheduleJob() 和 rescheduleJob() 是最常被调用的接口。需要确保目标平台对 Trigger 替换操作的原子性支持，避免在迁移过程中出现重复触发或漏触发。

2.7 概念对比：Quartz 与通用调度模型

为了帮助团队建立统一的认知基线，下表将 Quartz 的五个核心概念映射到通用调度模型中的对应角色：

Quartz 概念 通用调度模型 类比说明
Job 任务处理器 / Worker 类似 Java 的 Runnable，只关心“做什么”
JobDetail 任务定义 / 任务描述符 类似数据库中的任务元数据表，记录任务类型和参数
Trigger 调度规则 / 定时策略 类似 Linux cron 表达式，但更丰富（支持日历排除）
Scheduler 调度引擎 / 任务管理器 类似操作系统的进程调度器，负责任务生命周期管理
JobDataMap 上下文参数 / 配置字典 类似 HTTP 请求的 Header + Body，传递执行上下文

2.8 本章小结

Quartz 的五个核心概念构成了一个完整且解耦的任务调度模型：Job 定义执行逻辑，JobDetail 封装任务元数据，Trigger 控制触发时机，Scheduler 统一管理生命周期，JobDataMap 提供灵活的参数传递通道。在后续的 OpenAPI 适配方案中，每一个 API 端点都将围绕这五个概念进行设计，确保迁移后的平台在语义上保持与 Quartz 的高度兼容。

← 上一章 📖 返回目录 下一章 →