feat: add idempotent batch task submission and recovery examples

This commit is contained in:
2026-09-17 21:21:18 +08:00
parent a8a8dcfe1e
commit 571107f96d
27 changed files with 1375 additions and 24 deletions

View File

@@ -1,6 +1,6 @@
# Orbit HTTP 与 WebSocket 协议草案
> 版本 0.2 · 2026-09-17。HTTP + WS 已确认。本文的具体路径、消息名、字段及状态码是首版设计建议,业务协议尚未实现,需评审后冻结;健康接口的已实现契约见接口手册。
> 版本 0.2 · 2026-09-17。HTTP + WS 已确认。本文保留首版设计建议;已实现能力以[正式接口手册](api/README.md)为准,其余路径、消息名、字段和状态码仍待对应阶段实现及验证。
实现更新:HTTP 任务/队列接口已完成 P1;Worker 服务端已进入 P2,实际帧名、字段、回执与边界见 [Worker 契约](api/worker.md)。本文保留早期完整设计,未实现项目不能据此视为已交付。
@@ -18,7 +18,7 @@
| 方法与路径 | 行为 |
| --- | --- |
| `POST /v1/tasks` | 幂等提交一项任务 |
| `POST /v1/tasks:batchSubmit` | 批量逐项提交,每项独立幂等 |
| `POST /v1/tasks:batch` | 已实现;逐项身份、四类结果与限制见[批量手册](api/batch-tasks.md) |
| `GET /v1/tasks/{task_id}` | 查询权威任务状态与结果摘要 |
| `GET /v1/tasks/{task_id}/attempts` | 分页查询执行尝试 |
| `GET /v1/tasks` | 按有索引的字段分页查询,支持提交幂等键精确查找 |
@@ -55,7 +55,7 @@ Weave 的补充接口建议如下,功能范围已确认,具体技术细则
- 首次创建任务、流程或信号记录的建议响应为 `201 Created`,表示资源及幂等记录已可靠提交,不表示业务执行或信号消费完成。
- 相同幂等请求返回 `200` 和原资源 ID,标记 `deduplicated: true`;相同键不同语义请求返回 `409`。
- 单项提交使用 `Idempotency-Key`;批量每项使用 `submission_key`,由 SDK 统一映射为提交幂等标识。
- 单项提交使用 `Idempotency-Key`;已实现的批量每项使用 `idempotency_key`,与单项共用受理身份;不接受整批幂等头,见[批量接口](api/batch-tasks.md)。
- 普通任务提交幂等作用域为命名空间内的任务提交操作;流程启动使用独立操作作用域,信号按命名空间、实例与信号 ID 去重。其他管理写操作按命名空间、操作和资源界定作用域,避免同一个键在不同 API 间意外冲突。
- HTTP `request_id` 仅用于追踪,与业务幂等键分开。
- 请求超时后,使用原幂等键查询或重试;不能通过换一个键来猜测原请求是否失败。