4、任务调度平台核心API契约设计

API契约是压力测试与性能调优的基准。本章定义任务调度平台六大核心接口的OpenAPI 3.0契约，包括请求/响应结构、错误码体系及标准化响应格式。所有接口遵循RESTful风格，统一使用JSON作为数据交换格式。

4.1 接口概览与端点清单

平台核心API共分为五类，覆盖任务全生命周期管理。下表列出所有端点及简要说明：

接口分类	HTTP方法	端点路径	功能说明
任务CRUD	POST	/api/v1/tasks	创建任务
任务CRUD	GET	/api/v1/tasks/{taskId}	查询任务详情
任务CRUD	PUT	/api/v1/tasks/{taskId}	更新任务配置
任务CRUD	DELETE	/api/v1/tasks/{taskId}	删除任务
任务触发与停止	POST	/api/v1/tasks/{taskId}/trigger	手动触发任务执行
任务触发与停止	POST	/api/v1/tasks/{taskId}/stop	停止正在运行的任务
任务状态查询	GET	/api/v1/tasks/{taskId}/status	查询任务当前运行状态
调度日志	GET	/api/v1/tasks/{taskId}/logs	查询任务调度日志列表
调度日志	GET	/api/v1/tasks/{taskId}/logs/{logId}	查询单条调度日志详情

4.2 任务CRUD接口契约

任务CRUD接口是平台最基础、调用频率最高的接口组。以下以创建任务和更新任务为例，展示完整的请求/响应结构。

4.2.1 创建任务 (POST /api/v1/tasks)

请求体 (application/json)：

{
  "taskName": "数据同步任务-订单库",
  "taskType": "DATA_SYNC",
  "cronExpression": "0 0/5 * * * ?",
  "priority": 5,
  "timeoutSeconds": 300,
  "retryCount": 3,
  "retryIntervalSeconds": 30,
  "params": {
    "sourceDb": "order_db",
    "targetDb": "dw_db",
    "tableName": "orders"
  },
  "description": "每5分钟同步订单数据到数据仓库"
}

成功响应 (201 Created)：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "tsk-20250321-001",
    "taskName": "数据同步任务-订单库",
    "status": "STOPPED",
    "createdAt": "2025-03-21T10:30:00+08:00"
  }
}

4.2.2 更新任务 (PUT /api/v1/tasks/{taskId})

请求体： 支持部分更新，仅需传入需要修改的字段。

{
  "cronExpression": "0 0/10 * * * ?",
  "priority": 8,
  "timeoutSeconds": 600
}

成功响应 (200 OK)：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "tsk-20250321-001",
    "updatedAt": "2025-03-21T11:00:00+08:00"
  }
}

4.3 任务触发与停止接口契约

触发与停止接口是任务调度平台的核心控制面，直接影响调度引擎的状态机流转。这两个接口对响应时间要求极高，通常需要在毫秒级完成指令下发。

4.3.1 手动触发任务 (POST /api/v1/tasks/{taskId}/trigger)

请求体： 可选，用于覆盖任务默认参数。

{
  "overrideParams": {
    "sourceDb": "order_db_backup",
    "batchSize": 5000
  },
  "triggerReason": "MANUAL_RETRY"
}

成功响应 (202 Accepted)：

{
  "code": 0,
  "message": "accepted",
  "data": {
    "taskId": "tsk-20250321-001",
    "executionId": "exec-20250321-001",
    "estimatedStartTime": "2025-03-21T11:05:00+08:00"
  }
}

4.3.2 停止任务 (POST /api/v1/tasks/{taskId}/stop)

请求体： 无请求体。

成功响应 (200 OK)：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "tsk-20250321-001",
    "executionId": "exec-20250321-001",
    "previousStatus": "RUNNING",
    "currentStatus": "STOPPING"
  }
}

4.4 任务状态查询与调度日志接口契约

状态查询与日志接口属于读密集型操作，是压测中模拟监控面板和运维工具调用的主要目标。

4.4.1 任务状态查询 (GET /api/v1/tasks/{taskId}/status)

查询参数： 无。

成功响应 (200 OK)：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "tsk-20250321-001",
    "status": "RUNNING",
    "currentExecutionId": "exec-20250321-001",
    "lastRunTime": "2025-03-21T11:00:00+08:00",
    "nextRunTime": "2025-03-21T11:05:00+08:00",
    "runningDurationSeconds": 120
  }
}

4.4.2 调度日志查询 (GET /api/v1/tasks/{taskId}/logs)

查询参数：

参数名	类型	必填	说明	默认值
pageNum	integer	否	页码，从1开始	1
pageSize	integer	否	每页条数，最大100	20
status	string	否	按执行状态过滤：SUCCESS/FAILED/RUNNING	全部
startTime	string	否	开始时间范围，ISO8601格式	无
endTime	string	否	结束时间范围，ISO8601格式	无

成功响应 (200 OK)：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 156,
    "pageNum": 1,
    "pageSize": 20,
    "records": [
      {
        "logId": "log-20250321-001",
        "executionId": "exec-20250321-001",
        "status": "SUCCESS",
        "startTime": "2025-03-21T11:00:00+08:00",
        "endTime": "2025-03-21T11:02:30+08:00",
        "durationMs": 150000,
        "resultSummary": "同步记录数: 12500, 失败记录数: 0"
      }
    ]
  }
}

4.5 统一错误码与响应格式

所有接口遵循统一的响应格式，便于客户端解析与监控告警集成。错误码采用分层设计，前两位表示错误来源。

4.5.1 统一响应结构

{
  "code": 0,
  "message": "success",
  "data": {},
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": 1711000000000
}

字段	类型	说明
code	integer	业务状态码，0表示成功，非0表示错误
message	string	状态描述信息，成功时为"success"
data	object/null	业务数据负载，错误时为null
traceId	string	全链路追踪ID，用于日志关联与问题定位
timestamp	long	服务端响应时间戳（毫秒）

4.5.2 错误码定义

错误码	分类	说明	HTTP状态码
0	成功	请求处理成功	200/201/202
10001	参数错误	请求参数校验失败，如缺少必填字段、格式错误	400
10002	资源不存在	指定的任务ID或日志ID不存在	404
10003	状态冲突	任务当前状态不允许执行该操作，如停止已停止的任务	409
20001	调度引擎错误	调度器内部异常，如节点不可用、队列满	503
20002	执行超时	任务执行超过设定的timeoutSeconds	504
30001	限流拒绝	请求频率超过接口限流阈值	429
99999	未知错误	未预期的系统异常，需联系运维查看日志	500

4.6 核心API契约关系图

下图展示了任务调度平台核心API之间的调用关系与数据流向，帮助理解各接口在整体架构中的位置：

4.7 契约验证与压测前置检查清单

在开始压力测试之前，必须逐项验证API契约的正确性。以下清单可作为压测前置检查的参考：

1. 响应格式一致性： 所有接口返回的JSON结构必须包含 code、message、data、traceId、timestamp 五个字段，字段类型与契约一致。
2. 错误码覆盖： 对每个接口，至少验证参数错误(10001)、资源不存在(10002)、状态冲突(10003)三种异常场景的返回是否符合契约。
3. 分页参数边界： 日志查询接口的 pageSize 最大值为100，传入101时应返回10001错误码；传入0时应使用默认值20。
4. 时间格式： 所有时间字段统一使用ISO8601格式，包含时区信息（如 2025-03-21T10:30:00+08:00）。
5. 幂等性： 触发接口应保证同一 executionId 不会被重复创建，重复请求应返回200而非201。