docs: consolidate runnable examples and publish v0.1.1 guides
This commit is contained in:
@@ -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不新增数据库驱动。
|
||||
|
||||
## 流程定义发布
|
||||
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# SDK 与协议兼容矩阵
|
||||
|
||||
当前发布线是 HTTP `/v1`、Worker WebSocket `pulse.worker.v1`、结果事件 WebSocket `orbit.events.v1`、Worker/事件帧 `protocol_version=1`、流程定义 `schema_version=1`，数据库要求 MySQL 8.4+ 与 Orbit schema v28。协议门禁由 `make protocol-check` 执行，检查服务端常量、SDK 常量、路由和机器可读 schema 是否一致。
|
||||
当前发布线是 HTTP `/v1`、Worker WebSocket `pulse.worker.v1`、结果事件 WebSocket `orbit.events.v1`、Worker/事件帧 `protocol_version=1`、流程定义 `schema_version=1`，数据库要求 MySQL 8.4+ 与 Orbit schema v31。协议门禁由 `make protocol-check` 执行，检查服务端常量、SDK 常量、路由和机器可读 schema 是否一致。
|
||||
|
||||
| SDK / 客户端 | 服务端 | 当前证据 | 结论 |
|
||||
| --- | --- | --- | --- |
|
||||
| 当前仓库 SDK | 当前仓库服务端 | `scripts/test-protocol-compatibility.sh`、SDK 单元/竞态测试、HTTP/WSS 集成测试 | 已验证 |
|
||||
| 历史提交 `a50d5fa` SDK | 当前服务端 | `make mysql-compatibility`，真实 MySQL/HTTP 任务 API 双向演练 | 任务 API smoke 已验证；不是正式标签或全协议结论 |
|
||||
| 当前 SDK | 历史提交 `a50d5fa` 服务端 | `make mysql-compatibility`，真实 MySQL/HTTP 任务 API 双向演练 | 任务 API smoke 已验证；不是正式标签或全协议结论 |
|
||||
| 上一个正式 SDK 标签 | 当前服务端 | 仓库尚未发布正式 SDK 标签 | 未验证，不得宣称兼容 |
|
||||
| 当前 SDK | 上一个正式服务端标签 | 仓库尚未发布正式服务端标签 | 未验证，不得宣称兼容 |
|
||||
| 上一个正式 SDK 标签 | 当前服务端 | 已发布 `sdk/go/v0.1.0`；完整跨版本协议矩阵尚未验收 | 未验证，不得宣称兼容 |
|
||||
| 当前 SDK | 上一个正式服务端标签 | 已发布 `v0.1.0`；完整跨版本协议矩阵尚未验收 | 未验证，不得宣称兼容 |
|
||||
| 非 Go HTTP 客户端 | 当前服务端 | `/v1` 接口手册、严格输入和错误码回归 | 按接口手册逐项验证 |
|
||||
|
||||
## 兼容规则
|
||||
|
||||
@@ -5,10 +5,10 @@
|
||||
业务写库与提交 Orbit 是两次独立操作。Outbox 将业务变更和待发请求放在同一个业务数据库事务中，再通过后台发送器提交任务。提交响应丢失时复用原操作身份，避免业务记录已保存而任务丢失。
|
||||
|
||||
```sh
|
||||
go get git.yuntuo.hk/k2safe/orbit/adapters/outbox/mysql@codex/orbit-foundation
|
||||
go get git.yuntuo.hk/k2safe/orbit/adapters/outbox/mysql@v0.1.1
|
||||
```
|
||||
|
||||
Go 会将分支解析为固定版本写入 go.mod。上线应固定已验证的版本，不在每次部署时追踪分支。本包要求 Go 1.27.1，使用 SDK v0.1.0 和 MySQL 8.4 验证；不向核心 SDK 加入 SQL/ORM 依赖，也不依赖 Orbit 服务端模型。其他数据库和 ORM 专用适配尚未提供。
|
||||
对应 Git 标签为 `adapters/outbox/mysql/v0.1.1`；业务项目固定模块版本 `v0.1.1`，无需本地 `replace`。本包要求 Go 1.27.1，使用 SDK v0.1.0 和 MySQL 8.4 验证；不向核心 SDK 加入 SQL/ORM 依赖，也不依赖 Orbit 服务端模型。其他数据库和 ORM 专用适配尚未提供。
|
||||
|
||||
```go
|
||||
import (
|
||||
|
||||
@@ -20,26 +20,28 @@ sh scripts/test-sdk-isolation.sh
|
||||
成功输出示例：
|
||||
|
||||
```json
|
||||
{"sdk_module":"git.yuntuo.hk/k2safe/orbit/sdk/go","independent":true,"package_count":30,"forbidden_dependencies":0}
|
||||
{"sdk_module":"git.yuntuo.hk/k2safe/orbit/sdk/go","independent":true,"package_count":5,"forbidden_dependencies":0}
|
||||
```
|
||||
|
||||
`package_count` 随示例增加而变化，不能作为兼容性版本号。门禁只证明源码在当前 Go 工具链下保持独立和可构建，不代表已经发布到远端模块代理，也不替代旧 SDK/新服务端和新 SDK/旧服务端的协议兼容矩阵。
|
||||
示例已移到根目录独立 module；`package_count` 随 SDK 包增加而变化，不能作为兼容性版本号。门禁只证明源码在当前 Go 工具链下保持独立和可构建，不代表已经发布到远端模块代理，也不替代旧 SDK/新服务端和新 SDK/旧服务端的协议兼容矩阵。
|
||||
|
||||
协议版本、WebSocket 子协议、流程 schema 和数据库版本见[兼容矩阵](compatibility.md)。发布候选还必须执行仓库根目录的 `make protocol-check`；它检查当前服务端、SDK 和机器可读 schema 是否仍在同一协议线，不把历史版本组合标记为已验证。
|
||||
|
||||
## 接入方式
|
||||
|
||||
首个接入版本为 `v0.1.0`，需要 Go 1.27.1 或更高版本。接入方应固定 SDK 版本，升级前先执行自己的接口和业务幂等回归：
|
||||
当前接入版本为 `v0.1.1`，需要 Go 1.27.1 或更高版本。接入方应固定 SDK 版本，升级前先执行自己的接口和业务幂等回归：
|
||||
|
||||
```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
|
||||
# 在业务代码导入 SDK 并添加调用后：
|
||||
go mod tidy
|
||||
go mod verify
|
||||
```
|
||||
|
||||
仓库主分支为 `main`。服务端标签 `v0.1.0` 和独立 SDK 标签 `sdk/go/v0.1.0` 指向同一发布提交；Go 子模块标签必须包含 `sdk/go/` 前缀，业务端的模块版本不带此前缀。已发布标签保持不可变，修复使用新的补丁版本。`v0.1.0` 用于开发与测试接入，正式生产仍需完成[交付核对清单](../release-checklist.md)。
|
||||
仓库主分支为 `main`。服务端标签 `v0.1.1` 和独立 SDK 标签 `sdk/go/v0.1.1` 指向同一发布提交；Go 子模块标签必须包含 `sdk/go/` 前缀，业务端的模块版本不带此前缀。已发布标签保持不可变，修复使用新的补丁版本。版本发布不替代目标环境验收，正式生产仍需完成[交付核对清单](../release-checklist.md)。
|
||||
|
||||
`v0.1.0` 已在仓库外的新业务 module、空模块缓存和 `GOWORK=off` 下通过公开远端下载、`go mod tidy`、编译、SDK HTTP smoke 和 `go mod verify`，解析版本精确为 `v0.1.0` 且不存在 `Replace`。发布提交、校验和与网络条件见[远端验证报告](../reports/phase-7-sdk-remote-release.md)。后续发布继续重复这一步，并按[兼容矩阵](compatibility.md)验证旧/新组合。
|
||||
|
||||
本地联调可以临时添加 `replace`，但不能提交到业务项目的发布分支。SDK 不负责 TLS 终止、凭据托管、对象存储或外部副作用核查；这些边界仍由平台接口手册和接入方运行手册定义。
|
||||
|
||||
Outbox 独立模块使用 `adapters/outbox/mysql/v0.1.1` 标签，安装与版本边界见[适配包手册](outbox-mysql.md)。本次目录整理、发布与远端取包验证见[v0.1.1 记录](../reports/v0.1.1-release.md)。
|
||||
|
||||
@@ -2,17 +2,17 @@
|
||||
|
||||
更新：2026-09-17。自动 Worker 已实现，并通过真实 MySQL、实际服务命令、WSS 断线/ACK 丢失/持续断网及 [进程强杀恢复回归](../reports/phase-2.md)。[尝试与证据查询](../api/execution-history.md) 可核对结果，协议形状见 [Schema](../api/worker-schema.md)。
|
||||
|
||||
源码：[运行器](../../sdk/go/worker_runtime.go)、[配置与中文注释](../../sdk/go/worker_runtime_types.go)、[完整示例](../../sdk/go/examples/worker/main.go)。特殊传输集成可以使用 [底层协议 SDK](worker.md)，普通消费直接使用本页的 Worker。
|
||||
源码：[运行器](../../sdk/go/worker_runtime.go)、[配置与中文注释](../../sdk/go/worker_runtime_types.go)、[完整示例](../../examples/worker/main.go)。特殊传输集成可以使用 [底层协议 SDK](worker.md)，普通消费直接使用本页的 Worker。
|
||||
|
||||
## 1. 运行完整示例
|
||||
|
||||
按 [底层 SDK 的初始化步骤](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/worker
|
||||
ORBIT_CREDENTIALS_FILE=../.local/worker.credentials.json \
|
||||
go run ./worker
|
||||
```
|
||||
|
||||
示例提交三条文本任务，以容量 2 启动自动 Worker，真实执行文本规范化，查询结果后取消 Run context 并等待排空。预期输出：
|
||||
|
||||
@@ -14,10 +14,10 @@ chmod 700 .local
|
||||
go run ./cmd/orbit-admin bootstrap \
|
||||
--application worker-example --namespace default --environment development \
|
||||
--queue normalization --worker-access --output .local/worker.credentials.json
|
||||
cd sdk/go
|
||||
cd examples
|
||||
ORBIT_URL=http://127.0.0.1:8080 \
|
||||
ORBIT_CREDENTIALS_FILE=../../.local/worker.credentials.json \
|
||||
go run ./examples/worker-protocol
|
||||
ORBIT_CREDENTIALS_FILE=../.local/worker.credentials.json \
|
||||
go run ./worker-protocol
|
||||
```
|
||||
|
||||
预期输出：
|
||||
@@ -26,7 +26,7 @@ ORBIT_URL=http://127.0.0.1:8080 \
|
||||
task=<32位任务ID> final_state=SUCCEEDED attempts=1 result={"text":"HELLO ORBIT"}
|
||||
```
|
||||
|
||||
[完整源码](../../sdk/go/examples/worker-protocol/main.go) 实际提交 `{"text":" Hello Orbit "}`，领取并取得开始授权，执行去首尾空格/转大写，报告结果、查询当前状态并排空。没有生成文件或调用外部服务。每次运行创建独立任务与临时处理器名，避免消费前次示例遗留任务；历史和审计保留，不硬删除。
|
||||
[完整源码](../../examples/worker-protocol/main.go) 实际提交 `{"text":" Hello Orbit "}`，领取并取得开始授权，执行去首尾空格/转大写，报告结果、查询当前状态并排空。没有生成文件或调用外部服务。每次运行创建独立任务与临时处理器名，避免消费前次示例遗留任务；历史和审计保留，不硬删除。
|
||||
|
||||
安全重试可通过 `WorkerFinish.Retryable=true` 声明明确失败允许再试，仅适用于 WorkerFailed；省略为 false。新尝试由服务端决定，详见 [安全重试](../api/retries.md)。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user