zhub-go-client/README.md

ZHub Go Client

一个独立的 ZHub 客户端组件，支持消息发布订阅、RPC 调用、分布式锁等功能。

功能特性

• ✅ 消息发布订阅 (Pub/Sub)
• ✅ RPC 调用支持
• ✅ 分布式锁机制
• ✅ 定时器支持
• ✅ 自动重连
• ✅ 灵活的配置管理
• ✅ 环境变量支持

安装

从私有仓库安装

# 设置私有模块
go env -w GOPRIVATE=gitea.1216.top/lxy/*

# 安装包
go get gitea.1216.top/lxy/zhub-go-client

配置 Gitea 私有仓库访问

# 方法1: 使用 SSH 密钥（推荐）
git config --global url."git@gitea.1216.top:".insteadOf "https://gitea.1216.top/"

# 方法2: 使用用户名密码或 Token
git config --global url."https://用户名:密码@gitea.1216.top/".insteadOf "https://gitea.1216.top/"

# 方法3: 使用 .netrc 文件
# 创建 ~/.netrc 文件并添加认证信息

快速开始

1. 配置文件初始化

package main

import (
    "log"
    zhub "gitea.1216.top/lxy/zhub-go-client"
)

func main() {
    // 使用项目配置文件初始化
    err := zhub.InitWithProjectConfig("app.yml")
    if err != nil {
        log.Fatal("Failed to initialize zhub:", err)
    }

    // 发布消息
    zhub.Publish("test-topic", "Hello World!")
    
    // 订阅消息
    zhub.Subscribe("test-topic", func(message string) {
        log.Printf("Received: %s", message)
    })
}

2. 配置文件格式

# app.yml
zhub:
  appname: "my-app"
  addr: "127.0.0.1:1216"
  groupid: "my-group"
  auth: "my-token"

# 其他项目配置...
web:
  addr: "0.0.0.0:8080"

3. 多种初始化方式

// 方式1: 指定配置文件路径
zhub.InitWithProjectConfig("config/app.yml")

// 方式2: 自动发现配置文件
zhub.InitFromCurrentDir()

// 方式3: 使用环境变量
zhub.InitFromEnv() // 需要设置 ZHUB_CONFIG_PATH

// 方式4: 自定义配置选项
opts := &zhub.ConfigOptions{
    ConfigPath: "./config/my-app.yml",
    ConfigKey:  "zhub",
    EnvPrefix:  "ZHUB",
}
zhub.InitWithOptions(opts)

API 使用

消息发布订阅

// 发布消息
zhub.Publish("topic", "message")

// 广播消息
zhub.Broadcast("topic", "message")

// 延迟消息
zhub.Delay("topic", "message", 30) // 30秒后发送

// 订阅消息
zhub.Subscribe("topic", func(message string) {
    // 处理消息
})

// 取消订阅
zhub.Unsubscribe("topic")

RPC 调用

// RPC 客户端
zhub.CallRpc("rpc-service", map[string]interface{}{
    "action": "getUser",
    "id":     123,
}, func(result zhub.RpcResult) {
    if result.Retcode == 0 {
        log.Printf("Success: %v", result.Result)
    } else {
        log.Printf("Error: %s", result.Retinfo)
    }
})

// RPC 服务端
zhub.RpcSubscribe("rpc-service", func(rpc zhub.Rpc) zhub.RpcResult {
    // 处理 RPC 请求
    return rpc.Render(map[string]interface{}{
        "user": map[string]interface{}{
            "id":   123,
            "name": "John",
        },
    })
})

分布式锁

// 获取锁
lock := zhub.AcquireLock("resource-key", 30) // 30秒超时

// 执行业务逻辑
log.Println("Doing critical work...")
time.Sleep(time.Second * 2)

// 释放锁
zhub.ReleaseLock(lock)

定时器

// 设置定时器
zhub.Timer("my-timer", func() {
    log.Println("Timer triggered!")
})

环境变量支持

# 设置配置文件路径
export ZHUB_CONFIG_PATH="/path/to/config.yml"

# 或者直接设置配置值
export ZHUB_APPNAME="my-app"
export ZHUB_ADDR="127.0.0.1:1216"
export ZHUB_GROUPID="my-group"
export ZHUB_AUTH="my-token"

错误处理

// 检查初始化错误
err := zhub.InitWithProjectConfig("config.yml")
if err != nil {
    log.Printf("初始化失败: %v", err)
    return
}

// 检查操作错误
err = zhub.Publish("topic", "message")
if err != nil {
    log.Printf("发布失败: %v", err)
}

测试

# 运行测试
go test ./...

# 运行示例
cd example
go run main.go

许可证

MIT License