4. 用户层接口（一）：任务提交接口（SubmitTask）的输入参数规范

任务提交接口 SubmitTask 是 GoDAG 调度系统面向用户层暴露的核心入口之一。调用方通过该接口将业务任务实例注入调度引擎，触发后续的依赖解析、拓扑排序与执行调度。本章聚焦于该接口的输入参数规范，明确必填字段与可选字段的边界，确保调用方与调度引擎之间的契约清晰、可验证。

4.1 接口语义与调用模型

SubmitTask 采用同步请求-响应模式，调用方提交任务定义后，接口在完成基础校验与持久化后立即返回任务全局唯一标识符（TaskID）。任务的实际调度与执行由引擎异步完成。接口不阻塞等待任务执行结果。

4.2 输入参数总览

SubmitTask 的请求体采用 JSON 格式，包含以下顶层字段。根据调度引擎的校验规则，字段被划分为 必填 与 可选 两类。

4.3 必填字段详解

4.3.1 task_name

任务名称在同一个命名空间内必须唯一。引擎在提交时执行唯一性校验，若名称已存在则返回冲突错误。命名规则：^[a-zA-Z0-9_-]{1,128}$。

4.3.2 dag_definition

DAG 定义是任务的核心结构，包含 nodes 与 edges 两个子字段。

Node 结构：

{
  "node_id": "node_001",
  "handler": "http://service-a/execute",
  "timeout_seconds": 300,
  "retry": 2,
  "input_data": { "key": "value" }
}

Edge 结构：

{
  "from": "node_001",
  "to": "node_002"
}

4.4 可选字段详解

可选字段为调用方提供了灵活的控制能力，但引擎在字段缺失时会使用安全默认值。以下为各字段的默认行为与使用场景。

• timeout_seconds： 控制任务从提交到完成的最大允许时间。超过此时间引擎将强制终止所有未完成节点并标记任务为超时失败。对于长时间运行的数据处理任务，建议显式设置较大的超时值。
• max_retry： 当某个节点执行失败时，引擎自动重试该节点的次数。重试间隔采用指数退避策略（1s、2s、4s…）。注意：重试仅针对节点级失败，不适用于 DAG 整体超时。
• tags： 键值对标签，可用于按业务线、环境、版本等维度过滤任务列表。例如：{"env": "prod", "version": "v2.1"}。
• priority： 影响任务在调度队列中的出队顺序。高优先级任务会优先获取调度资源。同一优先级内按提交时间 FIFO。
• callback_url： 任务终态（成功/失败/超时）触发后，引擎向该 URL 发送 POST 回调，携带任务 ID 与最终状态。回调采用至少一次语义，调用方需做好幂等处理。
• description： 纯文本描述，仅用于人工阅读与审计日志，引擎不解析其内容。

4.5 请求示例与边界校验

以下是一个完整的 SubmitTask 请求体示例，包含必填字段与部分可选字段：

{
  "task_name": "etl_pipeline_20250321",
  "dag_definition": {
    "nodes": [
      {
        "node_id": "extract",
        "handler": "http://worker-svc/extract",
        "timeout_seconds": 120,
        "retry": 1
      },
      {
        "node_id": "transform",
        "handler": "http://worker-svc/transform",
        "timeout_seconds": 300,
        "retry": 2
      },
      {
        "node_id": "load",
        "handler": "http://worker-svc/load",
        "timeout_seconds": 180,
        "retry": 0
      }
    ],
    "edges": [
      { "from": "extract", "to": "transform" },
      { "from": "transform", "to": "load" }
    ]
  },
  "timeout_seconds": 7200,
  "max_retry": 1,
  "tags": {
    "env": "staging",
    "team": "data"
  },
  "priority": 7,
  "callback_url": "https://callback.example.com/dag/notify",
  "description": "每日 ETL 流水线 - 测试环境"
}

4.6 参数校验流程

引擎在接收请求后，按以下顺序执行参数校验，任一阶段失败即终止并返回明确错误码。

1. JSON 反序列化： 检查请求体是否为合法 JSON，字段类型是否匹配。
2. 必填字段存在性： 确认 task_name 与 dag_definition 非空。
3. 字段值域校验： 检查字符串长度、数值范围、URL 格式等。
4. DAG 结构校验： 节点唯一性、边引用有效性、环检测。
5. 业务唯一性校验： 检查 task_name 在当前命名空间是否已存在。

4.7 契约保障与版本兼容

SubmitTask 的输入参数契约遵循向后兼容原则。新增可选字段时，不会破坏已有调用方的请求结构。引擎在反序列化时会忽略未知字段，确保未来扩展的平滑性。调用方应始终使用文档中列出的字段名，避免依赖未公开的内部字段。