添加：ZHub 管理接口文档和客户端使用指南

2025-09-23 21:48:31 +08:00
parent 88011cf20b
commit 5af775e525
35 changed files with 4133 additions and 412 deletions
--- a/docs/tutorial-basics/golang-connection.md
+++ b/docs/tutorial-basics/golang-connection.md
@@ -0,0 +1,242 @@
+---
+sidebar_position: 3
+title: Golang 连接
+description: 在 Go 项目中使用 ZHub 客户端
+---
+
+# Golang 项目中使用
+
+> 在 Go 项目中使用 ZHub 客户端
+
+---
+
+## 安装依赖
+
+```bash
+go get github.com/your-org/zhub-client-go
+```
+
+:::info 说明
+Go 客户端的实际包名请以官方发布为准，此处仅为示例
+:::
+
+---
+
+## 基础连接
+
+```go
+package main
+
+import (
+    "log"
+    "github.com/your-org/zhub-client-go"
+)
+
+func main() {
+    // 创建 ZHub 客户端
+    client := zhub.NewClient("127.0.0.1:1216", "go-group", "go-app-001", "token-12345")
+    
+    // 连接服务
+    err := client.Connect()
+    if err != nil {
+        log.Fatal("连接失败:", err)
+    }
+    defer client.Close()
+    
+    log.Println("ZHub 连接成功")
+}
+```
+
+**参数说明**：
+- `127.0.0.1:1216`: 服务端地址
+- `go-group`: 消费者组名称
+- `go-app-001`: 应用实例ID（必须唯一）
+- `token-12345`: 认证令牌（开启权限验证时）
+
+---
+
+## 基础使用
+
+### 发布订阅
+
+```go
+// 订阅消息
+client.Subscribe("user-login", func(message string) {
+    log.Println("收到消息:", message)
+})
+
+// 发布消息
+err := client.Publish("user-login", "用户登录")
+if err != nil {
+    log.Println("发布失败:", err)
+}
+```
+
+### 广播消息
+
+```go
+// 广播消息给所有客户端
+err := client.Broadcast("topic-abc", "hello!")
+if err != nil {
+    log.Println("广播失败:", err)
+}
+```
+
+### RPC 调用
+
+```go
+// 服务端：提供 RPC 服务
+client.RpcSubscribe("user-get-info", func(request string) string {
+    return "用户信息: " + request
+})
+
+// 客户端：调用 RPC 服务
+result, err := client.Rpc("user-get-info", "user123")
+if err != nil {
+    log.Println("RPC 失败:", err)
+} else {
+    log.Println("RPC 结果:", result)
+}
+```
+
+### 延时消息
+
+```go
+// 延时5秒发送消息
+err := client.Delay("task-reminder", "任务提醒", 5000)
+if err != nil {
+    log.Println("延时消息失败:", err)
+}
+```
+
+---
+
+## 完整示例
+
+```go
+package main
+
+import (
+    "log"
+    "time"
+    "github.com/your-org/zhub-client-go"
+)
+
+func main() {
+    // 创建客户端
+    client := zhub.NewClient("127.0.0.1:1216", "go-demo", "go-demo-001", "token-12345")
+    
+    // 连接服务
+    err := client.Connect()
+    if err != nil {
+        log.Fatal("连接失败:", err)
+    }
+    defer client.Close()
+    
+    log.Println("ZHub 连接成功")
+    
+    // 订阅消息
+    client.Subscribe("user-login", func(message string) {
+        log.Println("收到用户登录消息:", message)
+    })
+    
+    // 发布消息
+    err = client.Publish("user-login", "用户ID: 12345")
+    if err != nil {
+        log.Println("发布失败:", err)
+    }
+    
+    // 广播消息
+    err = client.Broadcast("topic-abc", "hello!")
+    if err != nil {
+        log.Println("广播失败:", err)
+    }
+    
+    // 延时消息
+    err = client.Delay("task-reminder", "任务提醒", 5000)
+    if err != nil {
+        log.Println("延时消息失败:", err)
+    }
+    
+    // 提供 RPC 服务
+    client.RpcSubscribe("user-get-info", func(userId string) string {
+        return "用户信息: " + userId
+    })
+    
+    // 调用 RPC 服务
+    result, err := client.Rpc("user-get-info", "user123")
+    if err != nil {
+        log.Println("RPC 失败:", err)
+    } else {
+        log.Println("RPC 结果:", result)
+    }
+    
+    // 保持程序运行
+    time.Sleep(time.Minute)
+}
+```
+
+---
+
+## 注意事项
+
+### 1. AppID 唯一性
+
+:::warning 重要
+- **每个客户端必须使用不同的 appid**
+- RPC 通讯消息回复地址使用 appid 标识
+- 相同 appid 会导致 RPC 消息回复找不到目标客户端
+:::
+
+**推荐命名规则**：
+- `go-service-001`
+- `go-worker-002`
+- `go-gateway-001`
+
+### 2. 错误处理
+
+```go
+// 建议的错误处理方式
+if err := client.Publish("topic-abc", "message"); err != nil {
+    log.Printf("发布消息失败: %v", err)
+    // 根据业务需要决定是否重试
+}
+```
+
+### 3. 连接管理
+
+```go
+// 检查连接状态
+if !client.IsConnected() {
+    log.Println("客户端未连接")
+    return
+}
+
+// 重连机制
+for {
+    if !client.IsConnected() {
+        err := client.Connect()
+        if err != nil {
+            log.Printf("重连失败: %v", err)
+            time.Sleep(time.Second * 5)
+            continue
+        }
+        log.Println("重连成功")
+    }
+    time.Sleep(time.Second)
+}
+```
+
+---
+
+## 版本信息
+
+- **客户端版本**: 待发布
+- **支持 Go 版本**: 1.19+
+- **包管理**: go mod
+
+:::info 说明
+- Go 客户端提供基础的发布订阅、广播、RPC 功能
+- 连接参数与 Java 客户端保持一致
+- 详细 API 请参考客户端源码文档
+:::