4、分布式调度核心模型：Task、Job、Workflow、Executor 的 API 抽象
在分布式任务调度平台中，Task（任务）、Job（作业）、Workflow（工作流） 和 Executor（执行器） 是构成调度体系最基础的四个核心模型。OpenAPI 契约设计的第一步，就是对这些模型进行精确的抽象与定义，确保调度语义在客户端与服务端之间无歧义地传递。
这四个模型并非孤立存在，而是通过明确的层级关系与生命周期约束，共同支撑起从单次执行到复杂编排的完整调度场景。下面从 API 抽象的角度逐一剖析每个模型的核心字段、行为语义以及它们之间的协作关系。
4.1 核心模型关系总览
下图展示了四个核心模型在分布式调度系统中的分层结构与交互关系：
契约设计要点：在 OpenAPI 契约中，这四个模型必须使用独立的 Schema 定义，并通过
workflowId、jobId、executorId 等引用字段建立关联。禁止将多个模型合并为一个扁平结构，否则将破坏调度语义的可扩展性。
4.2 Task（任务）—— 最小执行单元
Task 是调度系统中不可再分的最小执行单元，代表一次具体的计算或处理请求。API 抽象需要覆盖 Task 的标识、类型、输入、重试策略和状态。
| 字段 | 类型 | 说明 |
|---|---|---|
taskId |
string | 全局唯一标识，由调度中心生成 |
jobId |
string | 所属作业 ID |
taskType |
enum | HTTP、Shell、MR、Spark、Flink 等 |
taskPayload |
object | 执行参数，如 URL、命令、SQL |
maxRetries |
int | 最大重试次数，默认 0 |
timeoutSeconds |
int | 超时时间，超时自动标记失败 |
status |
enum | PENDING / RUNNING / SUCCESS / FAILED / TIMEOUT |
API 抽象原则：Task 的
taskPayload 应设计为 Map<String, Object> 或 oneOf 联合类型，避免为每种任务类型定义独立的请求体。这样新增任务类型时无需修改 API 接口，仅扩展 Schema 即可。
4.3 Job（作业）—— 调度与治理单元
Job 是用户直接面对的管理单元，包含调度策略、依赖关系和生命周期管理。一个 Job 可以包含一个或多个 Task，并定义这些 Task 的执行模式（串行/并行）。
- 调度属性：
cronExpr（定时表达式）、timeZone、startAt、endAt、maxConcurrency（最大并发数）。 - 执行模式：
executionMode枚举值：SEQUENTIAL（串行）、PARALLEL（并行）、DAG（有向无环图）。 - 生命周期：ENABLED / PAUSED / COMPLETED / ARCHIVED，支持暂停、恢复、终止操作。
- Task 列表：
tasks字段为Array<Task>，在创建 Job 时一并提交。
// Job 创建请求的 OpenAPI Schema 示例（YAML 片段）
CreateJobRequest:
type: object
required:
- jobName
- executionMode
- tasks
properties:
jobName:
type: string
maxLength: 128
executionMode:
type: string
enum: [SEQUENTIAL, PARALLEL, DAG]
cronExpr:
type: string
example: "0 0/5 * * * ?"
tasks:
type: array
items:
$ref: '#/components/schemas/Task'
maxRetries:
type: integer
default: 0
4.4 Workflow（工作流）—— 复杂编排引擎
Workflow 用于编排多个 Job 的执行顺序与依赖关系，支持条件分支、并行网关和超时控制。API 抽象需要提供 DAG 定义能力。
| 概念 | API 字段 | 说明 |
|---|---|---|
| 节点 | nodes |
Job 引用列表，每个节点包含 nodeId 和 jobId |
| 边 | edges |
依赖关系，fromNodeId → toNodeId |
| 条件 | condition |
可选，节点执行的前置条件表达式 |
| 超时 | timeoutMinutes |
整个工作流超时时间 |
| 触发方式 | triggerType |
MANUAL / CRON / EVENT |
契约一致性风险：Workflow 的 DAG 定义中，
edges 必须校验是否存在环（Cycle）。OpenAPI 契约应在服务端实现拓扑排序校验，并在响应中返回 400 INVALID_DAG 错误码。客户端 SDK 也建议在本地做一次轻量校验，减少无效请求。
4.5 Executor（执行器）—— 运行时容器
Executor 是 Task 的实际运行环境，可以是物理机、容器、Kubernetes Pod 或 Serverless 函数。API 抽象关注 Executor 的注册、心跳、资源容量和健康状态。
- 注册信息：
executorId、name、address（IP:Port）、tags（标签，用于路由）。 - 资源容量：
maxSlots（最大并行 Task 数）、availableSlots（当前可用槽位）。 - 健康状态：
status枚举：ONLINE / OFFLINE / BUSY / UNHEALTHY。 - 心跳接口：
POST /api/v1/executors/{executorId}/heartbeat，上报availableSlots和runningTaskIds。
// Executor 心跳请求体
{
"executorId": "exec-001",
"timestamp": 1712563200000,
"availableSlots": 3,
"runningTaskIds": ["task-101", "task-102"],
"cpuUsage": 0.45,
"memoryUsage": 0.62
}
4.6 模型间的契约约束总结
下表汇总了四个核心模型在 OpenAPI 契约中必须遵守的约束规则：
| 约束类型 | 涉及模型 | 规则描述 |
|---|---|---|
| 引用完整性 | Task → Job | Task 的 jobId 必须指向一个已存在的 Job |
| 引用完整性 | Job → Workflow | Workflow 中引用的 Job 必须已创建 |
| 容量约束 | Task → Executor | 调度时 Executor 的 availableSlots 必须 ≥ 1 |
| 状态流转 | Job / Task | 不允许从 FAILED 直接跳转到 RUNNING，必须经过重试或重置 |
| DAG 无环 | Workflow | edges 必须构成有向无环图 |
| 幂等创建 | Job / Workflow | 支持 idempotentKey 防止重复提交 |
通过对 Task、Job、Workflow、Executor 四个核心模型的精确 API 抽象，分布式调度平台能够以统一的契约语言描述从单次任务执行到复杂工作流编排的全场景。下一层将基于这些模型，进一步设计具体的 RESTful 资源路径与操作语义。