Go SDK

Ice Go SDK，功能与 Java SDK 完全对等。原生支持 context.Context，集成 trace、超时控制。

安装

要求 Go 1.21+。

go get github.com/zjn-zjn/ice/sdks/go

快速开始

package main

import (
    "context"
    "fmt"
    "log"

    ice "github.com/zjn-zjn/ice/sdks/go"
    icecontext "github.com/zjn-zjn/ice/sdks/go/context"
)

// 定义叶子节点
type ScoreFlow struct {
    Score float64 `json:"score" ice:"name:分数阈值,desc:判断分数的阈值"`
    Key   string  `json:"key" ice:"name:取值键,desc:从roam中取值的键名"`
}

func (s *ScoreFlow) DoRoamFlow(ctx context.Context, roam *icecontext.Roam) bool {
    value := roam.GetFloat64(s.Key, 0)
    return value >= s.Score
}

func init() {
    ice.RegisterLeaf("com.example.ScoreFlow",
        &ice.LeafMeta{Name: "分数判断", Desc: "判断分数是否达标"},
        func() any { return &ScoreFlow{} })
}

func main() {
    client, err := ice.NewClient(1, "./ice-data")
    if err != nil {
        log.Fatal(err)
    }
    client.Start()
    defer client.Destroy()

    pack := ice.NewPack().SetIceId(1)
    pack.Roam.Put("score", 85.0)
    ctxList := ice.SyncProcess(context.Background(), pack)

    for _, iceCtx := range ctxList {
        fmt.Println("结果:", iceCtx.Pack.Roam.Data())
    }
}

叶子节点开发

注册

Go SDK 使用显式注册（非注解扫描）：

ice.RegisterLeaf(className string, meta *LeafMeta, factory func() any)
  • className：节点类名，与 Server 配置中的 confName 对应
  • meta：节点元数据（名称、描述、别名），可为 nil
  • factory：创建节点实例的工厂函数

9 种节点接口

所有接口的第一个参数都是 context.Context：

类型接口方法返回值说明
FlowDoRoamFlow(ctx, roam)bool条件判断（最常用）
DoPackFlow(ctx, pack)bool需要访问 Pack
DoFlow(ctx, iceCtx)bool需要完整 Context
ResultDoRoamResult(ctx, roam)bool业务操作（最常用）
DoPackResult(ctx, pack)bool需要访问 Pack
DoResult(ctx, iceCtx)bool需要完整 Context
NoneDoRoamNone(ctx, roam)—辅助操作（最常用）
DoPackNone(ctx, pack)—需要访问 Pack
DoNone(ctx, iceCtx)—需要完整 Context

注册时 SDK 自动检测实现了哪个接口，无需手动指定类型。

字段配置

使用 ice struct tag 添加字段描述：

type MyNode struct {
    Score float64 `json:"score" ice:"name:分数阈值,desc:判断分数的阈值"`
    Key   string  `json:"key" ice:"name:取值键"`

    // 不在配置界面显示
    Service *http.Client `json:"-"`          // json:"-" 不参与序列化
    Cache   map[string]any `json:"cache" ice:"-"` // ice:"-" 隐藏
}

别名（跨语言兼容）

ice.RegisterLeaf("com.example.ScoreFlow",
    &ice.LeafMeta{
        Alias: []string{"score_flow", "ScoreFlow"},
    },
    func() any { return &ScoreFlow{} })

别名允许 Go 节点响应 Java/Python 配置的类名。

执行规则

所有执行方法的第一个参数都是 context.Context：

ctx := context.Background()

// 按 iceId 执行
pack := ice.NewPack().SetIceId(1)
pack.Roam.Put("uid", 12345)
ctxList := ice.SyncProcess(ctx, pack)

// 按场景执行
pack := ice.NewPack().SetScene("recharge")
ctxList := ice.SyncProcess(ctx, pack)

// 异步执行
channels := ice.AsyncProcess(ctx, pack)
for _, ch := range channels {
    iceCtx := <-ch
    // 处理结果
}

便捷方法

roam := ice.ProcessSingleRoam(ctx, pack)
roams := ice.ProcessRoam(ctx, pack)
iceCtx := ice.ProcessSingleCtx(ctx, pack)
ctxList := ice.ProcessCtx(ctx, pack)

Context 传递

func handleRequest(w http.ResponseWriter, r *http.Request) {
    ctx := ice.WithTraceId(r.Context(), r.Header.Get("X-Trace-Id"))

    pack := ice.NewPack().SetScene("api")
    pack.Roam.Put("userId", getUserId(r))

    // ctx 会传递到所有叶子节点，日志自动带上 traceId
    ice.SyncProcess(ctx, pack)
}

Roam 操作

roam := ice.NewRoam()

// 基础操作
roam.Put("name", "Alice")
name := roam.GetString("name")
age := roam.GetInt("age", 0)          // 带默认值
score := roam.GetFloat64("score", 0.0)

// 多级 key
roam.PutMulti("user.profile.level", 5)
level := roam.GetMulti("user.profile.level")

// 引用语法
roam.GetUnion("@user.profile.level")  // 5

完整 API 见 Roam API 参考。

Client 配置

// 最简方式
client, _ := ice.NewClient(1, "./ice-data")

// 完整配置
client, _ := ice.NewClientWithOptions(
    1,                      // app ID
    "./ice-data",           // 存储路径
    -1,                     // 并行度（-1 使用默认）
    5*time.Second,          // 轮询间隔
    30*time.Second,         // 心跳间隔
    "",                     // 泳道（空字符串 = 主干）
)

// 带泳道
client, _ := ice.NewWithLane(1, "./ice-data", "feature-xxx")

生命周期

client.Start()
client.WaitStarted()
version := client.GetLoadedVersion()
client.Destroy()

日志配置

默认使用 slog。支持自定义：

type MyLogger struct{}

func (l *MyLogger) Debug(ctx context.Context, msg string, args ...any) { /* ... */ }
func (l *MyLogger) Info(ctx context.Context, msg string, args ...any)  { /* ... */ }
func (l *MyLogger) Warn(ctx context.Context, msg string, args ...any)  { /* ... */ }
func (l *MyLogger) Error(ctx context.Context, msg string, args ...any) { /* ... */ }

ice.SetLogger(&MyLogger{})

TraceId 会自动从 context 中提取并附加到日志。

下一步