vault backup: 2026-05-28 12:41:37
This commit is contained in:
@@ -0,0 +1,363 @@
|
||||
---
|
||||
tags: [Redis, Go, go-redis, 缓存, 后端]
|
||||
create time: 2026-05-28 10:55
|
||||
---
|
||||
|
||||
# Go 项目集成 Redis
|
||||
|
||||
## 概述
|
||||
|
||||
Go 生态中最主流的 Redis 客户端是 **go-redis**（`github.com/redis/go-redis/v9`），它支持 Redis 6.0+ 的全部命令、Cluster、Sentinel、Pub/Sub、Lua 脚本、Pipeline 等能力，社区活跃度和文档质量均优于早期的 redigo。本文以 go-redis 为主线，覆盖从初始化到生产实践的完整链路。
|
||||
|
||||
> [!QUESTION] go-redis vs redigo，怎么选？
|
||||
> | 维度 | go-redis | redigo |
|
||||
> |------|----------|--------|
|
||||
> | API 风格 | 命令式，返回值类型明确 | `Do()` 返回 `interface{}`，需手动断言 |
|
||||
> | 连接池 | 内置，参数可调 | 需手动封装 `Pool` |
|
||||
> | Cluster / Sentinel | 原生支持 | 需自行实现 |
|
||||
> | 维护状态 | 持续更新（v9） | 基本停更 |
|
||||
>
|
||||
> **结论**：新项目直接用 go-redis，除非有历史包袱。
|
||||
|
||||
## 一、客户端初始化与连接池
|
||||
|
||||
### 1.1 基础连接
|
||||
|
||||
```go
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"time"
|
||||
|
||||
"github.com/redis/go-redis/v9"
|
||||
)
|
||||
|
||||
// 单机模式
|
||||
rdb := redis.NewClient(&redis.Options{
|
||||
Addr: "localhost:6379",
|
||||
Password: os.Getenv("REDIS_PASSWORD"), // 生产环境从环境变量读取
|
||||
DB: 0,
|
||||
})
|
||||
```
|
||||
|
||||
### 1.2 连接池参数调优
|
||||
|
||||
go-redis 内置连接池，**不需要**再手动包一层。关键参数如下：
|
||||
|
||||
```go
|
||||
rdb := redis.NewClient(&redis.Options{
|
||||
Addr: "localhost:6379",
|
||||
PoolSize: 100, // 连接池最大连接数，默认 10*runtime.GOMAXPROCS
|
||||
MinIdleConns: 10, // 最小空闲连接，避免冷启动时频繁创建连接
|
||||
DialTimeout: 5 * time.Second, // 建立 TCP 连接的超时
|
||||
ReadTimeout: 3 * time.Second, // 读超时（含从池中获取连接的等待时间）
|
||||
WriteTimeout: 3 * time.Second, // 写超时
|
||||
})
|
||||
```
|
||||
|
||||
> [!TIP] PoolSize 和 MinIdleConns 的关系
|
||||
> - `PoolSize` 是硬上限——同时最多有这么多 TCP 连接到 Redis
|
||||
> - `MinIdleConns` 是保底——即使没有请求，也会保持这么多空闲连接
|
||||
> - 连接不够时，请求会**阻塞等待**（由 `ReadTimeout` / `WriteTimeout` 控制超时）
|
||||
> - go-redis v9 **没有** `MaxIdleConns` 和 `PoolTimeout`，空闲连接回收由内部 `connMaxIdleTime`（默认 5 分钟）管理
|
||||
|
||||
> [!TIP] 如何确定 PoolSize？
|
||||
> - **公式参考**：`PoolSize ≈ 预估并发数 × 单次 Redis 操作耗时(s)`（Little's Law：任意时刻同时占用连接的期望数）
|
||||
> - 例如并发 1000，每次操作 10ms → `1000 × 0.01 = 10`，再留 2~3 倍余量 → `PoolSize = 30`
|
||||
> - 监控 `redis.PoolStats()` 中的 `Hits`、`Misses`、`Timeouts` 来动态调整
|
||||
|
||||
### 1.3 Sentinel 模式
|
||||
|
||||
```go
|
||||
rdb := redis.NewFailoverClient(&redis.FailoverOptions{
|
||||
MasterName: "mymaster",
|
||||
SentinelAddrs: []string{"sentinel-1:26379", "sentinel-2:26379", "sentinel-3:26379"},
|
||||
Password: os.Getenv("REDIS_PASSWORD"),
|
||||
SentinelPassword: os.Getenv("SENTINEL_PASSWORD"),
|
||||
PoolSize: 100,
|
||||
MinIdleConns: 10,
|
||||
})
|
||||
```
|
||||
|
||||
### 1.4 Cluster 模式
|
||||
|
||||
```go
|
||||
rdb := redis.NewClusterClient(&redis.ClusterOptions{
|
||||
Addrs: []string{
|
||||
"node-1:6379", "node-2:6379", "node-3:6379",
|
||||
"node-4:6379", "node-5:6379", "node-6:6379",
|
||||
},
|
||||
Password: os.Getenv("REDIS_PASSWORD"),
|
||||
PoolSize: 100,
|
||||
MinIdleConns: 10,
|
||||
ReadOnly: true, // 从节点可读，分担读压力
|
||||
RouteByLatency: true, // 自动路由到延迟最低的节点
|
||||
})
|
||||
```
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Go Application"] --> B{"连接模式？"}
|
||||
B -->|"单机/开发"| C["redis.NewClient"]
|
||||
B -->|"主从+自动故障转移"| D["redis.NewFailoverClient"]
|
||||
B -->|"水平扩展/分片"| E["redis.NewClusterClient"]
|
||||
C --> F["redis.Options"]
|
||||
D --> G["redis.FailoverOptions"]
|
||||
E --> H["redis.ClusterOptions"]
|
||||
F --> I["调优连接池参数"]
|
||||
G --> I
|
||||
H --> I
|
||||
```
|
||||
|
||||
## 二、基础操作示例
|
||||
|
||||
go-redis 的命令命名与 Redis 命令一一对应，遵循 `rdb.Xxx(ctx, args...)` 的统一模式。
|
||||
|
||||
### 2.1 String
|
||||
|
||||
```go
|
||||
ctx := context.Background()
|
||||
|
||||
// SET key value EX 60
|
||||
err := rdb.Set(ctx, "user:1001:name", "张三", 60*time.Second).Err()
|
||||
|
||||
// GET key
|
||||
name, err := rdb.Get(ctx, "user:1001:name").Result()
|
||||
// 不存在时返回 redis.Nil 错误，而非空字符串
|
||||
if errors.Is(err, redis.Nil) {
|
||||
fmt.Println("key 不存在，回源 DB")
|
||||
}
|
||||
```
|
||||
|
||||
> [!WARNING] 区分 "key 不存在" 和 "其他错误"
|
||||
> go-redis 用 `redis.Nil` 表示 key 不存在，不要用 `err != nil` 一概而论——这会把"不存在"误判为"出错"。
|
||||
|
||||
### 2.2 Hash
|
||||
|
||||
```go
|
||||
// HSET user:1001 name "张三" age 25
|
||||
rdb.HSet(ctx, "user:1001", map[string]interface{}{
|
||||
"name": "张三",
|
||||
"age": 25,
|
||||
})
|
||||
|
||||
// HGETALL user:1001
|
||||
user, err := rdb.HGetAll(ctx, "user:1001").Result()
|
||||
```
|
||||
|
||||
### 2.3 Sorted Set
|
||||
|
||||
```go
|
||||
// ZADD leaderboard 95.5 "player:A"
|
||||
rdb.ZAdd(ctx, "leaderboard", redis.Z{
|
||||
Score: 95.5,
|
||||
Member: "player:A",
|
||||
})
|
||||
|
||||
// ZREVRANGE leaderboard 0 9 WITHSCORES（取 Top 10）
|
||||
top10, _ := rdb.ZRevRangeWithScores(ctx, "leaderboard", 0, 9).Result()
|
||||
```
|
||||
|
||||
## 三、Pipeline 批量操作
|
||||
|
||||
逐条发送命令，每条都要等一次 RTT。**Pipeline** 把多条命令打包成一次请求发送，响应也一次性读回，大幅减少网络往返。
|
||||
|
||||
```go
|
||||
// 逐条写入 1000 个 key：1000 次 RTT ❌
|
||||
// Pipeline 写入 1000 个 key：1 次 RTT ✅
|
||||
|
||||
pipe := rdb.Pipeline()
|
||||
for i := 0; i < 1000; i++ {
|
||||
pipe.Set(ctx, fmt.Sprintf("key:%d", i), i, 0)
|
||||
}
|
||||
cmds, err := pipe.Exec(ctx) // 一次发送，批量执行
|
||||
```
|
||||
|
||||
> [!QUESTION] Pipeline 和 Lua 脚本的区别？
|
||||
> - **Pipeline**：多条命令打包发送，但**不保证原子性**——其他客户端的命令可能穿插在中间
|
||||
> - **Lua 脚本**：在 Redis 服务端**原子执行**，适合需要"要么全成功，要么全失败"的场景（如分布式锁解锁）
|
||||
> - 如果只是"批量读/写"，Pipeline 性能更优；如果需要原子语义，用 Lua
|
||||
|
||||
## 四、分布式锁
|
||||
|
||||
### 4.1 加锁：SET NX EX
|
||||
|
||||
```go
|
||||
// SET lock:order:1001 $uuid NX EX 10
|
||||
ok, err := rdb.SetNX(ctx, "lock:order:1001", uuid, 10*time.Second).Result()
|
||||
if !ok {
|
||||
// 获取锁失败，其他协程/进程已持有
|
||||
return fmt.Errorf("锁已被持有")
|
||||
}
|
||||
defer unlock(ctx, rdb, "lock:order:1001", uuid) // 确保释放
|
||||
```
|
||||
|
||||
### 4.2 解锁：Lua 原子判断 + 删除
|
||||
|
||||
解锁必须**先判断锁是否是自己加的**，再删除——这两步必须原子执行，否则会误删别人的锁。
|
||||
|
||||
```go
|
||||
const unlockScript = `
|
||||
if redis.call("GET", KEYS[1]) == ARGV[1] then
|
||||
return redis.call("DEL", KEYS[1])
|
||||
else
|
||||
return 0
|
||||
end`
|
||||
|
||||
func unlock(ctx context.Context, rdb *redis.Client, key, uuid string) error {
|
||||
result, err := rdb.Eval(ctx, unlockScript, []string{key}, uuid).Int64()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if result == 0 {
|
||||
return fmt.Errorf("锁已过期或不属于当前持有者")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant G1 as "Goroutine A"
|
||||
participant R as "Redis"
|
||||
participant G2 as "Goroutine B"
|
||||
G1->>R: "SET lock:order NX EX 10 uuid-a"
|
||||
R-->>G1: "OK"
|
||||
G2->>R: "SET lock:order NX EX 10 uuid-b"
|
||||
R-->>G2: "nil, 失败"
|
||||
Note over G2: "等待或重试"
|
||||
G1->>R: "Eval Lua: GET==uuid-a ? DEL : 0"
|
||||
R-->>G1: "1, 解锁成功"
|
||||
G2->>R: "SET lock:order NX EX 10 uuid-b"
|
||||
R-->>G2: "OK"
|
||||
```
|
||||
|
||||
> [!WARNING] Redlock 争议
|
||||
> Martin Kleppmann 在 [How to do distributed locking](https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html) 中指出单节点 `SET NX EX` 在主从切换时可能不安全。如果你的业务对锁的安全性要求极高，建议：
|
||||
> 1. 使用 Redlock 多节点方案（go-redis 的 `redsync` 库）
|
||||
> 2. 或引入 fencing token + 下游服务校验
|
||||
|
||||
## 五、缓存模式实战：Cache-Aside + GORM
|
||||
|
||||
### 5.1 Cache-Aside 流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph "读流程"
|
||||
R1["查询缓存"] --> R2{"命中？"}
|
||||
R2 -->|"是"| R3["返回缓存数据"]
|
||||
R2 -->|"否"| R4["查询 DB"]
|
||||
R4 --> R5["回填缓存（SET EX）"]
|
||||
R5 --> R3
|
||||
end
|
||||
subgraph "写流程"
|
||||
W1["更新 DB"] --> W2["删除缓存 Key"]
|
||||
end
|
||||
```
|
||||
|
||||
### 5.2 实现示例
|
||||
|
||||
```go
|
||||
// 读：先缓存，miss 回源 DB
|
||||
func GetUser(ctx context.Context, rdb *redis.Client, db *gorm.DB, id uint) (*User, error) {
|
||||
key := fmt.Sprintf("user:%d", id)
|
||||
|
||||
// 1. 查缓存
|
||||
cached, err := rdb.Get(ctx, key).Bytes()
|
||||
if err == nil {
|
||||
var u User
|
||||
json.Unmarshal(cached, &u)
|
||||
return &u, nil
|
||||
}
|
||||
if !errors.Is(err, redis.Nil) {
|
||||
return nil, err // Redis 自身出错，降级到 DB
|
||||
}
|
||||
|
||||
// 2. 回源 DB
|
||||
var user User
|
||||
if err := db.First(&user, id).Error; err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// 3. 回填缓存（TTL 随机抖动防雪崩）
|
||||
ttl := 30*time.Minute + time.Duration(rand.Intn(300))*time.Second
|
||||
data, _ := json.Marshal(user)
|
||||
rdb.Set(ctx, key, data, ttl)
|
||||
|
||||
return &user, nil
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 与 GORM 钩子联动
|
||||
|
||||
在写操作后自动删缓存，通过 GORM 的 `AfterUpdate` / `AfterDelete` 钩子实现。先用类型安全的 context key 注入 Redis 客户端：
|
||||
|
||||
```go
|
||||
// context key 用自定义类型避免碰撞
|
||||
type ctxKey struct{}
|
||||
|
||||
func WithRedis(ctx context.Context, rdb *redis.Client) context.Context {
|
||||
return context.WithValue(ctx, ctxKey{}, rdb)
|
||||
}
|
||||
|
||||
func RedisFromCtx(ctx context.Context) *redis.Client {
|
||||
return ctx.Value(ctxKey{}).(*redis.Client)
|
||||
}
|
||||
|
||||
// 中间件注入：将 rdb 放入 Gin 的 context，GORM 通过 db.WithContext 传递
|
||||
func RedisMiddleware(rdb *redis.Client) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
c.Set("db", db.WithContext(WithRedis(c.Request.Context(), rdb)))
|
||||
c.Next()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// 钩子中安全地取出 rdb
|
||||
func (u *User) AfterUpdate(tx *gorm.DB) error {
|
||||
rdb := RedisFromCtx(tx.Statement.Context)
|
||||
key := fmt.Sprintf("user:%d", u.ID)
|
||||
return rdb.Del(tx.Statement.Context, key).Err()
|
||||
}
|
||||
```
|
||||
|
||||
> [!WARNING] 别用裸字符串做 context key
|
||||
> `context.Value("rdb")` 这种写法在多包协作时极易碰撞，且缺乏编译期类型检查。始终用**自定义 struct 类型**作为 key。
|
||||
|
||||
> [!TIP] 延迟双删
|
||||
> 在高并发写场景下，"先更新 DB，再删缓存"仍可能出现短暂不一致。**延迟双删**的做法是：第一次删缓存 → 更新 DB → sleep 500ms → 第二次删缓存。第二次删除清理了在 sleep 期间被其他请求回填的旧值。
|
||||
|
||||
## 六、Go 项目中 Redis 的典型架构位置
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Client["客户端请求"] --> Gin["Gin Router"]
|
||||
Gin --> Handler["Handler 层"]
|
||||
Handler --> Svc["Service 层"]
|
||||
Svc --> Cache{"缓存层"}
|
||||
Cache -->|"命中"| R["Redis"]
|
||||
Cache -->|"未命中"| Repo["Repository 层"]
|
||||
Repo --> DB["MySQL / PostgreSQL"]
|
||||
DB -->|"回填"| R
|
||||
subgraph "Session 共享"
|
||||
Gin -->|"gin-contrib/sessions"| R
|
||||
end
|
||||
```
|
||||
|
||||
Redis 在 Go 项目中通常承担三个角色：
|
||||
|
||||
1. **数据缓存**：Cache-Aside 模式，减轻数据库压力
|
||||
2. **Session 存储**：`gin-contrib/sessions/redis` 实现多实例共享会话
|
||||
3. **分布式协调**：分布式锁、限流器、排行榜等
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[hhs/Redis/README]] — Redis 知识索引入口
|
||||
- [[hhs/Redis/10-缓存架构模式]] — Cache-Aside / 穿透 / 击穿 / 雪崩完整方案
|
||||
- [[hhs/Redis/09-高级特性]] — Lua 脚本、Pipeline、Pub/Sub 详解
|
||||
- [[hhs/Redis/11-运维与性能调优]] — 连接池监控、慢查询、大 Key 治理
|
||||
- [[hhs/GORM/09-钩子函数]] — GORM 生命周期与缓存同步模式
|
||||
- [[hhs/EXAM/Week05]] — Docker Compose 中 Redis 容器管理与 Session 共享
|
||||
Reference in New Issue
Block a user