281 lines
4.9 KiB
Markdown
281 lines
4.9 KiB
Markdown
# 定时任务调度服务 - API文档
|
||
|
||
## 概述
|
||
|
||
分布式定时任务调度服务，支持：
|
||
- 定时任务CRUD
|
||
- Cron表达式配置
|
||
- 任务执行记录
|
||
- 任务调度管理
|
||
- 失败重试机制
|
||
- 任务监控告警
|
||
- XXL-Job兼容接口
|
||
|
||
## 基础信息
|
||
|
||
- 基础路径: `http://localhost:8088`
|
||
- Swagger UI: `http://localhost:8088/swagger-ui.html`
|
||
- API文档: `http://localhost:8088/v3/api-docs`
|
||
|
||
## 认证
|
||
|
||
本服务暂未实现认证，生产环境请添加JWT或其他认证机制。
|
||
|
||
---
|
||
|
||
## 定时任务管理
|
||
|
||
### 创建任务
|
||
|
||
**POST** `/api/task`
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"taskName": "数据同步任务",
|
||
"description": "每日凌晨同步业务数据",
|
||
"taskGroup": "sync",
|
||
"cronExpression": "0 0 2 * * ?",
|
||
"taskClass": "dataSyncTask",
|
||
"methodName": "execute",
|
||
"taskParams": "{\"source\":\"erp\",\"target\":\"bi\"}",
|
||
"taskType": "BEAN",
|
||
"concurrent": true,
|
||
"maxRetries": 3,
|
||
"retryInterval": 60,
|
||
"timeout": 3600,
|
||
"alertEnabled": true,
|
||
"alertEmails": "admin@example.com",
|
||
"misfirePolicy": "DO_NOTHING",
|
||
"owner": "admin"
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"taskName": "数据同步任务",
|
||
"status": "DRAFT",
|
||
...
|
||
}
|
||
```
|
||
|
||
### 查询任务
|
||
|
||
**GET** `/api/task/{id}`
|
||
|
||
### 更新任务
|
||
|
||
**PUT** `/api/task/{id}`
|
||
|
||
### 删除任务
|
||
|
||
**DELETE** `/api/task/{id}`
|
||
|
||
### 分页查询任务
|
||
|
||
**GET** `/api/task/list`
|
||
|
||
| 参数 | 类型 | 必需 | 说明 |
|
||
|------|------|------|------|
|
||
| taskName | string | 否 | 任务名称(模糊查询) |
|
||
| taskGroup | string | 否 | 任务分组 |
|
||
| status | string | 否 | 状态 |
|
||
| page | int | 否 | 页码，默认1 |
|
||
| pageSize | int | 否 | 每页大小，默认20 |
|
||
|
||
### 启动任务
|
||
|
||
**POST** `/api/task/{id}/start`
|
||
|
||
### 停止任务
|
||
|
||
**POST** `/api/task/{id}/stop`
|
||
|
||
### 暂停任务
|
||
|
||
**POST** `/api/task/{id}/pause`
|
||
|
||
### 恢复任务
|
||
|
||
**POST** `/api/task/{id}/resume`
|
||
|
||
### 立即执行一次
|
||
|
||
**POST** `/api/task/{id}/execute`
|
||
|
||
### 获取运行中的任务
|
||
|
||
**GET** `/api/task/running`
|
||
|
||
### 获取任务统计
|
||
|
||
**GET** `/api/task/stats`
|
||
|
||
### 获取最近执行时间
|
||
|
||
**GET** `/api/task/{id}/next-fire-times?n=5`
|
||
|
||
### 验证Cron表达式
|
||
|
||
**GET** `/api/task/validate-cron?cronExpression=0/5 * * * * ?`
|
||
|
||
---
|
||
|
||
## 执行记录管理
|
||
|
||
### 查询任务执行记录
|
||
|
||
**GET** `/api/task/log/task/{taskId}`
|
||
|
||
### 查询所有执行记录
|
||
|
||
**GET** `/api/task/log/list`
|
||
|
||
### 条件查询
|
||
|
||
**GET** `/api/task/log/query`
|
||
|
||
| 参数 | 类型 | 必需 | 说明 |
|
||
|------|------|------|------|
|
||
| taskId | long | 否 | 任务ID |
|
||
| status | string | 否 | 执行状态 |
|
||
| startTime | string | 否 | 开始时间(yyyy-MM-dd HH:mm:ss) |
|
||
| endTime | string | 否 | 结束时间 |
|
||
|
||
### 根据批次号查询
|
||
|
||
**GET** `/api/task/log/batch/{batchNo}`
|
||
|
||
### 查询可重试的失败记录
|
||
|
||
**GET** `/api/task/log/retryable?maxRetries=3`
|
||
|
||
### 清理旧日志
|
||
|
||
**DELETE** `/api/task/log/cleanup?days=30`
|
||
|
||
### 获取今日统计
|
||
|
||
**GET** `/api/task/log/stats/today`
|
||
|
||
---
|
||
|
||
## XXL-Job兼容接口
|
||
|
||
### 获取所有任务
|
||
|
||
**GET** `/api/xxl-job/jobinfo/pageList`
|
||
|
||
### 添加任务
|
||
|
||
**POST** `/api/xxl-job/jobinfo/add`
|
||
|
||
### 更新任务
|
||
|
||
**POST** `/api/xxl-job/jobinfo/update`
|
||
|
||
### 删除任务
|
||
|
||
**POST** `/api/xxl-job/jobinfo/remove?id={id}`
|
||
|
||
### 停止任务
|
||
|
||
**POST** `/api/xxl-job/jobinfo/stop?id={id}`
|
||
|
||
### 启动任务
|
||
|
||
**POST** `/api/xxl-job/jobinfo/start?id={id}`
|
||
|
||
### 触发任务执行
|
||
|
||
**POST** `/api/xxl-job/jobinfo/trigger?id={id}`
|
||
|
||
### 获取任务分组
|
||
|
||
**GET** `/api/xxl-job/jobgroup/pageList`
|
||
|
||
---
|
||
|
||
## 健康检查
|
||
|
||
### 健康检查
|
||
|
||
**GET** `/actuator/health`
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"status": "UP",
|
||
"timestamp": "2024-01-01T12:00:00",
|
||
"components": {
|
||
"taskScheduler": {
|
||
"status": "UP",
|
||
"details": {
|
||
"runningTasks": 5
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Prometheus指标
|
||
|
||
**GET** `/actuator/prometheus`
|
||
|
||
---
|
||
|
||
## 任务类型
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| BEAN | Spring Bean任务，通过Bean名称调用 |
|
||
| CLASS | Java Class任务，通过反射调用 |
|
||
| XXL_JOB | XXL-Job兼容模式 |
|
||
|
||
## 任务状态
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| DRAFT | 草稿 |
|
||
| RUNNING | 运行中 |
|
||
| STOPPED | 已停止 |
|
||
| PAUSED | 暂停 |
|
||
| ERROR | 异常 |
|
||
| DELETED | 已删除 |
|
||
|
||
## 执行状态
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| RUNNING | 执行中 |
|
||
| SUCCESS | 成功 |
|
||
| FAILED | 失败 |
|
||
| RETRYING | 重试中 |
|
||
| TIMEOUT | 超时 |
|
||
| CANCELLED | 已取消 |
|
||
|
||
## Cron表达式示例
|
||
|
||
| 表达式 | 说明 |
|
||
|--------|------|
|
||
| `0/5 * * * * ?` | 每5秒执行 |
|
||
| `0 0 0 * * ?` | 每天零点执行 |
|
||
| `0 0 8 ? * MON-FRI` | 工作日早上8点执行 |
|
||
| `0 0/30 * * * ?` | 每30分钟执行 |
|
||
| `0 0 12 * * ?` | 每天中午12点执行 |
|
||
| `0 30 10 ? * 1-5` | 工作日早上10:30执行 |
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| TASK_NOT_FOUND | 任务不存在 |
|
||
| TASK_EXISTS | 任务已存在 |
|
||
| INVALID_CRON | 无效的Cron表达式 |
|
||
| EXECUTION_FAILED | 任务执行失败 |
|
||
| CANNOT_START | 无法启动任务 |
|
||
| CANNOT_STOP | 无法停止任务 |
|
||
| TASK_TIMEOUT | 任务执行超时 |
|