一、概述
调度模块负责系统的定时任务管理，基于 PowerJob 分布式任务调度引擎，统一管理所有需要定时执行的后台任务（如预警扫描、数据同步、报表生成等）。业务模块通过配置调度记录即可接入，无需自行管理调度逻辑。
二、整体架构
┌──────────────────────────────────────────────────────────────┐
│ 业务层 │
│ 预警模块 (warn) 数据同步 报表生成 ... (其他业务) │
│ │ │
│ │ schedule_id 关联 │
│ ▼ │
└──────────────────┬───────────────────────────────────────────┘
│
┌──────────────────▼───────────────────────────────────────────┐
│ 调度模块 (schedule) │
│ │
│ ScheduleController (CRUD / 启停 / 手动触发) │
│ │ │
│ ▼ │
│ ScheduleService (配置管理 / 作业注册 / 执行日志) │
│ │ │
│ ┌────┴─────┐ │
│ ▼ ▼ │
│ sys_schedule sys_schedule_log │
│ (配置表) (日志表) │
│ │ │
└─────────┼────────────────────────────────────────────────────┘
│
┌─────────▼────────────────────────────────────────────────────┐
│ PowerJob 分布式调度引擎 │
│ │
│ PowerJob Server (192.168.168.209:32544) │
│ │ │
│ ▼ │
│ PowerJob Worker (应用内嵌) │
│ │ │
│ ▼ ┌─────────────────┐ │
│ IScheduleProcessor ─────────────→ │ 业务处理器实现 │ │
│ (调度处理器接口) │ (WarnProcessor) │ │
│ └─────────────────┘ │
└──────────────────────────────────────────────────────────────┘
- PowerJob Server — 分布式调度中心，管理所有 Job 的注册、触发、分配
- PowerJob Worker — 嵌入应用，接收调度指令并执行
- 调度模块 — 封装 PowerJob，提供配置管理、日志记录、业务解耦
- 业务模块 — 实现处理器接口，通过
schedule_id 与调度关联
三、数据库设计
3.1 sys_schedule（调度配置表）
| 字段 |
类型 |
说明 |
id |
bigint |
主键 |
code |
varchar(250) |
调度编码（唯一标识） |
name |
varchar(250) |
调度名称 |
cron_expression |
varchar(50) |
Cron 表达式 |
class_name |
varchar(250) |
处理器全限定类名 |
job_id |
varchar(50) |
PowerJob 任务 ID（注册后回填） |
is_enabled |
varchar(50) |
是否启用 |
description |
varchar(500) |
描述 |
param |
text |
默认调度参数（JSON） |
3.2 sys_schedule_log（调度执行日志表）
| 字段 |
类型 |
说明 |
id |
bigint |
主键 |
schedule_id |
bigint |
关联调度 ID |
job_id |
varchar(50) |
PowerJob 任务 ID |
status |
varchar(50) |
运行状态（SUCCESS / FAILED） |
result |
text |
执行结果 |
error_message |
text |
错误信息 |
error_stack |
text |
错误堆栈 |
start_time |
datetime |
开始时间 |
end_time |
datetime |
结束时间 |
duration |
bigint |
耗时（毫秒） |
default_param |
text |
默认参数（冗余快照） |
run_param |
text |
本次运行独立参数 |
四、核心流程
4.1 调度注册流程
用户创建调度配置 (POST /sys/v1/schedule)
└→ ScheduleService.create()
├→ 持久化到 sys_schedule 表
├→ 构造 PowerJob 任务定义
│ ├→ JobName = schedule.code
│ ├→ Cron = schedule.cron_expression
│ ├→ Processor = 通用分发处理器
│ └→ JobParams = schedule.id (注入到上下文)
├→ 调用 PowerJob Client API 注册任务
├→ 回填 job_id 到 sys_schedule
└→ PowerJob Server 按 cron 定时触发
4.2 调度执行流程
PowerJob Server 触发 cron
└→ PowerJob Worker 接收任务
└→ 通用分发处理器 (ScheduleProcessorDispatcher)
├→ 从 JobParams 取出 schedule_id
├→ 查询 sys_schedule 获取配置
├→ 创建 sys_schedule_log 记录 (status=RUNNING)
├→ 反射实例化 class_name 指定的处理器
│ └→ IScheduleProcessor.execute(param)
│ └→ 业务处理器执行具体逻辑
├→ 更新 sys_schedule_log
│ ├→ status = SUCCESS / FAILED
│ ├→ result / error_message / error_stack
│ ├→ end_time / duration
└→ 返回执行结果给 PowerJob
4.3 生命周期管理
用户操作 PowerJob 状态 sys_schedule 状态
─────────────────────────────────────────────────────────────────
创建调度 注册 Job is_enabled = 1
停用调度 关闭 Job is_enabled = 0
启用调度 恢复 Job is_enabled = 1
删除调度 删除 Job 物理删除（级联日志）
手动触发 立即执行一次 记录日志
五、处理器接口
5.1 IScheduleProcessor
/**
* 调度任务处理器接口
* 所有需要定时执行的业务逻辑实现此接口
*/
public interface IScheduleProcessor {
/**
* 执行调度任务
*
* @param param 调度参数（来自 sys_schedule.param，JSON 格式）
* @return 执行结果（写入 sys_schedule_log.result）
*/
String execute(String param);
}
5.2 处理器注册方式
处理器通过 Spring Bean + class_name 全限定名方式定位：
- 调度配置中
class_name 存储处理器全限定类名
- 运行时反射获取 Spring 容器中的 Bean 实例
- 新业务只需：实现
IScheduleProcessor → 注册为 Spring Bean → 配置 class_name
5.3 通用分发处理器
@Component
public class ScheduleProcessorDispatcher {
public String dispatch(Long scheduleId) {
// 1. 查配置
ScheduleConfig config = scheduleService.getById(scheduleId);
// 2. 写日志
ScheduleLog log = scheduleService.createLog(config);
// 3. 反射获取处理器
IScheduleProcessor processor = getProcessor(config.getClassName());
// 4. 执行
String result = processor.execute(config.getParam());
// 5. 更新日志
scheduleService.updateLogSuccess(log, result);
return result;
}
}
六、PowerJob 配置
6.1 依赖
<dependency>
<groupId>tech.powerjob</groupId>
<artifactId>powerjob-worker-spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>tech.powerjob</groupId>
<artifactId>powerjob-client</artifactId>
<version>4.3.6</version>
</dependency>
6.2 配置项
powerjob:
worker:
server-address: 192.168.168.209:32544 # PowerJob Server 地址
enabled: false # 是否启用（开发/测试环境建议关闭）
akka-port: 27777 # 通信端口
appName: sys # 应用名（需在 PowerJob Server 注册）
七、sys-api 层接口
sys-api 是提供给其他微服务调用的接口层，调度模块在此暴露：
sys-api/
└── schedule/
├── processor/
│ └── IScheduleProcessor.java # 处理器接口（业务实现）
├── seed/
│ └── ScheduleSeedDTO.java # 调度初始化种子数据
└── listener/
└── ScheduleEventListener.java # 调度事件监听（预留）
7.1 Seed 机制
/**
* 调度种子数据
* 子服务启动时注册预定义的调度配置
*/
public class ScheduleSeedDTO {
private String code; // 调度编码
private String name; // 调度名称
private String cronExpression; // cron 表达式
private String className; // 处理器类名
private String param; // 默认参数
private String description; // 描述
}
八、状态枚举
ScheduleStatusEnum
| 值 |
说明 |
PENDING |
待执行 |
RUNNING |
执行中 |
SUCCESS |
执行成功 |
FAILED |
执行失败 |
ScheduleEnabledEnum
九、目录结构
schedule/
├── controller/
│ └── ScheduleController.java # 调度 CRUD API
├── service/
│ ├── ScheduleService.java # 调度配置管理
│ ├── ScheduleProcessorDispatcher.java # 通用分发处理器
│ └── ScheduleLogService.java # 执行日志管理
├── entity/
│ ├── Schedule.java # 对应 sys_schedule
│ └── ScheduleLog.java # 对应 sys_schedule_log
├── mapper/
│ ├── ScheduleMapper.java
│ └── ScheduleLogMapper.java
├── dto/
│ ├── ScheduleCreateDTO.java
│ ├── ScheduleUpdateDTO.java
│ ├── SchedulePageDTO.java
│ └── ScheduleViewDTO.java
├── enums/
│ ├── ScheduleStatusEnum.java
│ └── ScheduleEnabledEnum.java
├── convert/
│ └── ScheduleConvert.java # MapStruct
├── listener/
│ └── ScheduleEventListener.java # 预留：PowerJob 事件监听
└── demo/
└── DemoProcessor.java # 演示处理器
