k2safe/orbit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate runnable examples and publish v0.1.1 guides

Browse Source
This commit is contained in:
k2safe
2026-09-24 21:27:25 +08:00
parent e29dec717f
commit 81e56bd633
124 changed files with 1430 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/examples/README.md
View File

@@ -1,16 +1,18 @@
# 通用场景示例
完整源码已统一放在根目录 [examples/](../../examples/README.md)，共有 27 个可运行场景；各目录 README 提供命令和预期结果。首次接入先看[仓库 README](../../README.md)。
示例只使用通用的作业、对象、文件、资源与审核信号，不包含接入方项目名称或行业规则。
## 已可运行：研发定义与发布流程
- [完整命令和结果](workflow-definition.md)、[SDK源码](../../sdk/go/examples/workflow-definition/main.go)。
- [完整命令和结果](workflow-definition.md)、[SDK源码](../../examples/workflow-definition/main.go)。
- 六类节点的有限结构定义、原键及同版本确认、新版本发布、旧版本读取保持不变。
- 本例只发布定义；实际运行见下方流程示例。
## 已可运行：并行作业、定时等待与外部回执
- [完整命令、输入输出与失败处理](workflow.md)、[独立SDK源码](../../sdk/go/examples/workflow/main.go)。
- [完整命令、输入输出与失败处理](workflow.md)、[独立SDK源码](../../examples/workflow/main.go)。
- 两个任务并行处理并汇合，计时等待后接收显式目标代次的信号，再执行后续任务；最终三个任务完成并有界排空。
- 启动及信号原键重复不会建立新的实例或信号；分页查看原状态事件，核对信号消费及赢家等待。
@@ -32,13 +34,13 @@
## 已可运行：相对延迟执行
- [完整命令、输入输出和失败处理](delayed-task.md)，[SDK源码](../../sdk/go/examples/delayed-task/main.go)。
- [完整命令、输入输出和失败处理](delayed-task.md)，[SDK源码](../../examples/delayed-task/main.go)。
- delay_ms按数据库首次受理时间计时，实际Worker执行后查询开始时间；重报原请求仍返回原任务及时间。
- 自动失败重试单独使用retry策略，初始延迟不在每次尝试中重新计时。
## 已可运行：健康检查
- 源码：[SDK 健康检查](../../sdk/go/examples/health/main.go)。
- 源码：[SDK 健康检查](../../examples/health/main.go)。
- 前置：已迁移的 MySQL 与已启动的基础服务。
- 操作与预期输出：[SDK 接入说明](../sdk/README.md)。
- 异常：数据库不可用或迁移记录异常时 readiness 返回 HTTP 503，SDK 返回类型化状态错误。
@@ -46,7 +48,7 @@
## 已可运行：文件转换任务的受理与取消
- 源码：[SDK 任务受理示例](../../sdk/go/examples/tasks/main.go)。
- 源码：[SDK 任务受理示例](../../examples/tasks/main.go)。
- 前置：完成迁移、初始化凭据、启动服务，在没有 Worker 消费的专用队列运行此受理/取消示例，详见 [SDK 接入](../sdk/README.md)。
- 输入：对象引用、格式与精确整数；提交两次同一身份，再查询、分页并带版本取消。
- 预期：重复请求返回同一任务，最终 CANCELLED/revision=2，source_kind=DIRECT。当前不启动 Worker，不实际生成文件。
@@ -55,7 +57,7 @@
## 已可运行：文件格式转换执行
- 源码：[CSV→JSON Worker 示例](../../sdk/go/examples/file-conversion/main.go)，[完整说明](file-conversion.md)。
- 源码：[CSV→JSON Worker 示例](../../examples/file-conversion/main.go)，[完整说明](file-conversion.md)。
- 前置：专用 Worker 凭据、已启动服务和当前迁移；标准隔离回归会自动运行本例。
- 输入与步骤：提交带稳定操作键的两行 CSV 快照 → Worker 注册 `file.convert.csv-json` v1 → 领取、授权并转换 → 查询 JSON 结果 → 排空。
- 预期：`SUCCEEDED`、一次尝试、`records.json`、`rows=2`，重复提交仍沿用原任务身份。
@@ -63,7 +65,7 @@
## 已可运行：文本规范化执行
- 源码：[Worker 底层协议示例](../../sdk/go/examples/worker-protocol/main.go)。
- 源码：[Worker 底层协议示例](../../examples/worker-protocol/main.go)。
- 前置：专用 Worker 凭据，启动步骤见 [Worker SDK 文档](../sdk/worker.md)。
- 输入与步骤：提交 `{"text":" Hello Orbit "}` → 注册/容量 → 领取 → 开始授权 → 实际处理 → 确认结果 → 查询 → 排空。
- 预期：SUCCEEDED、一次尝试、结果 `{"text":"HELLO ORBIT"}`。
@@ -72,7 +74,7 @@
## 已可运行：自动 Worker 并发消费
- 源码：[自动 Worker 示例](../../sdk/go/examples/worker/main.go)，[接入与启动命令](../sdk/worker-runtime.md)。
- 源码：[自动 Worker 示例](../../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)。
@@ -80,7 +82,7 @@
## 已可运行：执行历史与冲突证据核对
- 源码：[执行历史示例](../../sdk/go/examples/history/main.go)，[启动命令和输入输出](../sdk/README.md#6-查询执行历史与证据)。
- 源码：[执行历史示例](../../examples/history/main.go)，[启动命令和输入输出](../sdk/README.md#6-查询执行历史与证据)。
- 前置：迁移到当前版本、启动服务，专用凭据具备提交/读取与 Worker 权限。
- 步骤：创建模拟任务 → 开始授权 → 保存 v1 结果 → 用另一消息身份报告 v2 → 查询尝试/证据列表与详情 → 核对任务仍保留 v1。
- 预期：SUCCEEDED、attempts=1、evidence=1、reason=RESULT_CONFLICT、disposition=EVIDENCE_ONLY；实际结果中的大整数保持精确。
@@ -89,7 +91,7 @@
## 已可运行：有限安全重试
- 源码：[重试示例](../../sdk/go/examples/retry/main.go)，[完整启动命令与结果](../api/retries.md#5-运行完整示例)。
- 源码：[重试示例](../../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。
@@ -98,7 +100,7 @@
## 已可运行：周期对象快照
- 源码：[调度示例](../../sdk/go/examples/schedules/main.go)，[初始化、调用与输出](../api/schedules.md#6-sdk-与完整示例)。
- 源码：[调度示例](../../examples/schedules/main.go)，[初始化、调用与输出](../api/schedules.md#6-sdk-与完整示例)。
- 前置：当前迁移、服务，显式 --schedule-access 与 --worker-access 的专用开发凭据。
- 步骤：创建暂停的有限每秒计划 → 恢复 → 自动 Worker 返回输入快照 → 查到至少两次任务成功 → 暂停并排空。
- 预期：不同 occurrence/task 身份、相同计划版本、paused=true、running=0；精确整数保留。
@@ -107,7 +109,7 @@
## 已可运行：运行中任务取消
- 源码：[取消示例](../../sdk/go/examples/cancellation/main.go)，[初始化、调用与输出](../api/cancellation.md)。
- 源码：[取消示例](../../examples/cancellation/main.go)，[初始化、调用与输出](../api/cancellation.md)。
- 前置：当前迁移、全部服务节点升级完成，凭据具备任务提交/读取/取消和 Worker 权限。
- 步骤：提交并开始受控任务 → 保存取消意图 → 处理器遵守 context 停止 → 明确确认本次无未结清效果 → 查询最终状态并排空。
- 预期：accepted_state=RUNNING、final_state=CANCELLED、attempts=1、running=0。
@@ -116,7 +118,7 @@
## 已可运行：队列限速与积压背压
- 源码：[资源控制示例](../../sdk/go/examples/resources/main.go)，[初始化、字段与完整输出](../api/queues.md)。
- 源码：[资源控制示例](../../examples/resources/main.go)，[初始化、字段与完整输出](../api/queues.md)。
- 前置：当前迁移与服务，凭据具备全部队列的 queues:manage、任务及 Worker 权限。
- 步骤：创建并暂停积压上限为 2 的队列 → 第三个任务被 429 拒绝 → 满额下核对第一条原回执 → 取消释放空间 → 用被拒原身份再提交 → 恢复并按每秒 1 次开始执行。
- 预期：QUEUE_FULL、duplicate=true、两个任务 SUCCEEDED/attempts=1、unfinished=0。
@@ -125,7 +127,7 @@
## 已可运行：跨命名空间共享配额
- 源码：[应用资源示例](../../sdk/go/examples/application-resources/main.go)，[双命名空间初始化、字段和输出](../api/application-resources.md)。
- 源码：[应用资源示例](../../examples/application-resources/main.go)，[双命名空间初始化、字段和输出](../api/application-resources.md)。
- 前置：同一独立、空闲示例应用下的两个命名空间，凭据显式具备应用资源管理权限；不需要 Worker。
- 步骤：应用上限设为 1 → first 受理 → second 全局满额 → 取消 first → second 以原受理键成功 → 取消收尾并按 CAS 恢复配置。
- 预期：APPLICATION_FULL/429、same_identity_retry_accepted=true、三个用量归零。
@@ -134,9 +136,9 @@
## 计划场景与验收标准
已可运行的 [优先级场景](../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/priority-and-fairness.md#4-sdk-完整场景) 提供 [完整源码](../../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 不是生产分布式存储，生产必须在资源端原子持久化序号、操作身份和实际更新。
已可运行的 [跨队列资源互斥场景](../api/keyed-concurrency.md#5-完整可运行场景) 提供 [完整源码](../../examples/keyed-concurrency/main.go)：两个队列的自动 Worker 操作同一资源，核对递增序号，并模拟资源端拒绝旧写入。输入使用显式 concurrency_key；预期 completed=2、resource_writes=2、stale_write_rejected=true。示例仅使用受控内存资源，无外部副作用；正常排空、保留历史，任务自带总时限。内存 mutex 不是生产分布式存储，生产必须在资源端原子持久化序号、操作身份和实际更新。
| 场景 | 输入与步骤 | 预期结果 | 必测异常 | 状态 |
| --- | --- | --- | --- | --- |
@@ -151,7 +153,7 @@
## 已可运行：订阅管理与幂等回执
- 源码：[订阅管理示例](../../sdk/go/examples/subscriptions/main.go)，[启动、输入输出和异常说明](subscriptions.md)。
- 源码：[订阅管理示例](../../examples/subscriptions/main.go)，[启动、输入输出和异常说明](subscriptions.md)。
- 前置：当前迁移及服务，具备 events:manage/read/consume 的专用开发凭据；初始化显式 --event-access。
- 步骤：创建 → 同键核对 → 暂停 → 恢复 → 查询与分页 → 最终暂停。
- 预期：duplicate=true、resumed_revision=3、final_enabled=false、revision=4、pending=0。
@@ -160,7 +162,7 @@
## 已可运行：结果消费协议与跨连接确认
- 源码：[事件协议示例](../../sdk/go/examples/event-protocol/main.go)，[启动与输出说明](event-protocol.md)。
- 源码：[事件协议示例](../../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，不能把示例当作业务恰好一次保证。
@@ -175,7 +177,7 @@
## 已可运行：批量受理与部分补交
- 源码：[batch](../../sdk/go/examples/batch/main.go)，[完整启动命令和输出](batch.md)。
- 源码：[batch](../../examples/batch/main.go)，[完整启动命令和输出](batch.md)。
- 步骤：独立暂停队列 → 三项批量提交、两项成功一项满额 → 整批核对原回执 → 取消释放额度 → 仅原身份补交第三项 → 取消收尾。
- 预期：accepted=2、replayed=2、retried_items=1、unfinished=0。
- 异常：逐项区分REJECTED/UNKNOWN/NOT_ATTEMPTED；真实HTTP响应丢失后恢复无重复，保留当前权限和额度控制。
@@ -183,7 +185,7 @@
## 已可运行：独立任务人工核查与关联重试
- 源码：[recovery](../../sdk/go/examples/recovery/main.go)，[完整运行与失败说明](recovery.md)。
- 源码：[recovery](../../examples/recovery/main.go)，[完整运行与失败说明](recovery.md)。
- 步骤：模拟UNKNOWN → 人工声明历史执行结束 → 核查FAILED → 原键核对 → 创建retry_of关联新任务 → 执行成功 → 查询原任务及操作审计。
- 预期：原任务FAILED、新任务SUCCEEDED，原尝试和审计保留；管理凭据显式--recovery-access。
- 异常：真实HTTP在核查/重试提交后丢响应，原身份恢复同一审计和新任务；迟到成功只进入证据。
@@ -191,7 +193,7 @@
## 已可运行：业务键和创建时间查询
- 源码：[task-query](../../sdk/go/examples/task-query/main.go)，[完整启动与异常说明](task-query.md)。
- 源码：[task-query](../../examples/task-query/main.go)，[完整启动与异常说明](task-query.md)。
- 步骤：提交三个模拟任务 → 精确业务键及时间范围过滤 → 每页一条遍历 → 验证上界排除 → 取消收尾。
- 预期：matched=2、pages=2、before_excluded=true、cancelled=3。
- 范围：普通提交/读取/取消权限；不调用外部系统、不启动Worker，所有历史保留，状态分页不是数据库快照。

8
docs/examples/batch.md
View File

@@ -1,6 +1,6 @@
# 批量文件作业受理与部分补交
[完整源码](../../sdk/go/examples/batch/main.go) 使用独立Go SDK，不导入服务端模型或数据库驱动。它演示受理与取消，不启动Worker或转换真实文件。
[完整源码](../../examples/batch/main.go) 使用独立Go SDK，不导入服务端模型或数据库驱动。它演示受理与取消，不启动Worker或转换真实文件。
## 前置与运行
@@ -21,10 +21,10 @@ go run ./cmd/orbit
另开终端：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/batch.credentials.json \
go run ./examples/batch
ORBIT_CREDENTIALS_FILE=../.local/batch.credentials.json \
go run ./batch
```
也接受ORBIT_TOKEN，环境值优先。示例自行创建并暂停一个独立队列，未终结上限为2，不改变已有队列或应用配置。前置应用剩余额度至少2。

8
docs/examples/delayed-task.md
View File

@@ -1,16 +1,16 @@
# 相对延迟与原请求恢复
源码：[delayed-task/main.go](../../sdk/go/examples/delayed-task/main.go)。示例提交等待1500毫秒的对象任务，启动自动Worker，核对实际执行历史，再在任务完成后重报原请求。处理器原样返回示例JSON，无外部副作用。
源码：[delayed-task/main.go](../../examples/delayed-task/main.go)。示例提交等待1500毫秒的对象任务，启动自动Worker，核对实际执行历史，再在任务完成后重报原请求。处理器原样返回示例JSON，无外部副作用。
## 准备与运行
先完成[迁移和Worker凭据初始化](../sdk/worker.md#1-可运行的文本规范化示例)，启动当前Orbit。凭据需要任务提交、读取及Worker连接/消费权限，队列须有可用额度。仓库根目录执行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/worker.credentials.json \
go run ./examples/delayed-task
ORBIT_CREDENTIALS_FILE=../.local/worker.credentials.json \
go run ./delayed-task
```
也可用ORBIT_TOKEN和ORBIT_QUEUE_ID覆盖凭据文件中的对应值。示例总上下文20秒、任务总时限15秒、单次执行5秒、最多1次尝试；每次运行使用独立操作及处理器身份，不会消费其他处理器的任务。

9
docs/examples/event-protocol.md
View File

@@ -1,6 +1,6 @@
# 结果消费协议示例
[完整代码](../../sdk/go/examples/event-protocol/main.go) 使用正式 Go SDK 创建取消结果订阅，提交并取消一个待执行任务，接收并验证冻结结果，然后 ACK；关闭连接后在新连接中重报原证明，验证原确认时间和去重回执，最后暂停本次订阅。
[完整代码](../../examples/event-protocol/main.go) 使用正式 Go SDK 创建取消结果订阅，提交并取消一个待执行任务，接收并验证冻结结果，然后 ACK；关闭连接后在新连接中重报原证明，验证原确认时间和去重回执，最后暂停本次订阅。
本例只读取并验证结果，没有业务数据库写入。生产业务应使用 [自动消费器及事务去重约定](../sdk/event-consumer.md)。持久化接入见 [独立 MySQL Inbox 示例](result-inbox.md)。
@@ -8,12 +8,13 @@
先按 [订阅管理示例](subscriptions.md) 建立隔离示例队列和带 --event-access 的凭据，启动 Orbit。凭据需要 tasks:submit、tasks:cancel、events:manage/read/consume 及该队列范围；订阅绑定创建凭据，不能临时换凭据消费。
从 sdk/go 目录运行：
从仓库根目录进入 examples 后运行：
```sh
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/event.credentials.json \
go run ./examples/event-protocol
ORBIT_CREDENTIALS_FILE=../.local/event.credentials.json \
go run ./event-protocol
```
也可以传 ORBIT_TOKEN 与 ORBIT_QUEUE_ID，环境变量覆盖凭据文件对应值。每次运行新建随机订阅及任务身份，全部流程最多 15 秒。本例是短流程，两个连接均短于一次心跳周期；长期运行必须用自动消费器或主动 Ping。

10
docs/examples/file-conversion.md
View File

@@ -7,10 +7,10 @@
需要当前迁移、已启动 Orbit 服务，以及具备任务提交/读取和 Worker 消费权限的专用凭据。凭据文件应只保存在本地受保护目录：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/worker.credentials.json \
go run ./examples/file-conversion
ORBIT_CREDENTIALS_FILE=../.local/worker.credentials.json \
go run ./file-conversion
```
## 调用链与预期
@@ -50,8 +50,8 @@ input=records.csv output=records.json rows=2 state=SUCCEEDED worker_drained=true
单元转换校验：
```sh
cd sdk/go
GOWORK=off go test ./examples/file-conversion
cd examples
GOWORK=off go test ./file-conversion
```
`make integration` 会在一次性 MySQL 和真实 Orbit HTTP 服务上运行该示例，确认提交、Worker 执行、结果查询和排空均通过。该场景不证明外部对象存储的持久性，也不替代生产容量、故障切换或 RPO/RTO 验收。

8
docs/examples/recovery.md
View File

@@ -1,6 +1,6 @@
# 未知结果的核查与人工重试示例
完整源码：[SDK recovery/main.go](../../sdk/go/examples/recovery/main.go)。只处理本地模拟对象，不调用任何真实外部业务系统。接口细节见[人工恢复手册](../api/task-recovery.md)。
完整源码：[SDK recovery/main.go](../../examples/recovery/main.go)。只处理本地模拟对象，不调用任何真实外部业务系统。接口细节见[人工恢复手册](../api/task-recovery.md)。
## 准备与运行
@@ -20,10 +20,10 @@ go run ./cmd/orbit
另开终端，从仓库根目录执行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/recovery.credentials.json \
go run ./examples/recovery
ORBIT_CREDENTIALS_FILE=../.local/recovery.credentials.json \
go run ./recovery
```
演示凭据为了完整运行同时包含Worker与人工管理权限；生产将它们分开。凭据文件0600、token不输出；也接受ORBIT_TOKEN/ORBIT_QUEUE_ID，环境值优先。

8
docs/examples/subscriptions.md
View File

@@ -1,6 +1,6 @@
# 订阅管理与幂等回执示例
状态：已提供 [完整可运行源码](../../sdk/go/examples/subscriptions/main.go)。演示 HTTP 管理 SDK；完整结果消费、重连及持久化 Inbox 示例继续开发。协议与字段见 [订阅接口](../api/subscriptions.md)。
状态：已提供 [完整可运行源码](../../examples/subscriptions/main.go)。演示 HTTP 管理 SDK；完整结果消费、重连及持久化 Inbox 示例继续开发。协议与字段见 [订阅接口](../api/subscriptions.md)。
## 前置和运行
@@ -19,10 +19,10 @@ go run ./cmd/orbit
另一个终端从仓库根目录执行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/subscriptions.credentials.json \
go run ./examples/subscriptions
ORBIT_CREDENTIALS_FILE=../.local/subscriptions.credentials.json \
go run ./subscriptions
```
也可设置 ORBIT_TOKEN 和 ORBIT_QUEUE_ID，环境值优先于凭据文件。生产接入使用 HTTPS；不要提交凭据文件或在命令行打印秘密。

8
docs/examples/task-query.md
View File

@@ -1,16 +1,16 @@
# 业务键与时间范围查询示例
源码：[task-query/main.go](../../sdk/go/examples/task-query/main.go)。本例提交三个模拟对象任务，不启动Worker，演示精确业务键、创建时间区间和任务摘要分页。
源码：[task-query/main.go](../../examples/task-query/main.go)。本例提交三个模拟对象任务，不启动Worker，演示精确业务键、创建时间区间和任务摘要分页。
## 准备与运行
按[SDK初始化步骤](../sdk/README.md)迁移数据库、初始化专用开发队列及普通提交/读取/取消凭据，启动当前Orbit服务。从仓库根目录执行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/development.credentials.json \
go run ./examples/task-query
ORBIT_CREDENTIALS_FILE=../.local/development.credentials.json \
go run ./task-query
```
也可使用ORBIT_TOKEN与ORBIT_QUEUE_ID，环境值优先。无需额外管理权限，凭据秘密不输出。队列应有至少三个未终结任务空位；每次运行的处理器与业务键带独立标识，避免已有任务干扰。

6
docs/examples/workflow-definition.md
View File

@@ -2,7 +2,7 @@
本例运行真实HTTP发布与读取，验证六种节点的格式以及不可变版本。当前不创建流程实例、不执行外部业务。实际运行另见[并行作业与回执示例](workflow.md)。
源码：[workflow-definition/main.go](../../sdk/go/examples/workflow-definition/main.go)。接口：[定义发布](../api/workflow-definitions.md)；字段规范：[结构版本1](../api/workflow-definition-format.md)。
源码：[workflow-definition/main.go](../../examples/workflow-definition/main.go)。接口：[定义发布](../api/workflow-definitions.md)；字段规范：[结构版本1](../api/workflow-definition-format.md)。
## 1. 准备与运行
@@ -15,11 +15,11 @@ bin/orbit-admin bootstrap --application definition-demo --namespace default --en
首次创建文件后保留，不要覆盖或打印凭据内容。该标志只增加定义读取和发布动作；生产凭据应限制到需要的命名空间及队列。
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=/tmp/orbit-definition.credentials.json \
ORBIT_OPERATION_ID=object-definition-demo-001 \
go run ./examples/workflow-definition
go run ./workflow-definition
```
开发回环地址可用HTTP，生产使用HTTPS。可改用`ORBIT_TOKEN`及`ORBIT_QUEUE_ID`，不把Token写入URL或提交版本库。不传`ORBIT_OPERATION_ID`时随机生成并先输出；发生未知结果时保存此操作ID，保持相同队列及源码再次运行。已成功的相同操作ID也可以重复执行，旧版本与revision不会增加。

8
docs/examples/workflow-poll.md
View File

@@ -1,6 +1,6 @@
# 有界轮询：请求重试与业务轮次分别计数
[完整源码](../../sdk/go/examples/workflow-poll/main.go)通过公共SDK发布POLL定义，启动真实Worker，并请求一个本机HTTP渠道夹具。流程先由TASK向本机渠道提交一次作业，受理回执提供固定operation_id，随后POLL只查询这个作业；平台没有集成任何具体业务渠道。
[完整源码](../../examples/workflow-poll/main.go)通过公共SDK发布POLL定义，启动真实Worker，并请求一个本机HTTP渠道夹具。流程先由TASK向本机渠道提交一次作业，受理回执提供固定operation_id，随后POLL只查询这个作业；平台没有集成任何具体业务渠道。
同一命令依次运行两个流程：
@@ -27,10 +27,10 @@ go run ./cmd/orbit
bootstrap只执行一次，凭据文件存在时不会覆盖。另开终端，从仓库根目录运行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/poll.credentials.json \
go run ./examples/workflow-poll
ORBIT_CREDENTIALS_FILE=../.local/poll.credentials.json \
go run ./workflow-poll
```
程序自行创建并关闭本机HTTP夹具，不需要启动第三方系统，不向公网提交操作。正式接入使用HTTPS/WSS和分角色凭据，将只读查询处理器替换为自己的渠道调用。

8
docs/examples/workflow-query.md
View File

@@ -2,7 +2,7 @@
场景：一个对象关联多次处理流程，管理端需要按固定定义版本、精确业务关联及时间范围查询等待中的实例，再进入详情处理。示例同时证明业务键末尾有无空格属于不同关联。
源码：[workflow-query/main.go](../../sdk/go/examples/workflow-query/main.go)。服务端入口：[筛选接口](../api/workflow-queries.md)。示例发布一个SIGNAL等待流程，创建三个实例，其中两个使用相同业务键、第三个去掉尾部空格；每页1项读取匹配的两个实例，最后将三个实例取消并等待CANCELLED。
源码：[workflow-query/main.go](../../examples/workflow-query/main.go)。服务端入口：[筛选接口](../api/workflow-queries.md)。示例发布一个SIGNAL等待流程，创建三个实例，其中两个使用相同业务键、第三个去掉尾部空格；每页1项读取匹配的两个实例，最后将三个实例取消并等待CANCELLED。
## 启动
@@ -22,10 +22,10 @@ go run ./cmd/orbit
另开终端：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/workflow-query.credentials.json \
go run ./examples/workflow-query
ORBIT_CREDENTIALS_FILE=../.local/workflow-query.credentials.json \
go run ./workflow-query
```
查询本身只要求workflows:read。此完整示例额外需要研发创建/发布、启动与控制权限，由上述bootstrap选项授予。SIGNAL等待不用Worker，也不模拟外部业务成功；正常结束通过显式取消结清。

8
docs/examples/workflow-recovery.md
View File

@@ -1,6 +1,6 @@
# 提交后回执丢失：核查、暂停与有证据恢复
[完整源码](../../sdk/go/examples/workflow-recovery/main.go)使用真实Orbit、自动Worker和本机HTTP渠道夹具。夹具先保存外部提交结果，再直接关闭连接，确保Worker实际遇到传输错误。流程进入NEEDS_REVIEW后，程序在受控夹具中模拟一个已经核实事实的管理员，逐项提交恢复决定。
[完整源码](../../examples/workflow-recovery/main.go)使用真实Orbit、自动Worker和本机HTTP渠道夹具。夹具先保存外部提交结果，再直接关闭连接，确保Worker实际遇到传输错误。流程进入NEEDS_REVIEW后，程序在受控夹具中模拟一个已经核实事实的管理员，逐项提交恢复决定。
这是一份可运行的SDK接入与故障示例。夹具数据仅在本次进程内保存；真实系统需要持久证据和真实授权，不能把下面的演示核查逻辑接成任意业务的自动放行。
@@ -23,10 +23,10 @@ go run ./cmd/orbit
初始化一次；原凭据文件不会被覆盖。另开终端，从仓库根目录运行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/workflow-recovery.credentials.json \
go run ./examples/workflow-recovery
ORBIT_CREDENTIALS_FILE=../.local/workflow-recovery.credentials.json \
go run ./workflow-recovery
```
开发凭据包含定义、启动、Worker、控制、恢复及审计权限，便于单命令演示。正式接入应使用HTTPS/WSS，并为业务Worker与管理员分别签发所需权限；Worker执行权不自动授予恢复权。

8
docs/examples/workflow.md
View File

@@ -1,6 +1,6 @@
# 并行生成结果 → 等待外部回执 → 后续任务
[完整源码](../../sdk/go/examples/workflow/main.go)通过独立Go SDK发布固定版本、启动实例，并使用真实自动Worker处理任务。流程是两个文本规范化任务并行完成并汇合，等待500毫秒，等待模拟外部确认信号，最后用左侧输出执行发布步骤。输入为 `{"text":" hello orbit "}`，输出为 `{"text":"HELLO ORBIT"}`。
[完整源码](../../examples/workflow/main.go)通过独立Go SDK发布固定版本、启动实例，并使用真实自动Worker处理任务。流程是两个文本规范化任务并行完成并汇合，等待500毫秒，等待模拟外部确认信号，最后用左侧输出执行发布步骤。输入为 `{"text":" hello orbit "}`，输出为 `{"text":"HELLO ORBIT"}`。
## 1. 启动
@@ -21,10 +21,10 @@ go run ./cmd/orbit
初始化仅执行一次，文件存在时不会覆盖。重用该凭据运行例子无需重复bootstrap。另开终端，从仓库根目录执行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/workflow.credentials.json \
go run ./examples/workflow
ORBIT_CREDENTIALS_FILE=../.local/workflow.credentials.json \
go run ./workflow
```
生产使用HTTPS/WSS，并为定义发布者、启动者、信号发送者及Worker分别签发所需权限。本示例使用一个专用开发凭据，未申请人工恢复或控制权限。