# ZHub Go Client

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

## 功能特性

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

## 安装

### 从私有仓库安装

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

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

### 配置 Gitea 私有仓库访问

```bash
# 方法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. 配置文件初始化

```go
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. 配置文件格式

```yaml
# 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. 多种初始化方式

```go
// 方式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 使用

### 消息发布订阅

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

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

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

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

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

### RPC 调用

```go
// 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",
        },
    })
})
```

### 分布式锁

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

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

// 释放锁
zhub.ReleaseLock(lock)
```

### 定时器

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

## 环境变量支持

```bash
# 设置配置文件路径
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"
```

## 错误处理

```go
// 检查初始化错误
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)
}
```

## 测试

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

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

## 许可证

MIT License