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

32
docs/sdk/README.md
View File

@@ -1,6 +1,6 @@
# Go SDK 接入说明
已实现健康查询、任务单项与[批量提交](../api/batch-tasks.md)/查询/分页/待执行取消、队列创建/查询、[自动 Worker](worker-runtime.md)、[Worker 底层协议 SDK](worker.md) 和 [执行历史查询](../api/execution-history.md)。[人工核查与重试](../api/task-recovery.md) 已提供 ReviewTask、RetryTask 与任务操作审计查询。[安全重试](../api/retries.md) 已提供有限策略、WorkerFailure.Retryable、历史查询及完整例子。[计划调度](../api/schedules.md) 已支持创建、查询、版本发布、暂停/恢复、触发历史与完整示例。[订阅管理](../api/subscriptions.md) 已支持创建、查询、暂停恢复、交付历史与人工重试；[事件消费 SDK](event-consumer.md) 已支持连接、自动心跳、重连与确认。[流程定义发布](../api/workflow-definitions.md)、[实例/控制/信号/操作审计](../api/workflows.md)及[六类人工恢复](../api/workflow-recovery.md)已提供独立SDK；完整历史与更多场景按[开发计划](../08-development-plan.md)继续实现。
已实现健康查询、任务单项与[批量提交](../api/batch-tasks.md)/查询/分页/待执行取消、队列创建/查询、[自动 Worker](worker-runtime.md)、[Worker 底层协议 SDK](worker.md) 和 [执行历史查询](../api/execution-history.md)。[人工核查与重试](../api/task-recovery.md) 已提供 ReviewTask、RetryTask 与任务操作审计查询。[安全重试](../api/retries.md) 已提供有限策略、WorkerFailure.Retryable、历史查询及完整例子。[计划调度](../api/schedules.md) 已支持创建、查询、版本发布、暂停/恢复、触发历史与完整示例。[订阅管理](../api/subscriptions.md) 已支持创建、查询、暂停恢复、交付历史与人工重试；[事件消费 SDK](event-consumer.md) 已支持连接、自动心跳、重连与确认。[流程定义发布](../api/workflow-definitions.md)、[实例/控制/信号/操作审计](../api/workflows.md)及[六类人工恢复](../api/workflow-recovery.md)已提供独立SDK；历史、查询、轮询与恢复均有[可运行示例](../../examples/README.md)。
生产接入推荐按[生产接入闭环](production-integration.md)执行：业务 Outbox 持久化幂等身份，SDK 负责 HTTP 受理和查询，Event WebSocket 负责可靠通知，业务 Inbox 负责去重和确认；网络结果不明时始终保留原键核对。
@@ -29,11 +29,11 @@ go run ./cmd/orbit
另开终端，从仓库根目录执行：
```sh
cd sdk/go
ORBIT_URL=http://127.0.0.1:8080 go run ./examples/health
cd examples
ORBIT_URL=http://127.0.0.1:8080 go run ./health
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/development.credentials.json \
go run ./examples/tasks
ORBIT_CREDENTIALS_FILE=../.local/development.credentials.json \
go run ./tasks
```
预期输出，task 为每次运行生成的实际 ID：
@@ -46,8 +46,8 @@ task=<32位任务ID> duplicate=true listed=1 final_state=CANCELLED revision=2
重复运行示例会新建一个独立任务并取消它，listed 数量可能增加，最多显示当前页 10 条。数据和审计保留，不执行硬删除。任务受理示例不启动 Worker；真实文件转换见[CSV→JSON场景](../examples/file-conversion.md)。
- [健康示例源码](../../sdk/go/examples/health/main.go)：只读，无业务资源写入。
- [任务示例源码](../../sdk/go/examples/tasks/main.go)：提交两次同一身份、获取当前状态、列表、带版本取消，再核对直接来源。
- [健康示例源码](../../examples/health/main.go)：只读，无业务资源写入。
- [任务示例源码](../../examples/tasks/main.go)：提交两次同一身份、获取当前状态、列表、带版本取消，再核对直接来源。
- 任务示例也接受 ORBIT_TOKEN 和 ORBIT_QUEUE_ID，环境值优先于凭据文件。
- 示例发生错误会打印错误并非零退出；打印内容不包含原始 token。
- 初始凭据 30 天有效。初始化行为和错误核对方式见 [凭据文档](../api/authentication.md)。
@@ -148,10 +148,10 @@ Options.HTTPClient 可注入专用 HTTP 客户端。SDK 复制配置，不修改
## 5. 外部项目通过远端接入
业务项目需要 Go 1.27.1 或更高版本。在业务项目的 `go.mod` 所在目录安装首个接入版本：
业务项目需要 Go 1.27.1 或更高版本。在业务项目的 `go.mod` 所在目录安装当前接入版本：
```sh
go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.0
go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.1
```
代码中导入：
@@ -167,9 +167,9 @@ go mod tidy
go mod verify
```
SDK 位于仓库子目录，对应 Git 标签为 `sdk/go/v0.1.0`；`go get` 使用模块版本 `v0.1.0`。服务端对应仓库标签为 `v0.1.0`。业务项目固定版本并提交 `go.mod` 与 `go.sum`，无需本地源码、`replace` 或 Orbit 的 `go.work`。如果此前配置过本地替换，先执行 `go mod edit -dropreplace=git.yuntuo.hk/k2safe/orbit/sdk/go`。
SDK 位于仓库子目录，对应 Git 标签为 `sdk/go/v0.1.1`；`go get` 使用模块版本 `v0.1.1`。服务端对应仓库标签为 `v0.1.1`。业务项目固定版本并提交 `go.mod` 与 `go.sum`，无需本地源码、`replace` 或 Orbit 的 `go.work`。如果此前配置过本地替换，先执行 `go mod edit -dropreplace=git.yuntuo.hk/k2safe/orbit/sdk/go`。
这是开发与测试接入版本；生产部署仍按[交付清单](../release-checklist.md)完成目标环境验收。版本发布和校验规则见[发布说明](release.md)，空缓存远端取包结果见[验证报告](../reports/phase-7-sdk-remote-release.md)。
这是开发与测试接入版本；生产部署仍按[交付清单](../release-checklist.md)完成目标环境验收。版本发布和校验规则见[发布说明](release.md)，空缓存远端取包结果见[验证报告](../reports/v0.1.1-release.md)。
## 6. 查询执行历史与证据
@@ -193,13 +193,13 @@ for {
查询证据对应 `ListAttemptEvidence(ctx, taskID, attemptID, pageRequest)` 与 `GetAttemptEvidence(ctx, taskID, attemptID, evidenceID)`，列表相同方式使用 NextCursor。结果正文只在详情返回，列表适合按需展示。查询快照不授予执行权；证据的 outcome 是 Worker 原始声明，EVIDENCE_ONLY 不能当作任务成功。当前权威任务结果用 GetTask 核对。
完整 [执行历史示例](../../sdk/go/examples/history/main.go) 会创建一条模拟任务，提交固定成功结果，再模拟矛盾报告，并通过上述四个查询核对历史。先按 [Worker 初始化步骤](worker.md#1-可运行的文本规范化示例) 准备具有提交、读取及 Worker 权限的专用凭据，再从仓库根目录执行：
完整 [执行历史示例](../../examples/history/main.go) 会创建一条模拟任务，提交固定成功结果，再模拟矛盾报告，并通过上述四个查询核对历史。先按 [Worker 初始化步骤](worker.md#1-可运行的文本规范化示例) 准备具有提交、读取及 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/history
ORBIT_CREDENTIALS_FILE=../.local/worker.credentials.json \
go run ./history
```
预期输出：
@@ -216,7 +216,7 @@ P2 已提供底层协议、[自动 Worker 运行器及示例](worker-runtime.md)
## 订阅管理示例
[完整运行方法](../examples/subscriptions.md) 使用显式 --event-access 凭据，执行创建/同键核对/暂停/恢复/查询，再暂停本次订阅并保留审计。源码见 [examples/subscriptions](../../sdk/go/examples/subscriptions/main.go)。WSS 连接 SDK 与自动消费器见 [消费手册](event-consumer.md)，可运行 [协议示例](../examples/event-protocol.md) 验证跨连接 ACK；[持久化 Inbox 示例](../examples/result-inbox.md) 已独立交付，核心SDK不新增数据库驱动。
[完整运行方法](../examples/subscriptions.md) 使用显式 --event-access 凭据，执行创建/同键核对/暂停/恢复/查询，再暂停本次订阅并保留审计。源码见 [examples/subscriptions](../../examples/subscriptions/main.go)。WSS 连接 SDK 与自动消费器见 [消费手册](event-consumer.md)，可运行 [协议示例](../examples/event-protocol.md) 验证跨连接 ACK；[持久化 Inbox 示例](../examples/result-inbox.md) 已独立交付，核心SDK不新增数据库驱动。
## 流程定义发布