2. 任务调度平台 OpenAPI 概述

在深入幂等性设计之前，必须先理解任务调度平台的整体架构、OpenAPI 在其中的角色定位，以及接口的分类体系。只有明确了这些基础，才能针对不同接口类型制定合理的幂等策略。

2.1 典型任务调度平台架构

一个生产级的任务调度平台通常采用分层架构，从上到下依次为：接入层、调度核心层、执行层和存储层。各层职责清晰，通过标准协议交互。

2.2 OpenAPI 的角色与定位

OpenAPI（开放应用程序编程接口）是任务调度平台对外暴露的标准化接口集合，承担着连接外部系统与调度平台内部能力的桥梁作用。其核心角色包括：

2.3 常见接口分类

根据业务操作的性质，任务调度平台的 OpenAPI 接口可以划分为四大类：创建类、执行类、查询类和删除类。每一类接口的幂等性要求和实现策略差异显著。

2.4 接口分类详细说明

2.4.1 创建类接口

创建类接口用于在调度平台上定义新的任务、工作流或执行器。这类接口的幂等性设计核心在于业务唯一性约束。

• 典型接口：POST /api/v1/jobs、POST /api/v1/workflows
• 幂等策略：客户端传入 Idempotency-Key 或使用业务字段组合（如 namespace + jobName）作为唯一标识。服务端先查询是否存在，若存在则返回已有资源，不重复创建。
• 返回码：首次创建返回 201 Created，重复请求返回 200 OK 并携带已有资源信息。

2.4.2 执行类接口

执行类接口触发任务的一次运行实例。这是幂等性设计最严格的接口类别，因为重复触发可能导致数据重复处理、资源浪费甚至业务错误。

• 典型接口：POST /api/v1/jobs/{jobId}/trigger、POST /api/v1/instances/{instanceId}/stop
• 幂等策略：必须使用全局唯一触发ID（由客户端生成 UUID 或由平台颁发预生成 ID）。服务端记录所有已处理的触发ID，重复请求直接返回已存在的实例信息。
• 关键设计：触发ID 的存储需要持久化，且与实例状态绑定。即使实例执行失败，重复触发也应返回相同的实例ID，而不是创建新实例。

2.4.3 查询类接口

查询类接口用于获取任务定义、实例状态、日志等信息。这类接口天然具有幂等性——多次调用返回相同结果（在数据未变化的前提下）。

• 典型接口：GET /api/v1/jobs/{jobId}、GET /api/v1/instances?status=running
• 幂等策略：无需特殊幂等处理，但需注意：
• 分页查询应保证排序稳定，避免分页偏移量不一致导致数据重复或遗漏。
• 缓存场景下需考虑缓存失效策略，避免返回过期数据。

2.4.4 删除类接口

删除类接口用于移除任务定义、工作流或清理日志。幂等性设计的目标是：无论删除多少次，最终状态一致。

• 典型接口：DELETE /api/v1/jobs/{jobId}、DELETE /api/v1/logs?before=2024-01-01
• 幂等策略：采用“存在则删除，不存在则返回成功”的语义。服务端先检查资源是否存在，若不存在则直接返回 204 No Content 或 200 OK，不报错。
• 注意事项：级联删除（如删除任务时同时删除关联实例）需要保证整体操作的原子性和幂等性，避免部分删除导致数据不一致。

2.5 接口幂等性需求矩阵

下表总结了四类接口的幂等性需求对比，帮助你在设计阶段快速定位策略重点：