149 lines
14 KiB
Markdown
149 lines
14 KiB
Markdown
# 通用场景示例
|
||
|
||
示例只使用通用的作业、对象、文件、资源与审核信号，不包含接入方项目名称或行业规则。
|
||
|
||
## 已可运行：健康检查
|
||
|
||
- 源码：[SDK 健康检查](../../sdk/go/examples/health/main.go)。
|
||
- 前置：已迁移的 MySQL 与已启动的基础服务。
|
||
- 操作与预期输出：[SDK 接入说明](../sdk/README.md)。
|
||
- 异常：数据库不可用或迁移记录异常时 readiness 返回 HTTP 503，SDK 返回类型化状态错误。
|
||
- 清理：只读调用，无业务资源需要删除。
|
||
|
||
## 已可运行：文件转换任务的受理与取消
|
||
|
||
- 源码：[SDK 任务受理示例](../../sdk/go/examples/tasks/main.go)。
|
||
- 前置：完成迁移、初始化凭据、启动服务，在没有 Worker 消费的专用队列运行此受理/取消示例，详见 [SDK 接入](../sdk/README.md)。
|
||
- 输入：对象引用、格式与精确整数；提交两次同一身份，再查询、分页并带版本取消。
|
||
- 预期：重复请求返回同一任务，最终 CANCELLED/revision=2。当前不启动 Worker，不实际生成文件。
|
||
- 异常：凭据失效、权限不足、内容冲突、版本竞争和未知网络结果，见 [任务接口](../api/tasks.md)。
|
||
- 清理：示例以取消结束；任务和审计历史保留。重复运行会生成独立示例任务。
|
||
|
||
## 已可运行：文本规范化执行
|
||
|
||
- 源码：[Worker 底层协议示例](../../sdk/go/examples/worker-protocol/main.go)。
|
||
- 前置：专用 Worker 凭据，启动步骤见 [Worker SDK 文档](../sdk/worker.md)。
|
||
- 输入与步骤：提交 `{"text":" Hello Orbit "}` → 注册/容量 → 领取 → 开始授权 → 实际处理 → 确认结果 → 查询 → 排空。
|
||
- 预期：SUCCEEDED、一次尝试、结果 `{"text":"HELLO ORBIT"}`。
|
||
- 异常：底层示例使用原身份有限重报控制 ACK；业务函数不随重连再次调用；迟到证据不能当作成功结果。自动续租与持续消费见下方运行器示例。
|
||
- 清理：任务历史保留；运行结束确认排空并关闭连接。每次示例使用独立任务/处理器身份。
|
||
|
||
## 已可运行：自动 Worker 并发消费
|
||
|
||
- 源码：[自动 Worker 示例](../../sdk/go/examples/worker/main.go)，[接入与启动命令](../sdk/worker-runtime.md)。
|
||
- 步骤：注册版本化处理器 → Run → 以容量 2 消费三条文本任务 → 查询结果 → 取消 Run context 并等待排空。
|
||
- 预期：三条规范化结果、started=3、confirmed=3、running=0；输入与结果均由实际代码处理。
|
||
- 异常：自动心跳/续租与原身份重连；普通错误/panic 按未知效果报告，超时退出不声称杀死 goroutine；完整故障证据见 [回归记录](../reports/phase-2-worker-runtime.md)。
|
||
- 清理：正常排空关闭连接，保留历史；进程被强杀后的在途状态由租约恢复与核查衔接。
|
||
|
||
## 已可运行：执行历史与冲突证据核对
|
||
|
||
- 源码：[执行历史示例](../../sdk/go/examples/history/main.go)，[启动命令和输入输出](../sdk/README.md#6-查询执行历史与证据)。
|
||
- 前置：迁移到当前版本、启动服务，专用凭据具备提交/读取与 Worker 权限。
|
||
- 步骤：创建模拟任务 → 开始授权 → 保存 v1 结果 → 用另一消息身份报告 v2 → 查询尝试/证据列表与详情 → 核对任务仍保留 v1。
|
||
- 预期：SUCCEEDED、attempts=1、evidence=1、reason=RESULT_CONFLICT、disposition=EVIDENCE_ONLY；实际结果中的大整数保持精确。
|
||
- 异常：迟到或矛盾内容不能覆盖权威结果；缺少动作权限返回 403，错配父资源、跨命名空间或队列越权返回 404，详见 [接口](../api/execution-history.md)。示例不调用外部业务系统。
|
||
- 清理：正常结束确认排空并关闭连接；任务及证据保留用于追踪，不硬删除。重复运行创建独立任务。
|
||
|
||
## 已可运行：有限安全重试
|
||
|
||
- 源码：[重试示例](../../sdk/go/examples/retry/main.go)，[完整启动命令与结果](../api/retries.md#5-运行完整示例)。
|
||
- 前置：当前迁移及服务，具有提交、读取和 Worker 权限的专用凭据。
|
||
- 步骤：第一次在产生效果前模拟明确拒绝 → 平台持久化退避 → 第二次处理文本 → 查询两次尝试 → 排空。
|
||
- 预期：SUCCEEDED、attempts=2、first_retryable=true、结果 `{"text":"SAFE RETRY"}`；Worker started=2、confirmed=2、running=0。
|
||
- 异常：次数/时限耗尽停止重试；未知效果默认转核查。`Retryable=true` 需要明确的安全依据，不能用于普通网络超时。
|
||
- 清理：示例不调用外部业务系统，每次创建独立任务并保留历史；失败时非零退出并有界收尾。
|
||
|
||
## 已可运行：周期对象快照
|
||
|
||
- 源码：[调度示例](../../sdk/go/examples/schedules/main.go)，[初始化、调用与输出](../api/schedules.md#6-sdk-与完整示例)。
|
||
- 前置：当前迁移、服务，显式 --schedule-access 与 --worker-access 的专用开发凭据。
|
||
- 步骤：创建暂停的有限每秒计划 → 恢复 → 自动 Worker 返回输入快照 → 查到至少两次任务成功 → 暂停并排空。
|
||
- 预期：不同 occurrence/task 身份、相同计划版本、paused=true、running=0；精确整数保留。
|
||
- 异常：串行前项未知时不新建后续任务；恢复按版本与漏跑策略处理，超过窗口记录跳过。暂停不撤销已生成任务。
|
||
- 清理：计划最终暂停，自带十秒结束边界；失败非零退出，历史保留，无外部业务副作用。
|
||
|
||
## 已可运行：运行中任务取消
|
||
|
||
- 源码：[取消示例](../../sdk/go/examples/cancellation/main.go)，[初始化、调用与输出](../api/cancellation.md)。
|
||
- 前置：当前迁移、全部服务节点升级完成，凭据具备任务提交/读取/取消和 Worker 权限。
|
||
- 步骤：提交并开始受控任务 → 保存取消意图 → 处理器遵守 context 停止 → 明确确认本次无未结清效果 → 查询最终状态并排空。
|
||
- 预期：accepted_state=RUNNING、final_state=CANCELLED、attempts=1、running=0。
|
||
- 异常：普通 context 错误、通知丢失和未配合停止不能自动判定取消成功；未知效果进入核查。CAS 冲突先查询，网络结果未知保留原身份核对。
|
||
- 清理：无外部业务副作用；历史保留，每次运行独立身份，失败非零退出并有界收尾。
|
||
|
||
## 已可运行：队列限速与积压背压
|
||
|
||
- 源码：[资源控制示例](../../sdk/go/examples/resources/main.go)，[初始化、字段与完整输出](../api/queues.md)。
|
||
- 前置：当前迁移与服务，凭据具备全部队列的 queues:manage、任务及 Worker 权限。
|
||
- 步骤：创建并暂停积压上限为 2 的队列 → 第三个任务被 429 拒绝 → 满额下核对第一条原回执 → 取消释放空间 → 用被拒原身份再提交 → 恢复并按每秒 1 次开始执行。
|
||
- 预期：QUEUE_FULL、duplicate=true、两个任务 SUCCEEDED/attempts=1、unfinished=0。
|
||
- 异常：网络结果未知保留原身份，降额不清零用量，待核查任务仍占名额；跨节点及重启证据见 [资源回归](../reports/phase-3-queue-resources.md)。
|
||
- 清理：每次新建独立队列，任务 20 秒总截止；无外部副作用，历史保留，失败非零退出并有界收尾。
|
||
|
||
## 已可运行：跨命名空间共享配额
|
||
|
||
- 源码：[应用资源示例](../../sdk/go/examples/application-resources/main.go)，[双命名空间初始化、字段和输出](../api/application-resources.md)。
|
||
- 前置：同一独立、空闲示例应用下的两个命名空间，凭据显式具备应用资源管理权限；不需要 Worker。
|
||
- 步骤：应用上限设为 1 → first 受理 → second 全局满额 → 取消 first → second 以原受理键成功 → 取消收尾并按 CAS 恢复配置。
|
||
- 预期：APPLICATION_FULL/429、same_identity_retry_accepted=true、三个用量归零。
|
||
- 异常：普通队列管理员不能改应用额度；恢复配置遇到新版本冲突时不覆盖。进程强杀后不能保证清理，遗留任务受总时限约束，须按原身份核对。
|
||
- 清理：正常完成取消示例任务并恢复配置；历史保留，无业务副作用、无硬删除。
|
||
|
||
## 计划场景与验收标准
|
||
|
||
已可运行的 [优先级场景](../api/priority-and-fairness.md#4-sdk-完整场景) 提供 [完整源码](../../sdk/go/examples/priority/main.go)：按 0、9、4 受理后，以单槽 Worker 按 9、4、0 完成近同时到期的任务。前置为当前迁移/服务与队列、任务及 Worker 权限；预期 completed=3、attempts_per_task=1、worker_drained=true。无外部业务副作用，历史保留，失败非零退出，任务自带总时限；长等待补偿和其他应用隔离由真实数据库回归验证。
|
||
|
||
已可运行的 [跨队列资源互斥场景](../api/keyed-concurrency.md#5-完整可运行场景) 提供 [完整源码](../../sdk/go/examples/keyed-concurrency/main.go)：两个队列的自动 Worker 操作同一资源，核对递增序号，并模拟资源端拒绝旧写入。输入使用显式 concurrency_key；预期 completed=2、resource_writes=2、stale_write_rejected=true。示例仅使用受控内存资源，无外部副作用；正常排空、保留历史，任务自带总时限。内存 mutex 不是生产分布式存储，生产必须在资源端原子持久化序号、操作身份和实际更新。
|
||
|
||
| 场景 | 输入与步骤 | 预期结果 | 必测异常 | 状态 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 文件转换 | 对象引用 → 提交任务 → Worker 转换 → 结果引用 | 同一操作获得一次业务结果，历史可查 | 重复提交、Worker 在结果上报前中断 | 受理与执行框架已实现，实际转换示例待补齐 |
|
||
| 定期同步 | 发布计划 → 周期触发 → 暂停 → 恢复 | 触发身份唯一，漏跑策略可追溯 | 多节点竞争、停机后补跑上限 | P3 通用快照示例已完成，业务同步由接入方处理器实现 |
|
||
| 并行生成 | 输入对象 → 并行计算两份结果 → 汇合 | 两支满足条件后只创建一份后继工作 | 一支失败、重复结果、汇合竞争 | P4 待开发 |
|
||
| 等待审核 | 校验 → 等待信号 → 发布结果 | 只接受授权、匹配当前操作的信号 | 早到、重复、过期与越权信号 | P4 待开发 |
|
||
| 外部作业查询 | 提交一次 → 间隔查询 → 最终结果 | 处理中消耗轮次，请求失败消耗尝试 | 回执与查询竞争、预算耗尽、响应未知 | P5 待开发 |
|
||
| 暂停与恢复 | 暂停 → 接收在途结果 → 核查 → 继续 | 历史与预算保留，已成功工作不重复 | 暂停/开始竞争、恢复时已过期 | P5 待开发 |
|
||
|
||
每个待开发场景最终都需提供独立目录、完整源码、配置模板、启动与验证命令，不能只留下概念流程图。配套回归会先使用可控的模拟处理器或外部服务，不对真实系统产生副作用。
|
||
|
||
## 已可运行：订阅管理与幂等回执
|
||
|
||
- 源码：[订阅管理示例](../../sdk/go/examples/subscriptions/main.go)，[启动、输入输出和异常说明](subscriptions.md)。
|
||
- 前置：当前迁移及服务，具备 events:manage/read/consume 的专用开发凭据；初始化显式 --event-access。
|
||
- 步骤：创建 → 同键核对 → 暂停 → 恢复 → 查询与分页 → 最终暂停。
|
||
- 预期：duplicate=true、resumed_revision=3、final_enabled=false、revision=4、pending=0。
|
||
- 保留：每次运行留下一个已暂停订阅及审计；没有硬删除，受64个订阅上限约束。
|
||
- 范围：本例只演示管理SDK；自动消费 SDK 已实现，[持久化Inbox例子](result-inbox.md) 已独立交付。
|
||
|
||
## 已可运行：结果消费协议与跨连接确认
|
||
|
||
- 源码：[事件协议示例](../../sdk/go/examples/event-protocol/main.go)，[启动与输出说明](event-protocol.md)。
|
||
- 操作：创建订阅 → 提交并取消任务 → 接收冻结结果 → ACK → 重连重报原证明 → 核对原确认时间 → 暂停订阅。
|
||
- 输出：ack_replayed=true、same_receipt=true、pending=0、subscription_enabled=false。
|
||
- 范围：本例只做读取验证，不写业务数据；[自动消费器](../sdk/event-consumer.md) 的生产接入须提供事务Inbox，不能把示例当作业务恰好一次保证。
|
||
|
||
## 已可运行：独立业务 MySQL Inbox
|
||
|
||
- 独立项目：[result-inbox](../../examples/result-inbox/README.md)，[完整前置、命令及故障说明](result-inbox.md)。
|
||
- 操作：接收冻结结果 → Inbox与业务视图同事务提交 → 重复核对 → ACK → 暂停本次演示订阅。
|
||
- 输出：inbox_duplicate=true、applied_events=1、ack_confirmed=1、pending=0。
|
||
- 覆盖：并发重复、旧版本保护、回滚、真实MySQL COMMIT响应丢失、业务提交后/ACK前消费者SIGKILL及新进程去重。
|
||
- 边界：只覆盖接收方本地SQL效果；核心SDK不依赖数据库，外部副作用需要接收方自己的幂等/Outbox设计。
|
||
|
||
## 已可运行：批量受理与部分补交
|
||
|
||
- 源码：[batch](../../sdk/go/examples/batch/main.go)，[完整启动命令和输出](batch.md)。
|
||
- 步骤：独立暂停队列 → 三项批量提交、两项成功一项满额 → 整批核对原回执 → 取消释放额度 → 仅原身份补交第三项 → 取消收尾。
|
||
- 预期：accepted=2、replayed=2、retried_items=1、unfinished=0。
|
||
- 异常：逐项区分REJECTED/UNKNOWN/NOT_ATTEMPTED；真实HTTP响应丢失后恢复无重复，保留当前权限和额度控制。
|
||
- 范围：示例只演示受理，不转换文件、不提供业务Outbox；失败非零退出，每项60秒总时限，保留队列及审计。
|
||
|
||
## 已可运行：独立任务人工核查与关联重试
|
||
|
||
- 源码：[recovery](../../sdk/go/examples/recovery/main.go)，[完整运行与失败说明](recovery.md)。
|
||
- 步骤：模拟UNKNOWN → 人工声明历史执行结束 → 核查FAILED → 原键核对 → 创建retry_of关联新任务 → 执行成功 → 查询原任务及操作审计。
|
||
- 预期：原任务FAILED、新任务SUCCEEDED，原尝试和审计保留；管理凭据显式--recovery-access。
|
||
- 异常：真实HTTP在核查/重试提交后丢响应，原身份恢复同一审计和新任务；迟到成功只进入证据。
|
||
- 范围：本例不操作外部系统，不能替代真实证据核查、业务幂等或持久化管理操作Outbox。
|