go-redis库使用总结

1. 概述与特性

go-redis 是一个高性能、功能丰富的 Redis 客户端库，支持 Redis 的大部分核心特性（字符串、哈希、列表、集合、有序集合、事务、Lua 脚本、发布订阅、Pipeline、Cluster、Sentinel 等）。
提供了对 Redis 6/7 及以上版本的特性支持，包含专门的客户端下载与连接管理、上下文感知 API、以及对 Redis 模块/RESP3 的部分支持。
官方地址与文档：https://github.com/go-redis/redis

2. 安装与初始化

2.1 安装

使用 go.mod 管理依赖：

go get github.com/go-redis/redis/v8

Go 版本要求：1.18+（go-redis v8 基于 go mod，使用模块版本，推荐使用 go1.18+），这里使用的是最新版本go1.24。

2.2 初始化

package mainimport ("errors""fmt""github.com/go-redis/redis"
)var client *redis.Clientfunc initClient() (err error) {client = redis.NewClient(&redis.Options{Addr:     "localhost:6379",Password: "",DB:       1,PoolSize: 100,DialTimeout: 5 * time.Second,ReadTimeout: 3 * time.Second,WriteTimeout: 3 * time.Second,PoolSize: 10, // 连接池大小MinIdleConns: 2,})_, err = client.Ping().Result()if err != nil {return err}return nil
}func initClient2() (err error) {// 哨兵模式client = redis.NewFailoverClient(&redis.FailoverOptions{MasterName:    "mymaster",SentinelAddrs: []string{"localhost:6379"},})_, err = client.Ping().Result()if err != nil {return err}return nil
}func initClient3() (err error) {// 连接redis集群rds := redis.NewClusterClient(&redis.ClusterOptions{Addrs: []string{"7000", "7001", "7002", "7003", "7004", "7005"},})_, err = rds.Ping().Result()if err != nil {return err}return nil
}func main() {err := initClient()if err != nil {panic(err)}fmt.Println("redis connect success...")result, err := client.Get("1").Result()if err != nil {return}fmt.Println(result)
}}

3 基本使用模式

3.1 单实例客户端

语法糖：使用 rdb.Get、rdb.Set 等方法，返回的错误大多用 err != nil 判断。

func singleInstanceDemo() {
client := newClient()
defer client.Close()// 设置键值
if err := client.Set(ctx, "key", "value", 0).Err(); err != nil {
// handle error
}// 获取值
val, err := client.Get(ctx, "key").Result()
if err != nil {
// 处理错误（不存在等情况）
} else {
fmt.Println("value:", val)
}// 自增
client.Incr(ctx, "counter")
}

3.2 连接池与自动重连

go-redis 通过 Options 提供连接池设置：

1. PoolSize: 最大并发连接数
2. MinIdleConns: 最小空闲连接数量
3. MaxRetries: 全局重试次数
4. MinRetryBackoff / MaxRetryBackoff: 重试间隔
5. DialTimeout、ReadTimeout、WriteTimeout
6. 对于短连接场景也能高效工作，确保在应用生命周期内复用一个客户端实例。

4. 常用 Redis 数据结构操作

4.1 字符串（String）

Set、Get、Incr、Decr、MGet、MSet、GetSet、Append 等常用操作。

client.Set(ctx, "name", "GoLang", 0)
name, _ := client.Get(ctx, "name").Result
client.Incr(ctx, "age")
vals, _ := client.MGet(ctx, "name", "age").Result

4.2 哈希（Hash）

HSet、HGet、HGetAll、HExists、HDel、HMSet（在 v8+ 内置 HMSet 的行为变更，推荐使用 HSet）

client.HSet(ctx, "user:1000", "name", "Alice", "age", "30")
name, _ := client.HGet(ctx, "user:1000", "name").Result
all, _ := client.HGetAll(ctx, "user:1000").Result

4.3 列表（List）

LPUSH、RPUSH、LPOP、RPOP、LRANGE、LPOS

client.RPush(ctx, "queue", "task1", "task2")
item, _ := client.LPop(ctx, "queue").Result

4.4 集合（Set）

SADD、SMEMBERS、SISMEMBER、SPOP、SUNION

client.SAdd(ctx, "tags", "go", "redis")
members, _ := client.SMembers(ctx, "tags").Result

4.5 有序集合（ZSet）

ZADD、ZRANGE、ZREVRANGE、ZCARD、ZSCORE

client.ZAdd(ctx, "leaders", &redis.Z{Score: 100, Member: "alice"})
score, _ := client.ZScore(ctx, "leaders", "alice").Result

4.6 事务（Tx/TxPipeline）

事务模式有乐观/乐观锁风格，go-redis 提供 Tx、TxPipelined 等接口。

tx := client.TxPipeline()
tx.Set(ctx, "k1", "v1", 0)
tx.Incr(ctx, "counter")
_, _ := tx.Exec(ctx)

TxPipelined（带闭包的流水线事务）：

_, err := client.TxPipelined(ctx, func(pipe redis.Pipeliner) error {
pipe.Incr(ctx, "counter")
pipe.Set(ctx, "k1", "v1", 0)
return nil
})