Files
orbit/docs/examples

通用场景示例

示例只使用通用的作业、对象、文件、资源与审核信号,不包含接入方项目名称或行业规则。

已可运行:研发定义与发布流程

  • 完整命令和结果、SDK源码。
  • 六类节点的有限结构定义、原键及同版本确认、新版本发布、旧版本读取保持不变。
  • 当前只发布定义,实例执行仍在P4–P5开发。

已可运行:业务事务与任务提交Outbox

  • 独立模块:task-outbox,完整前置、命令、Go方法及故障处理。
  • 操作:业务记录和待发请求同事务 → 持久化领取 → 原幂等键HTTP提交 → 原回执与业务关联同事务确认。
  • 预期:local_duplicate=true、state=ACCEPTED、sends=1;ACCEPTED仅表示平台受理,演示随后取消任务并保留历史。
  • 覆盖:8个并发调用/20项领取、业务回滚、旧代次拒绝、HTTP回执丢失、三处MySQL COMMIT回执丢失及发送进程SIGKILL恢复。
  • 边界:业务侧两张表均无外键,22个中文注释字段;固定发送预算,REVIEW保留原记录供业务管理核查,核心SDK不引入数据库依赖。

已可运行:相对延迟执行

  • 完整命令、输入输出和失败处理,SDK源码。
  • delay_ms按数据库首次受理时间计时,实际Worker执行后查询开始时间;重报原请求仍返回原任务及时间。
  • 自动失败重试单独使用retry策略,初始延迟不在每次尝试中重新计时。

已可运行:健康检查

  • 源码:SDK 健康检查。
  • 前置:已迁移的 MySQL 与已启动的基础服务。
  • 操作与预期输出:SDK 接入说明。
  • 异常:数据库不可用或迁移记录异常时 readiness 返回 HTTP 503,SDK 返回类型化状态错误。
  • 清理:只读调用,无业务资源需要删除。

已可运行:文件转换任务的受理与取消

  • 源码:SDK 任务受理示例。
  • 前置:完成迁移、初始化凭据、启动服务,在没有 Worker 消费的专用队列运行此受理/取消示例,详见 SDK 接入。
  • 输入:对象引用、格式与精确整数;提交两次同一身份,再查询、分页并带版本取消。
  • 预期:重复请求返回同一任务,最终 CANCELLED/revision=2,source_kind=DIRECT。当前不启动 Worker,不实际生成文件。
  • 异常:凭据失效、权限不足、内容冲突、版本竞争和未知网络结果,见 任务接口。
  • 清理:示例以取消结束;任务和审计历史保留。重复运行会生成独立示例任务。

已可运行:文本规范化执行

  • 源码:Worker 底层协议示例。
  • 前置:专用 Worker 凭据,启动步骤见 Worker SDK 文档。
  • 输入与步骤:提交 {"text":" Hello Orbit "} → 注册/容量 → 领取 → 开始授权 → 实际处理 → 确认结果 → 查询 → 排空。
  • 预期:SUCCEEDED、一次尝试、结果 {"text":"HELLO ORBIT"}。
  • 异常:底层示例使用原身份有限重报控制 ACK;业务函数不随重连再次调用;迟到证据不能当作成功结果。自动续租与持续消费见下方运行器示例。
  • 清理:任务历史保留;运行结束确认排空并关闭连接。每次示例使用独立任务/处理器身份。

已可运行:自动 Worker 并发消费

  • 源码:自动 Worker 示例,接入与启动命令。
  • 步骤:注册版本化处理器 → Run → 以容量 2 消费三条文本任务 → 查询结果 → 取消 Run context 并等待排空。
  • 预期:三条规范化结果、started=3、confirmed=3、running=0;输入与结果均由实际代码处理。
  • 异常:自动心跳/续租与原身份重连;普通错误/panic 按未知效果报告,超时退出不声称杀死 goroutine;完整故障证据见 回归记录。
  • 清理:正常排空关闭连接,保留历史;进程被强杀后的在途状态由租约恢复与核查衔接。

已可运行:执行历史与冲突证据核对

  • 源码:执行历史示例,启动命令和输入输出。
  • 前置:迁移到当前版本、启动服务,专用凭据具备提交/读取与 Worker 权限。
  • 步骤:创建模拟任务 → 开始授权 → 保存 v1 结果 → 用另一消息身份报告 v2 → 查询尝试/证据列表与详情 → 核对任务仍保留 v1。
  • 预期:SUCCEEDED、attempts=1、evidence=1、reason=RESULT_CONFLICT、disposition=EVIDENCE_ONLY;实际结果中的大整数保持精确。
  • 异常:迟到或矛盾内容不能覆盖权威结果;缺少动作权限返回 403,错配父资源、跨命名空间或队列越权返回 404,详见 接口。示例不调用外部业务系统。
  • 清理:正常结束确认排空并关闭连接;任务及证据保留用于追踪,不硬删除。重复运行创建独立任务。

已可运行:有限安全重试

  • 源码:重试示例,完整启动命令与结果。
  • 前置:当前迁移及服务,具有提交、读取和 Worker 权限的专用凭据。
  • 步骤:第一次在产生效果前模拟明确拒绝 → 平台持久化退避 → 第二次处理文本 → 查询两次尝试 → 排空。
  • 预期:SUCCEEDED、attempts=2、first_retryable=true、结果 {"text":"SAFE RETRY"};Worker started=2、confirmed=2、running=0。
  • 异常:次数/时限耗尽停止重试;未知效果默认转核查。Retryable=true 需要明确的安全依据,不能用于普通网络超时。
  • 清理:示例不调用外部业务系统,每次创建独立任务并保留历史;失败时非零退出并有界收尾。

已可运行:周期对象快照

  • 源码:调度示例,初始化、调用与输出。
  • 前置:当前迁移、服务,显式 --schedule-access 与 --worker-access 的专用开发凭据。
  • 步骤:创建暂停的有限每秒计划 → 恢复 → 自动 Worker 返回输入快照 → 查到至少两次任务成功 → 暂停并排空。
  • 预期:不同 occurrence/task 身份、相同计划版本、paused=true、running=0;精确整数保留。
  • 异常:串行前项未知时不新建后续任务;恢复按版本与漏跑策略处理,超过窗口记录跳过。暂停不撤销已生成任务。
  • 清理:计划最终暂停,自带十秒结束边界;失败非零退出,历史保留,无外部业务副作用。

已可运行:运行中任务取消

  • 源码:取消示例,初始化、调用与输出。
  • 前置:当前迁移、全部服务节点升级完成,凭据具备任务提交/读取/取消和 Worker 权限。
  • 步骤:提交并开始受控任务 → 保存取消意图 → 处理器遵守 context 停止 → 明确确认本次无未结清效果 → 查询最终状态并排空。
  • 预期:accepted_state=RUNNING、final_state=CANCELLED、attempts=1、running=0。
  • 异常:普通 context 错误、通知丢失和未配合停止不能自动判定取消成功;未知效果进入核查。CAS 冲突先查询,网络结果未知保留原身份核对。
  • 清理:无外部业务副作用;历史保留,每次运行独立身份,失败非零退出并有界收尾。

已可运行:队列限速与积压背压

  • 源码:资源控制示例,初始化、字段与完整输出。
  • 前置:当前迁移与服务,凭据具备全部队列的 queues:manage、任务及 Worker 权限。
  • 步骤:创建并暂停积压上限为 2 的队列 → 第三个任务被 429 拒绝 → 满额下核对第一条原回执 → 取消释放空间 → 用被拒原身份再提交 → 恢复并按每秒 1 次开始执行。
  • 预期:QUEUE_FULL、duplicate=true、两个任务 SUCCEEDED/attempts=1、unfinished=0。
  • 异常:网络结果未知保留原身份,降额不清零用量,待核查任务仍占名额;跨节点及重启证据见 资源回归。
  • 清理:每次新建独立队列,任务 20 秒总截止;无外部副作用,历史保留,失败非零退出并有界收尾。

已可运行:跨命名空间共享配额

  • 源码:应用资源示例,双命名空间初始化、字段和输出。
  • 前置:同一独立、空闲示例应用下的两个命名空间,凭据显式具备应用资源管理权限;不需要 Worker。
  • 步骤:应用上限设为 1 → first 受理 → second 全局满额 → 取消 first → second 以原受理键成功 → 取消收尾并按 CAS 恢复配置。
  • 预期:APPLICATION_FULL/429、same_identity_retry_accepted=true、三个用量归零。
  • 异常:普通队列管理员不能改应用额度;恢复配置遇到新版本冲突时不覆盖。进程强杀后不能保证清理,遗留任务受总时限约束,须按原身份核对。
  • 清理:正常完成取消示例任务并恢复配置;历史保留,无业务副作用、无硬删除。

计划场景与验收标准

已可运行的 优先级场景 提供 完整源码:按 0、9、4 受理后,以单槽 Worker 按 9、4、0 完成近同时到期的任务。前置为当前迁移/服务与队列、任务及 Worker 权限;预期 completed=3、attempts_per_task=1、worker_drained=true。无外部业务副作用,历史保留,失败非零退出,任务自带总时限;长等待补偿和其他应用隔离由真实数据库回归验证。

已可运行的 跨队列资源互斥场景 提供 完整源码:两个队列的自动 Worker 操作同一资源,核对递增序号,并模拟资源端拒绝旧写入。输入使用显式 concurrency_key;预期 completed=2、resource_writes=2、stale_write_rejected=true。示例仅使用受控内存资源,无外部副作用;正常排空、保留历史,任务自带总时限。内存 mutex 不是生产分布式存储,生产必须在资源端原子持久化序号、操作身份和实际更新。

场景 输入与步骤 预期结果 必测异常 状态
文件转换 对象引用 → 提交任务 → Worker 转换 → 结果引用 同一操作获得一次业务结果,历史可查 重复提交、Worker 在结果上报前中断 受理与执行框架已实现,实际转换示例待补齐
定期同步 发布计划 → 周期触发 → 暂停 → 恢复 触发身份唯一,漏跑策略可追溯 多节点竞争、停机后补跑上限 P3 通用快照示例已完成,业务同步由接入方处理器实现
并行生成 输入对象 → 并行计算两份结果 → 汇合 两支满足条件后只创建一份后继工作 一支失败、重复结果、汇合竞争 P4 待开发
等待审核 校验 → 等待信号 → 发布结果 只接受授权、匹配当前操作的信号 早到、重复、过期与越权信号 P4 待开发
外部作业查询 提交一次 → 间隔查询 → 最终结果 处理中消耗轮次,请求失败消耗尝试 回执与查询竞争、预算耗尽、响应未知 P5 待开发
暂停与恢复 暂停 → 接收在途结果 → 核查 → 继续 历史与预算保留,已成功工作不重复 暂停/开始竞争、恢复时已过期 P5 待开发

每个待开发场景最终都需提供独立目录、完整源码、配置模板、启动与验证命令,不能只留下概念流程图。配套回归会先使用可控的模拟处理器或外部服务,不对真实系统产生副作用。

已可运行:订阅管理与幂等回执

  • 源码:订阅管理示例,启动、输入输出和异常说明。
  • 前置:当前迁移及服务,具备 events:manage/read/consume 的专用开发凭据;初始化显式 --event-access。
  • 步骤:创建 → 同键核对 → 暂停 → 恢复 → 查询与分页 → 最终暂停。
  • 预期:duplicate=true、resumed_revision=3、final_enabled=false、revision=4、pending=0。
  • 保留:每次运行留下一个已暂停订阅及审计;没有硬删除,受64个订阅上限约束。
  • 范围:本例只演示管理SDK;自动消费 SDK 已实现,持久化Inbox例子 已独立交付。

已可运行:结果消费协议与跨连接确认

  • 源码:事件协议示例,启动与输出说明。
  • 操作:创建订阅 → 提交并取消任务 → 接收冻结结果 → ACK → 重连重报原证明 → 核对原确认时间 → 暂停订阅。
  • 输出:ack_replayed=true、same_receipt=true、pending=0、subscription_enabled=false。
  • 范围:本例只做读取验证,不写业务数据;自动消费器 的生产接入须提供事务Inbox,不能把示例当作业务恰好一次保证。

已可运行:独立业务 MySQL Inbox

  • 独立项目:result-inbox,完整前置、命令及故障说明。
  • 操作:接收冻结结果 → Inbox与业务视图同事务提交 → 重复核对 → ACK → 暂停本次演示订阅。
  • 输出:inbox_duplicate=true、applied_events=1、ack_confirmed=1、pending=0。
  • 覆盖:并发重复、旧版本保护、回滚、真实MySQL COMMIT响应丢失、业务提交后/ACK前消费者SIGKILL及新进程去重。
  • 边界:只覆盖接收方本地SQL效果;核心SDK不依赖数据库,外部副作用需要接收方自己的幂等/Outbox设计。

已可运行:批量受理与部分补交

  • 源码:batch,完整启动命令和输出。
  • 步骤:独立暂停队列 → 三项批量提交、两项成功一项满额 → 整批核对原回执 → 取消释放额度 → 仅原身份补交第三项 → 取消收尾。
  • 预期:accepted=2、replayed=2、retried_items=1、unfinished=0。
  • 异常:逐项区分REJECTED/UNKNOWN/NOT_ATTEMPTED;真实HTTP响应丢失后恢复无重复,保留当前权限和额度控制。
  • 范围:示例只演示受理,不转换文件、不提供业务Outbox;失败非零退出,每项60秒总时限,保留队列及审计。

已可运行:独立任务人工核查与关联重试

  • 源码:recovery,完整运行与失败说明。
  • 步骤:模拟UNKNOWN → 人工声明历史执行结束 → 核查FAILED → 原键核对 → 创建retry_of关联新任务 → 执行成功 → 查询原任务及操作审计。
  • 预期:原任务FAILED、新任务SUCCEEDED,原尝试和审计保留;管理凭据显式--recovery-access。
  • 异常:真实HTTP在核查/重试提交后丢响应,原身份恢复同一审计和新任务;迟到成功只进入证据。
  • 范围:本例不操作外部系统,不能替代真实证据核查、业务幂等或持久化管理操作Outbox。

已可运行:业务键和创建时间查询

  • 源码:task-query,完整启动与异常说明。
  • 步骤:提交三个模拟任务 → 精确业务键及时间范围过滤 → 每页一条遍历 → 验证上界排除 → 取消收尾。
  • 预期:matched=2、pages=2、before_excluded=true、cancelled=3。
  • 范围:普通提交/读取/取消权限;不调用外部系统、不启动Worker,所有历史保留,状态分页不是数据库快照。

已可运行:从任务定位来源

  • 来源接口与SDK随现有tasks、schedules、recovery三个示例运行,无额外服务或数据库表。
  • 步骤:取得任务ID → GetTaskSource → 区分普通提交/人工重试/计划触发 → 按权限读取父任务或固定计划版本。
  • 预期:source_kind分别为DIRECT、MANUAL_RETRY、SCHEDULE;人工重试关联原任务,计划任务保留实际触发版本。
  • 异常:来源缺失或归属不匹配返回503,不能降级为DIRECT;新计划版本不覆盖历史版本,引用查询不授予计划定义读取权限。