《游戏服务端架构·规模化、全球化与成本》5.1 本地缓存、分布式缓存与多级缓存

writer ──save v7──> store
   │
   └──publish v7──> node A: floor 7, local deleted
                    node B: floor 5 -> gap, suspect
                    node B ──resync──> store v7, floor 7

// file: internal/multicache/cache.go
// tier: L1
// verify: go test ./internal/multicache/
package multicache

import (
	"errors"
	"sync"
	"time"
)

// Kind 描述一类缓存对象允许的陈旧程度。TTL 越短，本地副本越容易过期。
type Kind int

const (
	Config Kind = iota
	Snapshot
	Leaderboard
	Relationship
)

// LocalTTL 返回该类对象在本地缓存中的存活时间。0 表示不进本地缓存。
func (k Kind) LocalTTL() time.Duration {
	switch k {
	case Config:
		return 10 * time.Minute
	case Snapshot:
		return 30 * time.Second
	case Leaderboard:
		return 15 * time.Second
	default:
		return 0
	}
}

func (k Kind) String() string {
	switch k {
	case Config:
		return "config"
	case Snapshot:
		return "snapshot"
	case Leaderboard:
		return "leaderboard"
	case Relationship:
		return "relationship"
	default:
		return "unknown"
	}
}

// Entry 是缓存条目。Version 由权威存储分配，缓存节点不能自行递增。
type Entry struct {
	Key       string
	Value     string
	Version   uint64
	ExpiresAt time.Time
}

// Invalidation 是广播到各节点的失效消息。
type Invalidation struct {
	Key     string
	Version uint64
}

// Gap 记录一次失效应用的结果。Lost 为真表示版本号出现跳号，可能丢过广播。
type Gap struct {
	Key  string
	Lost bool
	From uint64
	To   uint64
}

var (
	ErrEmptyKey       = errors.New("multicache: empty key")
	ErrInvalidVersion = errors.New("multicache: version must be positive")
	ErrNotFound       = errors.New("multicache: key not found")
)

// Store 是权威存储或分布式缓存的抽象。Load 必须返回带版本的条目。
type Store interface {
	Load(key string) (Entry, error)
	Save(entry Entry) error
}

// Cache 是单节点的两级缓存读侧：本地命中优先，未命中回源 Store。
type Cache struct {
	mu      sync.Mutex
	now     func() time.Time
	store   Store
	local   map[string]Entry
	floor   map[string]uint64
	suspect map[string]bool
	hits    int64
	misses  int64
	lost    int
}

func New(store Store, now func() time.Time) *Cache {
	if now == nil {
		now = time.Now
	}
	return &Cache{
		now:     now,
		store:   store,
		local:   map[string]Entry{},
		floor:   map[string]uint64{},
		suspect: map[string]bool{},
	}
}

// Get 先查本地，再回源。第二个返回值表示是否本地命中。
func (c *Cache) Get(key string, kind Kind) (Entry, bool, error) {
	if key == "" {
		return Entry{}, false, ErrEmptyKey
	}
	if entry, ok := c.lookup(key); ok {
		return entry, true, nil
	}
	entry, err := c.store.Load(key)
	if err != nil {
		return Entry{}, false, err
	}
	c.admit(entry, kind)
	return entry, false, nil
}

func (c *Cache) lookup(key string) (Entry, bool) {
	c.mu.Lock()
	defer c.mu.Unlock()
	entry, ok := c.local[key]
	if !ok {
		c.misses++
		return Entry{}, false
	}
	if c.suspect[key] || entry.Version < c.floor[key] {
		c.misses++
		return Entry{}, false
	}
	if !c.now().Before(entry.ExpiresAt) {
		delete(c.local, key)
		c.misses++
		return Entry{}, false
	}
	c.hits++
	return entry, true
}

func (c *Cache) admit(entry Entry, kind Kind) {
	ttl := kind.LocalTTL()
	if ttl <= 0 {
		return
	}
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.suspect[entry.Key] || entry.Version < c.floor[entry.Key] {
		return
	}
	if entry.Version > c.floor[entry.Key] {
		c.floor[entry.Key] = entry.Version
	}
	entry.ExpiresAt = c.now().Add(ttl)
	c.local[entry.Key] = entry
}

// Put 先写权威存储，再在本地应用同一版本号的失效。
func (c *Cache) Put(entry Entry) (Invalidation, error) {
	if entry.Key == "" {
		return Invalidation{}, ErrEmptyKey
	}
	if entry.Version == 0 {
		return Invalidation{}, ErrInvalidVersion
	}
	if err := c.store.Save(entry); err != nil {
		return Invalidation{}, err
	}
	inv := Invalidation{Key: entry.Key, Version: entry.Version}
	c.Apply(inv)
	return inv, nil
}

// Apply 处理一条来自广播的失效消息。旧消息直接忽略。
func (c *Cache) Apply(inv Invalidation) Gap {
	c.mu.Lock()
	defer c.mu.Unlock()
	if inv.Key == "" || inv.Version == 0 {
		return Gap{}
	}
	floor := c.floor[inv.Key]
	if inv.Version <= floor {
		return Gap{Key: inv.Key, From: floor, To: floor}
	}
	lost := floor > 0 && inv.Version > floor+1
	c.floor[inv.Key] = inv.Version
	delete(c.local, inv.Key)
	if lost {
		c.suspect[inv.Key] = true
		c.lost++
	}
	return Gap{Key: inv.Key, Lost: lost, From: floor, To: inv.Version}
}

// Resync 丢弃本地副本并从 Store 重新对齐版本水位。
func (c *Cache) Resync(key string) (Entry, error) {
	if key == "" {
		return Entry{}, ErrEmptyKey
	}
	entry, err := c.store.Load(key)
	if err != nil {
		return Entry{}, err
	}
	c.mu.Lock()
	defer c.mu.Unlock()
	if entry.Version > c.floor[key] {
		c.floor[key] = entry.Version
	}
	delete(c.local, key)
	delete(c.suspect, key)
	return entry, nil
}