绝尘
dcfb735a2d
新增 zhub 客户端完整实现，包括配置加载、TCP通信、消息发布/订阅、 RPC 调用、分布式锁等功能。支持从项目配置文件、环境变量等多种方式初始化客户端，并提供便捷的全局调用接口。- 添加 `.gitignore` 忽略 IDE 和临时文件 - 实现 `api.go` 提供全局便捷方法封装客户端调用 - 实现 `client.go` 核心客户端逻辑，包含网络通信、消息处理等 - 添加 `client_test.go` 单元测试和集成测试示例 - 实现 `config.go` 支持灵活的配置加载机制 - 添加示例配置文件 `example-config.yml` - 初始化 Go 模块依赖 `go.mod` 和 `go.sum` - 实现 `init.go` 提供多种初始化方式 - 添加 MIT 许可证文件 `LICENSE` - 新增使用示例 `example/main.go` 展示基本功能调用 - 实现 `manager.go` 管理默认客户端实例及初始化逻辑
222 lines
3.9 KiB
Markdown
222 lines
3.9 KiB
Markdown
# 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
|