# go-redis

**Repository Path**: simon_git_code/go-redis

## Basic Information

- **Project Name**: go-redis
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gitee Redis Client

一个高性能、高可靠的Go语言Redis客户端库，提供完整的Redis功能支持。

## 特性

- ✅ **高性能连接池** - 智能连接管理，支持连接复用
- ✅ **熔断器机制** - 自动故障检测和恢复
- ✅ **重试机制** - 自动重试失败的操作
- ✅ **完整的数据结构支持** - String、Hash、List、Set、Sorted Set
- ✅ **管道操作** - 批量命令执行
- ✅ **事务支持** - 完整的ACID事务
- ✅ **分布式锁** - 基于Redis的分布式锁实现
- ✅ **连接健康检查** - 自动连接健康监控
- ✅ **超时控制** - 连接、读取、写入超时配置
- ✅ **TLS支持** - 安全的加密连接

## 安装

```bash
go get gitee.com/simon_git_code/go-redis
```

## 快速开始

### 基本使用

```go
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"gitee.com/simon_git_code/go-redis"
)

func main() {
	// 创建配置
	config := redis.DefaultConfig()
	config.Addr = "localhost:6379"
	config.Password = ""
	config.DB = 0

	// 创建客户端
	client, err := redis.NewClient(config)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	ctx := context.Background()

	// 测试连接
	err = client.Ping(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// String操作
	err = client.Set(ctx, "key", "value", 10*time.Minute)
	if err != nil {
		log.Fatal(err)
	}

	value, err := client.Get(ctx, "key")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Value:", value)
}
```

### 数据结构操作示例

#### String
```go
// 设置带过期时间的键值对
err := client.Set(ctx, "key", "value", 10*time.Minute)

// 获取值
value, err := client.Get(ctx, "key")

// 自增操作
count, err := client.Incr(ctx, "counter")
```

#### Hash
```go
// 设置哈希字段
hashData := map[string]interface{}{
	"name": "Alice",
	"age": 30,
}
count, err := client.HSet(ctx, "user:1", hashData)

// 获取所有字段
userData, err := client.HGetAll(ctx, "user:1")
```

#### List
```go
// 推入列表
_, err := client.RPush(ctx, "tasks", "task1", "task2")

// 获取列表范围
tasks, err := client.LRange(ctx, "tasks", 0, -1)
```

#### Set
```go
// 添加集合元素
_, err := client.SAdd(ctx, "tags", "golang", "redis")

// 获取所有元素
tags, err := client.SMembers(ctx, "tags")
```

#### Sorted Set
```go
// 添加有序集合元素
members := []redis.Z{
	{Score: 100, Member: "player1"},
	{Score: 200, Member: "player2"},
}
_, err := client.ZAdd(ctx, "leaderboard", members...)

// 获取带分数的元素
leaders, err := client.ZRangeWithScores(ctx, "leaderboard", 0, -1)
```

### 管道操作

```go
pipeline := client.Pipeline()

// 添加多个命令
pipeline.Do("SET", "key1", "value1")
pipeline.Do("SET", "key2", "value2")
getCmd := pipeline.Do("GET", "key1")

// 批量执行
err := pipeline.Exec(ctx)
if err != nil {
	log.Fatal(err)
}

// 获取结果
value, err := getCmd.String()
```

### 事务操作

```go
tx := client.Transaction()

// 添加事务命令
tx.Do("SET", "tx_key1", "tx_value1")
tx.Do("SET", "tx_key2", "tx_value2")
getCmd := tx.Do("GET", "tx_key1")

// 执行事务
results, err := tx.Exec(ctx)
if err != nil {
	log.Fatal(err)
}

// 获取结果
value, err := getCmd.String()
```

### 分布式锁

```go
// 创建锁
lock := client.NewLock("resource_lock", 30*time.Second)

// 获取锁
acquired, err := lock.Acquire(ctx)
if err != nil {
	log.Fatal(err)
}

if acquired {
	defer lock.Release(ctx)
	
	// 执行业务逻辑
	fmt.Println("Lock acquired, doing work...")
	time.Sleep(2 * time.Second)
} else {
	fmt.Println("Failed to acquire lock")
}
```

## EasyClient - 简化版客户端

为了进一步简化使用，我们提供了 `EasyClient`，它自动管理 `context.Background()`，无需每次手动创建：

### EasyClient 快速开始

```go
package main

import (
	"fmt"
	"log"
	"time"

	"gitee.com/simon_git_code/go-redis"
)

func main() {
	// 创建 EasyClient（无需手动创建 context）
	client, err := redis.NewEasyClient(nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	// 测试连接 - 不需要传 ctx
	err = client.Ping()
	if err != nil {
		log.Fatal(err)
	}

	// String 操作 - 代码更简洁
	err = client.Set("key", "value", 10*time.Minute)
	if err != nil {
		log.Fatal(err)
	}

	value, err := client.Get("key")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Value:", value)

	// Hash 操作
	hashData := map[string]interface{}{
		"name": "Alice",
		"age":  30,
	}
	_, err = client.HSet("user:1", hashData)
	if err != nil {
		log.Fatal(err)
	}

	userData, err := client.HGetAll("user:1")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("User data: %+v\n", userData)
}
```

### EasyClient vs Client 对比

**使用 Client（需要手动管理 context）：**
```go
ctx := context.Background()
err := client.Set(ctx, "key", "value", 10*time.Minute)
value, err := client.Get(ctx, "key")
```

**使用 EasyClient（自动管理 context）：**
```go
err := client.Set("key", "value", 10*time.Minute)
value, err := client.Get("key")
```

### 需要自定义 Context 时

如果需要使用自定义 context（如超时控制），可以通过以下方式：

```go
// 方式1：使用 WithContext 创建新实例
customClient := client.WithContext(context.WithTimeout(context.Background(), 5*time.Second))
customClient.Set("key", "value", 10*time.Minute)

// 方式2：直接访问原始 Client
ctx := context.WithTimeout(context.Background(), 5*time.Second)
client.Client.Set(ctx, "key", "value", 10*time.Minute)
```

### EasyClient 特性

- ✅ **简化代码**：无需每次手动创建 `context.Background()`
- ✅ **功能完整**：支持所有 Redis 操作
- ✅ **灵活切换**：需要时可切换到自定义 context
- ✅ **零性能损耗**：只是方法包装，无额外开销
- ✅ **向后兼容**：不影响现有 `Client` 的使用

## 配置选项

```go
config := &redis.Config{
	// 基本配置
	Addr:     "localhost:6379",
	Password: "",
	DB:       0,

	// 连接池配置
	PoolSize:           10,
	MinIdleConns:       2,
	PoolTimeout:        4 * time.Second,
	IdleTimeout:        5 * time.Minute,

	// 超时配置
	DialTimeout:        5 * time.Second,
	ReadTimeout:        3 * time.Second,
	WriteTimeout:       3 * time.Second,

	// 重试配置
	MaxRetries:         3,
	RetryOnTimeout:     false,

	// 熔断器配置
	CircuitBreakerEnabled:     true,
	CircuitBreakerFailureThreshold: 5,
	CircuitBreakerSuccessThreshold: 3,
	CircuitBreakerTimeout:     30 * time.Second,

	// TLS配置
	TLSConfig:          nil,
}
```

## 错误处理

库定义了以下错误类型：

- `ErrNil` - 键不存在
- `ErrClosed` - 客户端已关闭
- `ErrPoolTimeout` - 连接池超时
- `ErrCircuitOpen` - 熔断器已打开
- `ErrLockNotHeld` - 锁未被持有
- `ErrLockExpired` - 锁已过期

## 重试机制

本客户端内置了强大的重试机制，当Redis服务不可用时会自动重试：

### 默认重试配置
- **最大重试次数**: 3次
- **重试间隔**: 渐进式延迟 (100ms, 200ms, 300ms)
- **熔断器**: 5次失败后熔断，30秒后尝试恢复

### 自定义重试配置
```go
config := redis.DefaultConfig()
config.MaxRetries = 5                      // 增加重试次数
config.RetryMinInterval = 200 * time.Millisecond  // 调整重试间隔
config.RetryMaxInterval = 2 * time.Second
config.RetryOnTimeout = true               // 超时时也重试

// 熔断器配置
config.CircuitBreakerFailureThreshold = 10  // 失败阈值
config.CircuitBreakerSuccessThreshold = 5   // 成功阈值
config.CircuitBreakerTimeout = 60 * time.Second  // 熔断超时
```

### 重试特性
- ✅ **自动重试**: 连接失败时自动重试，无需手动处理
- ✅ **渐进式延迟**: 避免立即重试造成服务器压力
- ✅ **智能跳过**: 对某些错误（如上下文取消）不重试
- ✅ **熔断器保护**: 防止雪崩效应，快速失败
- ✅ **灵活配置**: 根据不同场景调整参数

详细文档请参考：[RETRY_MECHANISM.md](RETRY_MECHANISM.md)

## 性能优化建议

1. **连接池大小**：根据并发需求调整PoolSize
2. **超时设置**：根据网络状况调整超时时间
3. **熔断器配置**：根据业务容忍度调整阈值
4. **使用管道**：批量操作时使用管道提高性能
5. **合理使用锁**：避免长时间持有分布式锁

## 测试

运行测试：

```bash
go test -v ./...
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！