z-docs/docs/tutorial-basics/golang-connection.md

---
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 请参考客户端源码文档
:::