73 lines
2.7 KiB
Markdown
73 lines
2.7 KiB
Markdown
# Go SDK 接入说明
|
||
|
||
当前已实现客户端创建、存活与就绪查询。任务提交、Worker 和流程构建接口按开发计划逐阶段实现。
|
||
|
||
SDK module：`git.yuntuo.hk/k2safe/orbit/sdk/go`。服务端与 SDK 在同一 Git 仓库，使用独立 `go.mod`；SDK 当前仅依赖 Go 标准库。
|
||
|
||
## 1. 本地运行当前示例
|
||
|
||
前置条件：Go 1.27.1、MySQL 8.4+，先按项目根目录 README 迁移数据库并启动服务。
|
||
|
||
在仓库根目录执行：
|
||
|
||
```sh
|
||
cd sdk/go
|
||
ORBIT_URL=http://127.0.0.1:8080 go run ./examples/health
|
||
```
|
||
|
||
期望输出：
|
||
|
||
```text
|
||
liveness=alive readiness=ready scope=database_and_schema
|
||
```
|
||
|
||
[完整示例源码](../../sdk/go/examples/health/main.go)。示例 context 最多等待 5 秒；数据库或迁移未就绪时返回错误并以非零状态退出。
|
||
|
||
## 2. 当前真实调用方式
|
||
|
||
```go
|
||
client, err := orbit.NewClient("http://127.0.0.1:8080", orbit.Options{})
|
||
if err != nil {
|
||
return err
|
||
}
|
||
|
||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||
defer cancel()
|
||
|
||
health, err := client.Readiness(ctx)
|
||
if err != nil {
|
||
var responseErr *orbit.HTTPError
|
||
if errors.As(err, &responseErr) {
|
||
// responseErr.StatusCode 是实际 HTTP 状态，例如 503。
|
||
}
|
||
return err
|
||
}
|
||
fmt.Println(health.Status, health.Scope)
|
||
```
|
||
|
||
片段需在调用函数中使用并导入标准库包和 `orbit`；完整可运行程序见上方源码。
|
||
|
||
`Options.HTTPClient` 可注入专用 HTTP 客户端。SDK 复制其配置，不修改调用方客户端；禁止自动跟随重定向，限制健康响应大小，不自动重试请求，不将服务端响应正文放进错误。
|
||
|
||
## 3. 外部项目的本地接入
|
||
|
||
仓库尚未发布 SDK 版本。开发期间可使用独立工作区或本地 replace，例如在接入项目中执行：
|
||
|
||
```sh
|
||
go mod edit -require=git.yuntuo.hk/k2safe/orbit/sdk/go@v0.0.0
|
||
go mod edit -replace=git.yuntuo.hk/k2safe/orbit/sdk/go=/absolute/path/to/orbit/sdk/go
|
||
go mod tidy
|
||
```
|
||
|
||
示例路径需替换为本机实际目录。不要将本机绝对路径 replace 提交为发布依赖。后续发布 SDK 时使用独立 module 标签与兼容说明，在真实仓库取包路径验证后给出 `go get` 命令；当前不提供不存在的发行版本。
|
||
|
||
## 4. 后续 SDK 交付
|
||
|
||
- P1：凭据配置、幂等提交、查询与待执行取消。
|
||
- P2：处理器注册、Worker 容量、WSS、续租与结果确认、优雅退出。
|
||
- P3：计划管理、可靠结果订阅与队列控制。
|
||
- P4：流程定义、发布、启动、信号与查询。
|
||
- P5：有界查询、暂停继续和人工恢复入口。
|
||
|
||
每阶段同步更新可运行场景、错误处理与兼容测试。业务幂等、外部结果核查与 Outbox 接入责任会与真实代码示例一起说明。
|