4. 任务调度平台 OpenAPI 规范设计

本章聚焦于任务调度平台的核心 API 规范设计。一套清晰、一致且可扩展的 OpenAPI 规范是平台与外部系统（如 Kafka 事件驱动层、前端控制台、CI/CD 流水线）集成的基石。我们将依次定义任务 CRUD、作业提交、工作流、触发器及日志查询五大类 API，确保每个接口都具备明确的语义、幂等性保障和错误响应格式。

4.1 API 设计总则

所有 API 遵循 RESTful 风格，使用 JSON 作为请求与响应体格式。基础路径统一为 /api/v1。认证方式采用 Bearer Token，在请求头中传递。响应结构统一封装，包含 code、message、data 三个字段。

4.2 任务 CRUD API

任务（Task）是调度平台的最小执行单元。CRUD 接口负责管理任务的定义，包括任务名称、类型、执行命令、超时时间、重试策略等。

4.2.1 核心端点

4.2.2 创建任务请求示例

POST /api/v1/tasks
Content-Type: application/json
Authorization: Bearer <token>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "name": "数据清洗-每日批次",
  "type": "SHELL",
  "command": "sh /opt/scripts/clean.sh",
  "timeout": 3600,
  "retryCount": 3,
  "retryInterval": 300,
  "description": "每日凌晨执行数据清洗任务"
}

4.2.3 响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task-20240501-001",
    "name": "数据清洗-每日批次",
    "type": "SHELL",
    "status": "ENABLED",
    "createdAt": "2024-05-01T00:00:00Z"
  }
}

4.3 作业提交 API

作业（Job）是任务的一次具体运行实例。提交作业时，用户指定任务 ID 和运行时参数，平台返回作业 ID 用于后续跟踪。

4.3.1 提交作业端点

4.3.2 提交作业请求示例

POST /api/v1/jobs
Content-Type: application/json
Authorization: Bearer <token>
Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001

{
  "taskId": "task-20240501-001",
  "parameters": {
    "date": "2024-05-01",
    "batchSize": 1000
  },
  "priority": "HIGH"
}

4.4 工作流定义 API

工作流（Workflow）由多个任务按 DAG（有向无环图）编排而成。API 支持定义工作流的节点、边、条件分支和并行策略。

4.4.1 工作流定义结构

4.4.2 创建工作流示例

POST /api/v1/workflows
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "数据管道-全流程",
  "nodes": [
    { "nodeId": "extract", "taskId": "task-extract-001" },
    { "nodeId": "transform", "taskId": "task-transform-001" },
    { "nodeId": "load", "taskId": "task-load-001" }
  ],
  "edges": [
    { "from": "extract", "to": "transform" },
    { "from": "transform", "to": "load" }
  ],
  "triggerPolicy": "CRON",
  "cronExpression": "0 0 2 * * ?"
}

4.5 触发器管理 API

触发器（Trigger）决定工作流或任务何时被自动调度。支持 CRON 表达式、事件驱动和手动触发三种模式。

4.5.1 触发器类型

4.5.2 创建触发器示例

POST /api/v1/triggers
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "每日凌晨2点触发",
  "type": "CRON",
  "targetType": "WORKFLOW",
  "targetId": "wf-data-pipeline-001",
  "cronExpression": "0 0 2 * * ?",
  "enabled": true
}

4.6 执行日志查询 API

执行日志是排查问题、审计追溯的核心数据。API 支持按作业 ID、任务 ID、时间范围等维度查询日志，并支持分页和流式拉取。

4.6.1 日志查询端点

4.6.2 日志查询请求示例

GET /api/v1/logs/jobs/job-20240501-001?startTime=2024-05-01T00:00:00Z&endTime=2024-05-01T23:59:59Z&page=1&size=50
Authorization: Bearer <token>

4.6.3 日志响应结构

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 128,
    "page": 1,
    "size": 50,
    "logs": [
      {
        "timestamp": "2024-05-01T02:00:05Z",
        "level": "INFO",
        "source": "executor-node-3",
        "message": "作业开始执行，任务ID: task-extract-001"
      },
      {
        "timestamp": "2024-05-01T02:00:10Z",
        "level": "ERROR",
        "source": "executor-node-3",
        "message": "连接数据库超时，重试第1次"
      }
    ]
  }
}

4.7 API 错误码规范

统一的错误码体系有助于客户端快速定位问题。下表列出核心错误码及其含义。

4.8 本章小结

本章完成了任务调度平台五大核心 API 的规范设计：任务 CRUD 提供基础管理能力；作业提交 API 实现运行时实例化；工作流定义 API 支持复杂 DAG 编排；触发器管理 API 连接时间与事件驱动；执行日志查询 API 保障可观测性。所有接口遵循统一响应格式、幂等性设计和标准错误码体系，为后续 Kafka 事件驱动集成奠定了坚实的契约基础。