44 lines
3.4 KiB
Markdown
44 lines
3.4 KiB
Markdown
# Orbit HTTP / WebSocket 接口手册
|
||
|
||
更新：2026-09-17。接口实现状态随 [开发计划](../08-development-plan.md) 更新。
|
||
|
||
## 当前接口状态
|
||
|
||
| 接口 | 状态 | 手册 |
|
||
| --- | --- | --- |
|
||
| `GET /health/live` | 已实现 | [健康检查](health.md) |
|
||
| `GET /health/ready` | 已实现，验证数据库、迁移记录及零外键要求 | [健康检查](health.md) |
|
||
| `/v1/tasks` 提交、查询、分页与待执行取消 | P1 已实现 | [任务接口](tasks.md) |
|
||
| `/v1/tasks/{task_id}/attempts` 与尝试详情 | P2 已实现 | [执行历史](execution-history.md) |
|
||
| `/v1/tasks/{task_id}/attempts/{attempt_id}/evidence` 与证据详情 | P2 已实现 | [执行历史](execution-history.md) |
|
||
| `/v1/queues` 创建、查询及 `:configure` 控制 | 已实现队列并发、开始速率、积压背压与暂停/恢复 | [队列接口与 SDK 场景](queues.md) |
|
||
| `/v1/application/resources` 查询及 `:configure` 管理 | P3 已实现跨命名空间应用配额 | [应用配额与 SDK 场景](application-resources.md) |
|
||
| 任务 `concurrency_key` 与尝试 `concurrency_token` | P3 已实现跨队列资源键互斥 | [资源键接口与 SDK 场景](keyed-concurrency.md) |
|
||
| 任务 `priority` 与节点领取池 | P3 已实现有界优先级加速、应用/队列轮转 | [优先级与公平派发](priority-and-fairness.md) |
|
||
| 凭据校验与初始化 CLI | P1 已实现 | [鉴权](authentication.md) |
|
||
| `/v1/worker/connect` | P2 已实现并通过阶段验收 | [Worker 契约](worker.md)、[Schema](worker-schema.md) |
|
||
| 任务冻结策略与 Worker `retryable` | P3 安全重试已实现 | [安全重试](retries.md) |
|
||
| `/v1/tasks/{task_id}:cancel` 与 `task.cancel` 通知 | P3 运行中取消已实现 | [取消及 SDK 场景](cancellation.md) |
|
||
| `/v1/schedules`、不可变版本、暂停/恢复及触发查询 | P3 已实现 | [计划接口与 SDK 场景](schedules.md) |
|
||
| `/v1/events/connect` 及订阅管理 | 持久化核心已实现；HTTP/WSS 和 SDK 尚未接入 | [订阅核心及边界](../09-result-subscription-core.md) |
|
||
| `/v1/workflows` 与流程管理 | 计划 P4–P5，尚未实现 | [流程接口规划](workflows.md) |
|
||
|
||
未实现路由返回 404。健康检查就绪不表示任务执行、定时调度或流程引擎已经可用。
|
||
|
||
## 业务接口统一要求
|
||
|
||
P1 业务接口已遵守下述约定，后续接口继续沿用：
|
||
|
||
- 生产使用 HTTPS/WSS，凭据通过授权头或受控握手传递，不放入 URL。
|
||
- 应用身份、命名空间和操作权限分别校验；知道资源 ID 不等于拥有权限。
|
||
- 稳定幂等键与请求追踪 ID 分开；超时重报保留原键。
|
||
- 可能超过跨语言整数精度的 ID 和执行代次使用字符串。
|
||
- 时间为 UTC RFC 3339，时长字段带单位；查询和批量操作有上限。
|
||
- 错误码、字段、分页游标和限制值在对应阶段实现及回归后冻结。
|
||
|
||
健康接口直接返回状态对象。已实现的业务接口使用 `request_id` + `data` / `error` 信封；当前实际字段以本目录手册为准，其他尚未实现的接口见 [通信协议草案](../03-http-websocket-protocol.md)。
|
||
|
||
## 每个正式接口的文档模板
|
||
|
||
实现时必须补齐：用途与权限、HTTP 方法和路径、请求头、字段类型/必填/默认值/限制、完整请求与响应、错误码、幂等与并发规则、超时/重试/取消语义、SDK 对应方法、可运行示例、兼容版本和已覆盖的回归场景。
|