erp-java/services/scheduled-task-service/doc/API.md

定时任务调度服务 - 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

请求体:

{
  "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"
}

响应:

{
  "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

响应:

{
  "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	任务执行超时