3. OpenAPI 规范与接口设计：RESTful API 设计原则、任务 CRUD 接口定义、状态查询与回调接口

在构建高性能任务调度平台时，OpenAPI 规范（原 Swagger）不仅是接口文档的标准，更是压测脚本与自动化测试的契约基础。本章将围绕 RESTful 设计原则，定义任务调度平台的核心 CRUD 接口、状态查询机制以及异步回调接口，为后续的压测场景设计奠定精确的请求-响应模型。

3.1 RESTful API 设计原则在调度平台中的落地

任务调度平台本质上是资源管理系统，核心资源是“任务（Task）”。我们严格遵循以下 REST 原则：

• 资源导向 URL：每个任务实例拥有唯一的 URI，如 /api/v1/tasks/{taskId}。
• 使用标准 HTTP 方法：GET（查询）、POST（创建）、PUT（全量更新）、PATCH（部分更新）、DELETE（删除）。
• 无状态交互：服务端不保存客户端上下文，每次请求携带完整认证信息（Token）。
• 统一响应格式：所有接口返回标准 JSON 结构，包含 code、message、data 字段。
• 版本控制：URL 前缀携带版本号 /api/v1/，保障向后兼容。

3.2 任务 CRUD 接口定义

任务 CRUD 是调度平台最核心的接口集合，也是压测中请求量最大的路径。以下为接口规范与参数定义：

3.3 状态查询接口

任务状态是调度系统健康度的核心指标。我们设计了批量状态查询与单任务状态查询两个接口，以满足不同压测场景：

• 单任务状态查询：GET /api/v1/tasks/{taskId}/status，返回当前任务的状态枚举值（pending / running / success / failed / timeout）。
• 批量状态查询：POST /api/v1/tasks/status/batch，请求体传入 { "taskIds": ["id1","id2"] }，返回 { "statusMap": { "id1": "running", "id2": "success" } }。

状态枚举与业务含义对应关系如下：

3.4 回调接口设计

任务调度平台采用异步执行模式，任务提交后立即返回 taskId，执行结果通过回调（Callback）机制通知调用方。回调接口由调用方提供，调度平台在任务终态时主动 POST 请求该地址。

回调请求规范如下：

3.5 接口安全与认证设计

所有 OpenAPI 接口均需通过 Bearer Token 认证。Token 通过 POST /api/v1/auth/token 获取，有效期 2 小时。压测脚本需在初始化阶段获取 Token，并在后续请求的 Header 中携带：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

接口响应中，认证相关错误码如下：

3.6 接口响应体统一规范

所有 OpenAPI 接口遵循统一的 JSON 响应结构，便于压测脚本进行断言与数据提取：

{
  "code": 0,
  "message": "success",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    // 业务数据
  }
}

• code：0 表示成功，非 0 表示业务异常，具体错误码见接口文档。
• message：人类可读的错误描述。
• requestId：全局唯一请求 ID，用于链路追踪与压测日志关联。
• data：业务数据载体，类型根据接口不同而变化。