三、Redis 分布式锁与缓存一致性

package lock

import (
    "context"
    "errors"
    "time"

    "github.com/google/uuid"
    redis "github.com/go-redis/redis/v9"
)

// ==================== 分布式锁结构体 ====================

// Client 是一个 Redis 分布式锁的客户端
type Client struct {
    client redis.Cmdable // Redis 客户端接口
}

// NewClient 创建分布式锁客户端
// client 可以是 *redis.Client（单节点）或 *redis.ClusterClient（集群）
// 使用接口类型 Cmdable 而不是具体类型，是为了方便测试时注入 mock
func NewClient(client redis.Cmdable) *Client {
    return &Client{
        client: client,
    }
}

// ==================== TryLock：尝试加锁 ====================

// TryLock 尝试获取一把锁
// 叫 TryLock 是因为它不能保证一定加锁成功——如果锁已被别人持有，就直接返回失败
//
// 参数：
//   ctx：上下文，用于控制超时
//   key：锁的名称，比如 "lock:order:123" 表示订单 123 的锁
//   expiration：锁的过期时间，防止持有者崩溃后锁永远不释放
//   返回值：val 是锁的唯一标识（UUID），用于后续释放锁时验证身份
func (c *Client) TryLock(ctx context.Context, key string, expiration time.Duration) (string, error) {
    // 生成一个唯一的 UUID 作为锁的值
    // 为什么用 UUID？后面锁释放时会详细解释
    val := uuid.New().String()

    // 使用 SET key value NX PX 命令加锁
    // NX：Only set the key if it does not already exist（不存在才设置）
    // 这就是"排他"的核心——如果 key 已存在（锁已被持有），SET 会失败
    ok, err := c.client.SetNX(ctx, key, val, expiration).Result()
    if err != nil {
        // 什么情况会返回 error？
        // 1. Redis 服务器出错了
        // 2. 网络超时了
        // 3. 网络断开了
        return "", err
    }

    if !ok {
        // ok 为 false 表示 SetNX 没有设置成功
        // 什么情况会返回 false？
        // key 已经存在了，也就是锁已经被别人持有了
        return "", ErrLockNotHold
    }

    // 加锁成功，返回 UUID 用于后续释放
    return val, nil
}

// ErrLockNotHold 表示锁已被其他人持有
var ErrLockNotHold = errors.New("lock: not hold the lock")

// ==================== 如果没有过期时间 ====================
//
// 假设不设置过期时间：
//
// 时间线：
//   t1: 实例1 调用 TryLock 获取锁成功
//   t2: 实例1 正在执行业务代码...
//   t3: 实例1 突然崩溃了！（OOM、panic、机器宕机）
//   t4: 锁永远存在于 Redis 中，没有人去释放它
//   t5: 实例2 想获取锁 → SetNX 失败 → 永远拿不到锁
//
// 结果：所有其他实例永远无法获取锁，业务完全卡死
//
// 所以必须设置过期时间：
//   即使持有者崩溃了，过一段时间后锁会自动过期释放
//   其他实例就能拿到锁了

// ==================== 为什么用 UUID 作为锁的值 ====================
//
// 假设不用 UUID，而是用固定值 "locked"：
//
// 时间线：
//   t1: 实例1 调用 TryLock，设置 key="mylock", value="locked", TTL=10s
//   t2: 实例1 正在执行业务代码...
//   t3: 10秒过去了，锁过期了（业务执行时间超过10秒）
//   t4: 实例2 调用 TryLock，设置 key="mylock", value="locked", TTL=10s → 成功
//   t5: 实例1 终于执行完了，准备释放锁
//   t6: 实例1 调用 DEL key → 把实例2的锁删除了！
//   t7: 实例3 调用 TryLock → 成功（因为实例2的锁被实例1误删了）
//   t8: 实例2 和 实例3 同时持有"锁"→ 互斥性被破坏！
//
// 用 UUID 的目的：
//   释放锁的时候，先检查 Redis 里的值是不是自己的 UUID
//   如果不是自己的，说明锁已经过期被别人拿走了，不能删除

// ==================== 为什么不能先 GET 再 DEL ====================
//
// 如果分两步做（非原子）：
//   t1: 实例1 调用 GET key → 返回 "uuid-1"（是自己的锁）
//   t2: ← 就在这个瞬间，锁过期了 → 实例2 SetNX 成功，value 变成 "uuid-2"
//   t3: 实例1 调用 DEL key → 删除了实例2的锁！
//
// 所以必须用 Lua 脚本，让"检查 + 删除"在一个原子操作中完成

// unlockScript 是释放锁的 Lua 脚本
// Lua 脚本在 Redis 中是原子执行的，不会被其他命令打断
const unlockScript = `
    -- redis.call('GET', KEYS[1])：获取 key 对应的值
    local val = redis.call('GET', KEYS[1])
    -- 检查值是否等于我们传入的 ARGV[1]（即我们的 UUID）
    if val == ARGV[1] then
        -- 值匹配，说明是自己的锁，可以删除
        return redis.call('DEL', KEYS[1])
    end
    -- 值不匹配，说明锁已经被别人拿走了，不能删除
    return 0
`

// Unlock 释放锁
// 参数 val 是 TryLock 时返回的 UUID
func (c *Client) Unlock(ctx context.Context, key, val string) error {
    // 使用 Eval 执行 Lua 脚本
    // KEYS[1] = key，ARGV[1] = val
    res, err := c.client.Eval(ctx, unlockScript, []string{key}, val).Result()
    if err != nil {
        // 可能是 Redis 服务器出错，或者网络超时
        return err
    }

    // res 是 Lua 脚本的返回值
    // 如果返回 0，说明锁不是我们的（可能已经过期被别人拿走了）
    if res.(int64) == 0 {
        return ErrLockNotHold
    }

    return nil
}

package lock

import (
    "context"
    "testing"
    "time"

    redis "github.com/go-redis/redis/v9"
    "github.com/golang/mock/gomock"
    "github.com/stretchr/testify/assert"

    "your_project/mocks" // mockgen 生成的 mock 包
)

// ==================== 单元测试（使用 gomock）====================
// 严格意义上来说，单元测试不能依赖于任何第三方组件
// 所以我们用 gomock 来 mock Redis 客户端
//
// 生成 mock 文件的命令：
// mockgen -package=mocks \
//         -destination=mocks/redis_cmdable.mock.go \
//         github.com/go-redis/redis/v9 Cmdable

func TestTryLock(t *testing.T) {
    ctrl := gomock.NewController(t)
    defer ctrl.Finish()

    mockClient := mocks.NewMockCmdable(ctrl)
    client := NewClient(mockClient)

    // ==================== 测试 1：加锁成功 ====================
    mockClient.EXPECT().
        SetNX(gomock.Any(), "lock_key", gomock.Any(), time.Second*10).
        Return(redis.NewBoolResult(true, nil)).
        Times(1)

    val, err := client.TryLock(context.Background(), "lock_key", time.Second*10)
    assert.NoError(t, err)
    assert.NotEmpty(t, val) // UUID 不为空

    // ==================== 测试 2：锁已被持有（加锁失败）====================
    mockClient.EXPECT().
        SetNX(gomock.Any(), "lock_key", gomock.Any(), time.Second*10).
        Return(redis.NewBoolResult(false, nil)).
        Times(1)

    _, err = client.TryLock(context.Background(), "lock_key", time.Second*10)
    assert.Equal(t, ErrLockNotHold, err)
}

func TestUnlock(t *testing.T) {
    ctrl := gomock.NewController(t)
    defer ctrl.Finish()

    mockClient := mocks.NewMockCmdable(ctrl)
    client := NewClient(mockClient)

    // ==================== 测试 1：释放自己的锁（成功）====================
    // 模拟 Lua 脚本返回 1（删除成功）
    mockClient.EXPECT().
        Eval(gomock.Any(), unlockScript, []string{"lock_key"}, "test-uuid").
        Return(redis.NewCmdResult(int64(1), nil)).
        Times(1)

    err := client.Unlock(context.Background(), "lock_key", "test-uuid")
    assert.NoError(t, err)

    // ==================== 测试 2：锁不是自己的（释放失败）====================
    // 模拟 Lua 脚本返回 0（值不匹配，没有删除）
    mockClient.EXPECT().
        Eval(gomock.Any(), unlockScript, []string{"lock_key"}, "wrong-uuid").
        Return(redis.NewCmdResult(int64(0), nil)).
        Times(1)

    err = client.Unlock(context.Background(), "lock_key", "wrong-uuid")
    assert.Equal(t, ErrLockNotHold, err)
}

// ==================== 集成测试（连接真实 Redis）====================
// 集成测试需要启动一个真实的 Redis 实例
//
// func TestLock_Integration(t *testing.T) {
//     client := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
//     lockClient := NewClient(client)
//     ctx := context.Background()
//
//     // 测试加锁 + 释放
//     val, err := lockClient.TryLock(ctx, "test_lock", time.Second*10)
//     assert.NoError(t, err)
//
//     err = lockClient.Unlock(ctx, "test_lock", val)
//     assert.NoError(t, err)
// }

// ==================== 过期时间的两难 ====================
//
// 设置短了：
//   业务还没完成，锁就过期了
//   → 别人拿到锁，互斥性被破坏
//
// 设置长了：
//   万一实例崩溃了，其他实例长时间拿不到锁
//   → 系统卡住很久
//
// 更严重的是：
//   不管你设置多长，极端情况下都会出现业务执行时间超过过期时间
//   不管你用 1 分钟还是 10 分钟，极端情况下都会超时
//
// 解决方案：续约（Refresh）
//   在锁还没过期的时候，再次延长过期时间
//   → 过期时间不必设置得很长，自动续约会帮我们设置好
//   → 如果实例崩溃了，则没有人再续约，过一段时间后自然过期

package lock

import (
    "context"
    "time"
)

// refreshScript 是续约的 Lua 脚本
// 逻辑：检查 key 的值是不是自己的，如果是，就延长过期时间
const refreshScript = `
    -- 获取 key 当前的值
    local val = redis.call('GET', KEYS[1])
    -- 检查值是否匹配
    if val == ARGV[1] then
        -- 值匹配，是自己的锁，延长过期时间
        -- EXPIRE 命令设置新的过期时间（秒）
        redis.call('PEXPIRE', KEYS[1], ARGV[2])
        return 1
    end
    -- 值不匹配，锁不是自己的（可能已经过期被别人拿走了）
    return 0
`

// Refresh 手动续约
// 参数：
//   ctx：上下文
//   key：锁的名称
//   val：锁的 UUID（TryLock 时返回的值）
//   expiration：新的过期时间
func (c *Client) Refresh(ctx context.Context, key, val string, expiration time.Duration) error {
    // 使用 Lua 脚本续约
    // ARGV[1] = val（UUID）
    // ARGV[2] = expiration 的毫秒数
    res, err := c.client.Eval(ctx, refreshScript,
        []string{key},
        val,
        expiration.Milliseconds(),
    ).Result()

    if err != nil {
        // 第一个 error：Redis 服务器出错，或者网络超时
        return err
    }

    if res.(int64) == 0 {
        // 第二个 error：锁要么不存在（已过期），要么存在但不是自己的
        return ErrLockNotHold
    }

    return nil
}

// ==================== 手动续约的使用 ====================
// 手动续约本身很简单，难的是使用时需要考虑的问题：
//
// 问题 1：间隔多久续约一次？
//   如果过期时间是 10 秒，可以每 7-8 秒续约一次
//   留 2-3 秒的缓冲时间，防止续约请求本身因网络延迟而超时
//
// 问题 2：如果 Refresh 返回了 error，怎么处理？
//   如果返回的是超时 error → 不知道有没有续约成功
//     → 可以立即再次尝试续约（大多数超时是偶发的）
//   如果返回的是其他 error → 可能是 Redis 宕机了
//     → 需要考虑业务是否应该中断
//
// 问题 3：如果确认续约失败了，怎么中断后续的业务？
//   这个问题基本无解！
//   因为业务代码一旦执行，你除非自己手动检测分布式锁状态
//   并且手动中断，不然是没有办法的

package main

import (
    "context"
    "fmt"
    "time"
)

func main() {
    client := NewClient(redisClient)
    ctx := context.Background()

    // 步骤 1：加锁
    val, err := client.TryLock(ctx, "mylock", 10*time.Second)
    if err != nil {
        panic(err)
    }
    // 确保最后释放锁
    defer func() {
        _ = client.Unlock(ctx, "mylock", val)
    }()

    // 步骤 2：启动续约 goroutine
    done := make(chan struct{})
    go func() {
        ticker := time.NewTicker(7 * time.Second) // 每 7 秒续约一次
        defer ticker.Stop()

        for {
            select {
            case <-ticker.C:
                // 续约
                if err := client.Refresh(ctx, "mylock", val, 10*time.Second); err != nil {
                    // 续约失败！
                    // 这里需要通知主 goroutine 中断业务
                    // 但实际上，主 goroutine 可能已经在执行不可中断的操作了
                    fmt.Println("续约失败:", err)
                    return
                }
                fmt.Println("续约成功")
            case <-done:
                // 业务完成，停止续约
                return
            }
        }
    }()

    // 步骤 3：执行业务逻辑
    fmt.Println("开始执行业务...")
    time.Sleep(30 * time.Second) // 模拟耗时业务（超过锁的 10 秒过期时间）
    fmt.Println("业务执行完成")

    // 步骤 4：通知续约 goroutine 停止
    close(done)
}

package lock

import (
    "context"
    "errors"
    "time"
)

// ==================== 自动续约 API ====================
// 自动续约需要面对的问题（和手动续约一样）：
//
// 1. 隔多久续约，续多长？
//    → 让用户指定多久续约一次（因为跟网络、Redis 稳定性有关）
//    → 每次续多长，直接使用原本的过期时间
//
// 2. 如何处理超时？
//    → 再次尝试续约（超时大多数是偶发的，可以立刻重试）
//    → 缺点：如果 Redis 真的崩溃了，会无限次尝试
//    → 超时时间让用户指定
//
// 3. 如何通知用户续约失败？
//    → 只处理超时引起的续约失败（自动重试）
//    → 其它 error 告诉用户遇到了无法处理的问题
//
// 4. 要不要设置续约次数上限？
//    → 不设置，如果用户有这种需求，应该自己手动续约

// AutoRefresh 自动续约
// 参数：
//   ctx：上下文，ctx.Done() 时停止续约
//   key：锁的名称
//   val：锁的 UUID
//   interval：续约间隔
//   expiration：每次续约设置的过期时间
//   f：续约失败时的回调函数（除了超时以外的 error）
func (c *Client) AutoRefresh(
    ctx context.Context,
    key, val string,
    interval time.Duration,
    expiration time.Duration,
    f func(error),
) {
    // 创建定时器，每隔 interval 时间续约一次
    ticker := time.NewTicker(interval)
    defer ticker.Stop()

    // 续约超时时间：设为 interval 的一半
    // 这样如果续约超时了，还有时间在下一次 tick 之前重试
    timeout := interval / 2

    for {
        select {
        case <-ctx.Done():
            // 上下文被取消，停止续约
            return

        case <-ticker.C:
            // 到了续约时间
            // 创建带超时的 context，防止续约请求卡住
            refreshCtx, cancel := context.WithTimeout(ctx, timeout)
            err := c.Refresh(refreshCtx, key, val, expiration)
            cancel()

            if err == nil {
                // 续约成功，等待下一次
                continue
            }

            if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
                // 超时了 → 立即重试
                // 超时意味着不知道有没有续约成功
                // 大多数超时是偶发的，可以立刻重试
                // 注意：如果 Redis 真的崩溃了，这里会无限次重试
                // 这是自动续约的一个缺点
                continue
            }

            if errors.Is(err, ErrLockNotHold) {
                // 锁不是自己的了（已过期被别人拿走）
                // 这种情况无法恢复，通知用户
                if f != nil {
                    f(err)
                }
                return
            }

            // 其他 error（Redis 宕机等）
            // 通知用户遇到了无法处理的 error
            if f != nil {
                f(err)
            }
            return
        }
    }
}

// ==================== 自动续约使用示例 ====================
//
// val, _ := client.TryLock(ctx, "mylock", 10*time.Second)
//
// // 启动自动续约，每 7 秒续约一次，每次设 10 秒过期
// go client.AutoRefresh(ctx, "mylock", val, 7*time.Second, 10*time.Second, func(err error) {
//     // 续约失败回调
//     // 实际上到这里已经无法做什么了
//     // 最多记录日志、发告警
//     log.Printf("续约失败: %v", err)
// })
//
// // 执行业务...
// // 业务完成后取消 ctx，自动续约 goroutine 会退出

// ==================== 加锁失败的原因 ====================
//
// 1. 超时了 → 不知道锁有没有拿到，需要重试确认
// 2. 锁被人持有着 → 等别人释放锁后重试
// 3. Redis 服务器故障 → 重试也没用，直接报错
//
// 超时重试的逻辑：
//   如果超时了，则直接再次加锁
//   然后检查 key 对应的值是不是我们刚才超时加锁请求的值
//   如果是 → 前一次加锁其实成功了，直接返回
//   如果不是 → 加锁失败（别人拿到了锁）

package lock

import (
    "context"
    "time"
)

// ==================== 重试策略接口 ====================
// 重试的接口设计成迭代器的形态
// 用户可以轻易通过扩展这个接口来实现自己的重试策略

// RetryStrategy 重试策略接口
type RetryStrategy interface {
    // Next 返回下一次重试需要等待的时间
    // 如果返回 false，表示不再重试
    Next() (time.Duration, bool)
}

// ==================== 策略 1：不重试 ====================
type NoRetry struct{}

func (NoRetry) Next() (time.Duration, bool) {
    return 0, false // 不等待，不重试
}

// ==================== 策略 2：等时间间隔重试 ====================
type EqualInterval struct {
    interval time.Duration // 每次重试的间隔
    maxRetry int           // 最大重试次数
    cnt      int           // 当前已重试次数
}

func NewEqualInterval(interval time.Duration, maxRetry int) *EqualInterval {
    return &EqualInterval{
        interval: interval,
        maxRetry: maxRetry,
    }
}

func (e *EqualInterval) Next() (time.Duration, bool) {
    if e.cnt >= e.maxRetry {
        return 0, false // 超过最大重试次数
    }
    e.cnt++
    return e.interval, true
}

// ==================== 策略 3：指数退避重试 ====================
// 每次重试间隔翻倍，避免频繁重试压垮 Redis
type ExponentialBackoff struct {
    initialInterval time.Duration // 初始间隔
    maxInterval     time.Duration // 最大间隔
    current         time.Duration // 当前间隔
    maxRetry        int           // 最大重试次数
    cnt             int           // 当前已重试次数
}

func NewExponentialBackoff(initial, max time.Duration, maxRetry int) *ExponentialBackoff {
    return &ExponentialBackoff{
        initialInterval: initial,
        maxInterval:     max,
        current:         initial,
        maxRetry:        maxRetry,
    }
}

func (e *ExponentialBackoff) Next() (time.Duration, bool) {
    if e.cnt >= e.maxRetry {
        return 0, false
    }
    e.cnt++
    wait := e.current
    // 下一次间隔翻倍，但不超过最大值
    e.current *= 2
    if e.current > e.maxInterval {
        e.current = e.maxInterval
    }
    return wait, true
}

// ==================== 重试接口的缺点 ====================
// 这种接口设计没有引入上下文的概念
// 用户在实现接口的时候没有办法根据上下文来判断真实情况
// 例如上一次调用的 error 来决定要不要重试

package lock

import (
    "context"
    "time"

    "github.com/google/uuid"
)

// Lock 带重试的加锁
// 和 TryLock 的区别：TryLock 只尝试一次，Lock 会按策略重试
func (c *Client) Lock(
    ctx context.Context,
    key string,
    expiration time.Duration,
    retry RetryStrategy,
) (string, error) {
    // 生成 UUID
    val := uuid.New().String()

    for {
        // 尝试加锁
        ok, err := c.client.SetNX(ctx, key, val, expiration).Result()
        if err != nil {
            // 加锁出错了（网络超时等）
            // 什么情况下应该重试？
            //   1. 超时了：不知道锁有没有拿到，可以重试
            //   2. 锁被人持有：等别人释放后重试
            // 什么情况下不应该重试？
            //   Redis 服务器故障：重试也没用
            // 这里简化处理，所有 error 都尝试重试
        } else if ok {
            // 加锁成功！
            return val, nil
        }

        // 加锁失败，检查是否应该重试
        wait, retry := retry.Next()
        if !retry {
            // 不再重试，返回错误
            if err != nil {
                return "", err
            }
            return "", ErrLockNotHold
        }

        // 等待一段时间后重试
        select {
        case <-ctx.Done():
            // 上下文被取消，停止重试
            return "", ctx.Err()
        case <-time.After(wait):
            // 等待结束，继续下一次重试
        }
    }
}

// ==================== 释放锁也可以重试 ====================
// 相比之下，释放锁问题没那么严重
// 释放锁的情况下只有超时是值得重试的，其它情况都不需要重试

package lock

import (
    "context"
    "time"

    "golang.org/x/sync/singleflight"
)

// ==================== singleflight 优化的分布式锁 ====================

// ClientWithSingleFlight 在 Client 的基础上增加 singleflight 优化
type ClientWithSingleFlight struct {
    *Client                  // 嵌入原始 Client
    g    singleflight.Group  // singleflight 组
}

func NewClientWithSingleFlight(client redis.Cmdable) *ClientWithSingleFlight {
    return &ClientWithSingleFlight{
        Client: NewClient(client),
    }
}

// Lock 使用 singleflight 优化加锁
// 同一个 key 的多个 goroutine，只有一个会去抢分布式锁
// 其他 goroutine 等待结果
func (c *ClientWithSingleFlight) Lock(
    ctx context.Context,
    key string,
    expiration time.Duration,
    retry RetryStrategy,
) (string, error) {
    // 使用 singleflight.Do
    // 同一个 key 同时只有一个 goroutine 执行加锁逻辑
    // 其他 goroutine 直接拿到结果
    val, err, _ := c.g.Do(key, func() (any, error) {
        return c.Client.Lock(ctx, key, expiration, retry)
    })

    if err != nil {
        return "", err
    }
    return val.(string), nil
}

// ==================== 两段式加锁 ====================
// singleflight + 分布式锁的组合也叫"两段式加锁"：
//
// 第一段：实例级别使用 singleflight
//   → 确保一个实例只有一个 goroutine 参与全局锁竞争
//
// 第二段：全局分布式锁
//   → 如果有 N 个实例，就是有 N 个 goroutine 去抢分布式锁
//
// 这样对 Redis 的压力从"总 QPS"降低到"实例数量"
// 热点越集中的应用，效果越好

// ==================== Redlock 算法简介 ====================
//
// 思路：不再部署单一主从集群，而是多个主节点（没有从节点）
//
// 比如说部署 5 个独立的 Redis 主节点：
//
//   Redis-1   Redis-2   Redis-3   Redis-4   Redis-5
//     ↑          ↑          ↑          ↑          ↑
//     └──────────┴──────────┴──────────┴──────────┘
//                        加锁
//
// 加锁过程：
//   1. 记录当前时间 T1
//   2. 依次向 5 个 Redis 节点发送 SETNX 请求
//   3. 每个请求设置很短的超时时间（如 50ms）
//   4. 记录当前时间 T2
//   5. 如果有 majority（多数，这里是 3 个）都成功
//      且 T2 - T1 < 锁的过期时间
//      则认为加锁成功
//   6. 如果加锁成功，锁的实际有效时间 = 过期时间 - (T2 - T1)
//   7. 如果加锁失败（没拿到多数），向所有节点发送 DEL 释放锁
//
// 优点：
//   - 不依赖主从复制，避免了主从切换导致锁丢失的问题
//
// 缺点：
//   - 需要 5 个独立的 Redis 实例，成本高
//   - 加锁和解锁需要对所有节点操作，延迟更高
//   - 仍然存在争议（时钟漂移等问题）

// ==================== 分布式锁使用原则 ====================
//
// 1. 你不能指望框架提供万无一失的方案
//    自己还是要处理各种异常情况（超时）
//
// 2. 自己写分布式锁，要考虑过期时间，以及要不要续约
//
// 3. 不管要对锁做什么操作，首先要确认这把锁是我们自己的锁
//    （用 UUID + Lua 脚本验证）
//
// 4. 大多数时候，与其选择复杂方案，不如直接让业务失败
//    有时候直接赔钱，比你部署一大堆节点、招一大堆开发、
//    搞好几个机房还要便宜，而且便宜很多
//
// 5. 选择恰好的方案，而不是完美的方案

// ==================== 缓存模式与一致性 ====================
//
// cache-aside：不能解决一致性问题
//   读时先查缓存，未命中查 DB 再回写
//   写时先写 DB 再删缓存
//   → 并发场景下依然可能出现不一致
//
// read-through：不能解决一致性问题
//   和 cache-aside 类似，只是把回源逻辑封装在缓存层
//
// write-through：不能解决一致性问题
//   先写 DB 再写缓存（或反过来），中间任何一步失败都会不一致

// ==================== write-back 与一致性 ====================
//
// 如果使用的是 Redis 这种缓存：
//
// 情况 1：缓存未命中不回查 DB
//   → 站在调用者的角度，不会有缓存不一致的问题
//   → 因为所有读写都走缓存，不直接读 DB
//   → 但问题是：缓存冷启动时没有数据，用户什么都读不到
//
// 情况 2：缓存未命中依旧回查 DB（大多数情况）
//   → 依旧会有缓存一致性问题
//   → 但在回查后写入缓存时，如果用 SetNX 命令（版本号控制）
//     也不会有一致性问题（除非在回查的瞬间，这个 key 的缓存
//     来了又过期了）
//
// 总结：write-back 在特定条件下可以缓解一致性问题
//   但不能完全解决，因为"部分失败"的根源还在

// ==================== refresh-ahead 与一致性 ====================
//
// refresh-ahead 也不能解决缓存一致性的问题
//
// 场景：通过 Canal 监听 MySQL binlog，数据变更时刷新缓存
//
// 时间线：
//   t1: 请求 1 读取数据，缓存未命中，从 DB 读取旧值 V1，回写缓存
//   t2: 请求 2 更新 DB，DB 值变为 V2
//   t3: Canal 监听到 binlog，准备刷新缓存
//   t4: ← 在 t2 和 t3 之间，缓存里的值是 V1，但 DB 里已经是 V2
//   t5: Canal 刷新缓存为 V2
//
// 在 Canal 刷新缓存之前（t2~t5），数据都是不一致的

// ==================== 方案一：一致性哈希 + singleflight ====================
//
// 思路：确保某个 key 对应的请求必然打到同一个机器上
//
// 原理：
//   1. 使用一致性哈希负载均衡，同一个 key 的请求总是路由到同一台机器
//   2. 机器内部使用 singleflight，同一个 key 只有一个 goroutine 在操作
//   3. 这样就控制住了"全局只有一个 goroutine 去更新特定 key 的数据"
//
// 一致性哈希的特点：
//   扩容和缩容时，同一个 key 的请求要么还是打到原来的机器上
//   要么打到另外一台机器上（不会同时打到两台）
//
// 唯一可能出现一致性问题的场景：扩容、缩容和应用重启

// ==================== 扩容时的问题与解决 ====================
//
// 场景：扩容时 key 的路由发生变化
//
//   请求 1、2 都操作同一个 key：
//   t1: 请求 1 被路由到机器 C 上
//   t2: 扩容，加入了 C1 节点
//   t3: 请求 2 被路由到了 C1 节点上
//   t4: 请求 1 更新 DB
//   t5: 请求 2 更新 DB，请求 2 更新缓存
//   t6: 请求 1 更新缓存 ← 此时请求 1 和请求 2 的缓存更新顺序可能错乱！
//
// 解决方案 1：在扩容/缩容时，直接在 C 上禁止对要迁移的 key 的缓存
//   → 不需要引入分布式锁，性能好
//   → 但如果频繁扩容缩容，效果不好
//
// 解决方案 2：加入 C1 节点，但 C1 此时不能启用缓存
//   → 等待一段时间，确认 C 上的请求都被处理之后
//   → 再开启 C1 的缓存

// ==================== 方案二：分布式锁 ====================
//
// 思路：直接加全局的分布式锁
//   不管你是先更新 DB 还是先更新缓存，都没问题
//   因为同一时间只有一个请求能操作同一个 key
//
// 适合：强一致性要求，极端写少的场景
//
// 注意点：
//   1. 写但凡多一点，性能衰退都很快
//      因为分布式锁对性能影响很大（网络开销 + 锁等待）
//
//   2. 可以采用两段式加锁优化
//      第一段：实例级别应用 singleflight
//        → 确保一个实例只有一个 goroutine 参与全局锁竞争
//      第二段：N 个实例的 N 个 goroutine 去抢分布式锁
//      → 最终全局只有一个 goroutine 更新特定 key 的数据
//
// ==================== 两段式加锁代码示例 ====================

type CacheWithLock struct {
    cache    Cache                  // 缓存客户端
    db       DB                     // 数据库客户端
    lockCli  *ClientWithSingleFlight // 带单飞优化的分布式锁
}

// DB 是数据库操作的接口（简化示例）
type DB interface {
    Update(ctx context.Context, key string, val any) error
}

// Update 更新数据（使用两段式加锁保证一致性）
func (c *CacheWithLock) Update(ctx context.Context, key string, val any) error {
    // 第一段：实例内 singleflight（在 ClientWithSingleFlight.Lock 内部实现）
    // 第二段：全局分布式锁
    lockVal, err := c.lockCli.Lock(
        ctx,
        "lock:"+key,       // 锁的 key
        10*time.Second,     // 过期时间
        NewExponentialBackoff(100*time.Millisecond, 1*time.Second, 3), // 指数退避重试
    )
    if err != nil {
        return err
    }
    defer func() {
        _ = c.lockCli.Unlock(ctx, "lock:"+key, lockVal)
    }()

    // 此时全局只有一个 goroutine 在操作这个 key
    // 可以安全地更新 DB 和缓存

    // 步骤 1：先更新 DB
    if err := c.db.Update(ctx, key, val); err != nil {
        return err
    }

    // 步骤 2：再删除缓存（注意是删除，不是更新）
    // 删除是幂等的，更安全
    if err := c.cache.Delete(ctx, key); err != nil {
        // 缓存删除失败
        // 可以记录日志，下次读请求会从 DB 重新加载
        log.Printf("缓存删除失败: key=%s, err=%v", key, err)
    }

    return nil
}

// ==================== 分布式锁核心原则 ====================
//
// 1. 不管要对锁做什么操作，首先要确认这把锁是我们自己的锁
//    → 用 UUID 作为值，用 Lua 脚本验证
//
// 2. 必须设置过期时间
//    → 防止持有者崩溃后锁永远不释放
//
// 3. 续约机制的三个核心问题
//    → 什么时候续约？（过期时间过半时）
//    → 续多长时间？（续为原始过期时间）
//    → 续约失败怎么办？（通知业务中断 + 执行回滚/补偿）
//
// 4. 选择恰好的方案，而不是完美的方案
//    → 大多数时候，直接让业务失败可能比部署复杂方案更便宜