任务执行与调度

引用文件

本文引用的文件

简介

本文件面向“任务执行与调度系统”，围绕任务调度机制（一次性、周期性、定时）、任务生命周期（创建、参数校验、执行状态跟踪、结果反馈）、监控与告警（进度、异常、重试、超时）、任务与设备关联（按设备分组、筛选、优先级）、任务API与批量能力、以及与Kafka的消息队列集成与异步处理进行系统化说明。文档同时提供架构图、序列图、流程图与最佳实践建议，帮助技术与非技术读者快速理解并高效运维。

项目结构

任务模块采用多模块聚合结构，核心位于 yudao-module-task，包含API与业务实现两部分；基础设施模块提供定时任务表与日志表；设备模块提供心跳与任务下发能力；框架层提供Kafka、WebSocket、通用枚举与MQ配置等支撑。

Mermaid Diagram Code:

graph TB
subgraph "任务模块"
API["yudao-module-task-api"]
Biz["yudao-module-task-biz"]
end
Infra["yudao-module-infra"]
Device["yudao-module-device"]
Rule["yudao-module-rule"]
Framework["yudao-framework"]
API --> Biz
Biz --> Infra
Biz --> Device
Biz --> Rule
Biz --> Framework

图表来源

yudao-module-task/pom.xml

章节来源

yudao-module-task/pom.xml

核心组件

控制器与服务
- 管理端控制器：负责任务的创建、更新、删除、分页查询、导出、审批流操作等。
- 任务服务接口与实现：支持带/不带BPM两种模式，提供任务分页、设备关联、版本号更新、取消更新等能力。
数据对象与持久层
- 任务DO：定义任务字段、状态、类型、版本号、流程状态等。
- Mapper：封装分页查询、条件过滤、角色权限关联查询等。
缓存层
- 任务缓存、区域缓存、规则缓存、型号缓存：基于Redis的随机过期与穿透保护策略，提升读性能。
BPM与变量
- BPM服务接口与实现：创建/取消流程、处理流程结果。
- BPM变量：封装任务提交审批所需的业务变量。
设备与心跳
- 心跳返回结构：包含任务列表，驱动设备侧任务下发。
MQ与WebSocket
- Kafka自动配置：统一错误处理、重试、不可重试异常、日志输出。
- Kafka属性配置：主题命名规范。
- WebSocket Kafka消费者：跨节点广播消息发送。
异步与线程池
- 异步消息状态枚举：统一状态管理。
- 导出拒绝策略：队列满时抛出服务异常，提示用户稍后再试。

章节来源

架构总览

任务执行与调度系统由“控制层-服务层-数据访问层-缓存层-设备层-消息队列”构成，形成闭环：管理员通过控制台创建/更新任务，服务层完成参数校验与状态流转，持久层落库，缓存层加速读取；设备侧通过心跳接口获取任务并执行；MQ负责异步解耦与广播；BPM提供审批流能力。

Mermaid Diagram Code:

graph TB
Admin["管理端控制台"] --> Ctl["任务控制器<br/>TaskController"]
Ctl --> Svc["任务服务<br/>TaskService/TaskNoBpmServiceImpl"]
Svc --> Mapper["任务Mapper<br/>TaskMapper"]
Svc --> Cache["Redis缓存<br/>TaskRedisDAO/Region/Model/Rule"]
Svc --> BPM["BPM服务<br/>TaskBpmService"]
Svc --> Device["设备心跳/任务下发<br/>DeviceHeartBeatRes"]
Svc --> MQ["Kafka/消息队列<br/>KafkaAutoConfiguration/KafkaProperties"]
MQ --> WS["WebSocket广播<br/>KafkaWebSocketMessageConsumer"]
Svc --> Log["定时任务日志表<br/>infra_job_log"]

图表来源

详细组件分析

任务生命周期与调度策略

一次性任务：通过控制器创建，服务层完成参数校验与状态设置，持久化后可立即下发给设备。
周期性/定时任务：系统提供定时任务表与日志表，结合框架层Quartz或Spring Task（仓库中体现为定时任务基础设施），可将任务执行纳入调度器统一管理。
执行时机控制：设备心跳接口返回任务列表，驱动设备侧按需执行；也可通过MQ异步触发。

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理员"
participant Ctrl as "TaskController"
participant Svc as "TaskService"
participant DB as "TaskMapper/DB"
participant Dev as "设备心跳"
participant MQ as "Kafka"
Admin->>Ctrl : 创建任务
Ctrl->>Svc : createDevice()
Svc->>DB : 写入任务记录
DB-->>Svc : 返回任务ID
Svc-->>Ctrl : 返回ID
Ctrl-->>Admin : 成功
Dev->>Svc : 心跳请求
Svc-->>Dev : 返回任务列表
Dev->>Dev : 下发并执行任务
Svc->>MQ : 异步消息如需
MQ-->>Svc : 消费确认/重试

图表来源

章节来源

任务与设备关联与筛选

按设备分组：通过区域缓存与型号缓存，将任务与区域/型号建立关联，查询时可快速定位目标设备集合。
按条件筛选：任务DO包含筛选类型（品牌/机型、渠道、MAC导入），Mapper提供多条件分页查询。
任务下发：设备心跳返回任务列表，驱动设备侧执行。

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> LoadTask["加载任务DO"]
LoadTask --> FilterType{"筛选类型"}
FilterType --> |品牌/机型| ModelCache["型号缓存命中"]
FilterType --> |渠道| RegionCache["区域缓存命中"]
FilterType --> |MAC导入| MACList["MAC列表"]
ModelCache --> BuildSet["构建设备集合"]
RegionCache --> BuildSet
MACList --> BuildSet
BuildSet --> ReturnTasks["返回任务列表"]
ReturnTasks --> End(["结束"])

图表来源

章节来源

任务监控与告警、重试与超时

监控与日志：定时任务表与日志表记录任务执行状态、耗时、结果等，便于审计与回溯。
异常与重试：Kafka自动配置提供统一错误处理、重试次数与不可重试异常分类，避免消息堆积。
超时处理：BPM任务超时处理（提醒/自动同意/自动拒绝）可借鉴到任务执行超时场景。
状态管理：异步消息状态枚举统一管理待处理、成功、失败、忽略等状态。

Mermaid Diagram Code:

flowchart TD
Consume["消费消息"] --> Try["尝试处理"]
Try --> Ok{"处理成功?"}
Ok --> |是| Ack["确认消费"]
Ok --> |否| Retry["重试计数+1"]
Retry --> Max{"超过最大重试?"}
Max --> |否| Backoff["退避等待"]
Max --> |是| Dead["死信/告警"]
Ack --> End["结束"]
Backoff --> Consume
Dead --> End

图表来源

章节来源

任务API与批量操作

管理端API
- 创建：POST /task/task/create
- 更新：PUT /task/task/update
- 删除：DELETE /task/task/delete
- 查询：GET /task/task/get
- 分页：GET /task/task/page
- 导出：GET /task/task/export-excel
- 审批流：PUT /task/task/bpm/create、PUT /task/task/bpm/cancel、PUT /task/task/cancel、PUT /task/task/bpm/cancel-all
批量能力
- 分页查询支持角色权限过滤与设备数量统计联动。
- 导出接口支持无分页导出（设置页大小为不限）。
- 缓存穿透保护：任务缓存提供空值短命缓存，避免缓存穿透。

章节来源

与Kafka的集成与异步处理

主题配置：KafkaProperties定义了设备变更、应用安装列表、黑名单回调等主题。
消费端：Kafka自动配置提供统一错误处理、重试与不可重试异常，日志记录Topic/分区/偏移等上下文。
广播：WebSocket Kafka消费者通过不同消费者组ID实现广播消费，向在线会话推送消息。

Mermaid Diagram Code:

sequenceDiagram
participant Producer as "生产者"
participant Kafka as "Kafka"
participant Consumer as "Kafka消费者"
participant WS as "WebSocket广播"
Producer->>Kafka : 发送消息
Kafka-->>Consumer : 拉取消息
Consumer->>Consumer : 重试/失败处理
Consumer->>WS : 广播消息
WS-->>WS : 推送给客户端

图表来源

章节来源

BPM与审批流

BPM服务接口：创建/取消流程、处理流程结果。
BPM变量：封装业务类型、原因、渠道名称等。
任务BPM实现：统计变更数量、生成审批原因、处理流程事件。

Mermaid Diagram Code:

classDiagram
class TaskBpmService {
+createBpm(userId, taskId)
+cancelBpm(userId, taskId)
+handleBpmResult(event)
}
class TaskBpmServiceImpl {
+createBpm(...)
+cancelBpm(...)
+handleBpmResult(...)
}
class TaskBpmVariable {
+String businessBpmReason
+String[] channelNames
+String businessBpmType
}
TaskBpmService <|.. TaskBpmServiceImpl
TaskBpmVariable --> TaskBpmServiceImpl : "使用"

图表来源

章节来源

依赖分析

控制器依赖服务与权限API、规则业务API，实现权限过滤与设备数量统计联动。
服务层依赖Mapper与各类DAO（Redis缓存），实现数据读写与缓存一致性。
设备层通过心跳返回任务列表，驱动任务下发。
MQ层提供统一错误处理与重试策略，确保消息可靠投递。

Mermaid Diagram Code:

graph LR
Ctrl["TaskController"] --> Svc["TaskService"]
Svc --> Mapper["TaskMapper"]
Svc --> Cache["Redis DAO"]
Svc --> BPM["TaskBpmService"]
Svc --> Dev["DeviceHeartBeatRes"]
Svc --> MQ["KafkaAutoConfiguration"]
Ctrl --> Perm["PermissionApi"]
Ctrl --> RuleBiz["RuleBusinessApi"]

图表来源

章节来源

性能考量

缓存策略：Redis缓存任务、区域、型号、规则，随机过期与空值短命缓存降低热点压力与穿透风险。
分页与权限：Mapper支持角色权限内联查询与去重，避免越权与重复数据。
导出限流：导出拒绝策略在队列满时直接抛出异常，避免阻塞线程池。
MQ可靠性：统一错误处理与重试，减少消息堆积与重复消费。

章节来源

故障排查指南

Kafka消费失败
- 现象：消费异常、重试日志、不可重试异常。
- 排查：检查Topic/分区/偏移、消息体、异常链；确认不可重试异常类型。
任务下发异常
- 现象：设备心跳未返回任务或任务列表为空。
- 排查：确认任务筛选类型与缓存命中情况；检查型号/区域/规则缓存是否正确。
导出失败
- 现象：导出被拒绝，提示队列已满。
- 排查：查看线程池饱和与拒绝策略；稍后重试或扩容节点。
BPM流程异常
- 现象：流程状态异常或超时未处理。
- 排查：核对流程事件与处理逻辑；必要时手动干预。

章节来源

结论

本系统通过清晰的分层设计与完善的缓存、MQ、BPM与定时任务基础设施，实现了任务的全生命周期管理与高可用执行。建议在生产环境中持续完善监控指标、告警阈值与自动化恢复策略，并结合业务增长逐步扩展缓存与MQ容量，确保任务调度的稳定性与可扩展性。

附录

任务状态与类型常量参考：任务DO中定义了任务类型、筛选类型、状态等常量，便于统一管理。
SQL脚本：定时任务表与日志表结构，便于部署与审计。

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

任务生命周期与调度策略​

任务与设备关联与筛选​

任务监控与告警、重试与超时​

任务API与批量操作​

与Kafka的集成与异步处理​

BPM与审批流​

依赖分析​

性能考量​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

任务生命周期与调度策略

任务与设备关联与筛选

任务监控与告警、重试与超时

任务API与批量操作

与Kafka的集成与异步处理

BPM与审批流

依赖分析

性能考量

故障排查指南

结论

附录