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
})