《游戏服务端架构·规模化、全球化与成本》5.2 热 key、穿透与击穿

t0        t1(逻辑过期)      t2(宽限期结束)
 |--- 新鲜 ---|------ 可兜底旧值 ------|
              |                         |
         一个请求刷新          刷新仍失败则报错

// file: internal/hotkeyguard/guard.go
// tier: L1
// verify: go test ./internal/hotkeyguard/
package hotkeyguard

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

// Source 说明本次返回值从哪里来，调用方据此决定是否给客户端打“旧值”标记。
type Source int

const (
	SourceFresh Source = iota
	SourceLoaded
	SourceCoalesced
	SourceStale
	SourceNegative
)

func (s Source) String() string {
	switch s {
	case SourceFresh:
		return "fresh"
	case SourceLoaded:
		return "loaded"
	case SourceCoalesced:
		return "coalesced"
	case SourceStale:
		return "stale"
	case SourceNegative:
		return "negative"
	default:
		return "none"
	}
}

var (
	ErrEmptyKey  = errors.New("hotkeyguard: empty key")
	ErrNilLoader = errors.New("hotkeyguard: nil loader")
)

// Config 是热点保护的全部时间参数。
type Config struct {
	TTL          time.Duration // 逻辑过期时间
	StaleGrace   time.Duration // 过期后仍可用旧值兜底的窗口
	NullTTL      time.Duration // 空值缓存时间，防止穿透
	Window       time.Duration // 热 key 统计窗口
	HotThreshold int           // 窗口内达到该次数即视为热 key
}

// Result 带数据新鲜度：Age 从最近一次成功加载算起，Stale 为真时必须告知调用方。
type Result struct {
	Value  string
	Source Source
	Stale  bool
	Age    time.Duration
}

type entry struct {
	value      string
	storedAt   time.Time
	expiresAt  time.Time
	staleUntil time.Time
}

type call struct {
	done   chan struct{}
	value  string
	source Source
	stale  bool
	err    error
}

// Guard 合并同一 key 的并发回源请求，并提供空值缓存与旧值兜底。
type Guard struct {
	mu          sync.Mutex
	cfg         Config
	now         func() time.Time
	entries     map[string]entry
	negative    map[string]time.Time
	inflight    map[string]*call
	counts      map[string]int
	windowStart time.Time
}

func New(cfg Config, now func() time.Time) *Guard {
	if now == nil {
		now = time.Now
	}
	if cfg.TTL <= 0 {
		cfg.TTL = 30 * time.Second
	}
	if cfg.StaleGrace < 0 {
		cfg.StaleGrace = 0
	}
	if cfg.NullTTL <= 0 {
		cfg.NullTTL = 5 * time.Second
	}
	if cfg.Window <= 0 {
		cfg.Window = time.Minute
	}
	if cfg.HotThreshold <= 0 {
		cfg.HotThreshold = 100
	}
	return &Guard{
		cfg:         cfg,
		now:         now,
		entries:     map[string]entry{},
		negative:    map[string]time.Time{},
		inflight:    map[string]*call{},
		counts:      map[string]int{},
		windowStart: now(),
	}
}

// Get 返回 key 的值。同一 key 并发未命中时只有一个 goroutine 真正回源。
func (g *Guard) Get(key string, load func() (string, error)) (Result, error) {
	if key == "" {
		return Result{}, ErrEmptyKey
	}
	if load == nil {
		return Result{}, ErrNilLoader
	}

	g.mu.Lock()
	g.observeLocked(key)
	now := g.now()
	if until, ok := g.negative[key]; ok {
		if now.Before(until) {
			g.mu.Unlock()
			return Result{Source: SourceNegative}, nil
		}
		delete(g.negative, key)
	}
	if e, ok := g.entries[key]; ok && now.Before(e.expiresAt) {
		g.mu.Unlock()
		return Result{Value: e.value, Source: SourceFresh, Age: now.Sub(e.storedAt)}, nil
	}
	if c, ok := g.inflight[key]; ok {
		g.mu.Unlock()
		<-c.done
		return Result{Value: c.value, Source: SourceCoalesced, Stale: c.stale}, c.err
	}
	c := &call{done: make(chan struct{})}
	g.inflight[key] = c
	prev, hasPrev := g.entries[key]
	g.mu.Unlock()

	value, err := load()

	g.mu.Lock()
	now = g.now()
	delete(g.inflight, key)
	switch {
	case err != nil:
		if hasPrev && now.Before(prev.staleUntil) {
			c.value, c.source, c.stale = prev.value, SourceStale, true
		} else {
			c.err = err
		}
	case value == "":
		g.negative[key] = now.Add(g.cfg.NullTTL)
		delete(g.entries, key)
		c.source = SourceNegative
	default:
		g.entries[key] = entry{
			value:      value,
			storedAt:   now,
			expiresAt:  now.Add(g.cfg.TTL),
			staleUntil: now.Add(g.cfg.TTL + g.cfg.StaleGrace),
		}
		c.value, c.source = value, SourceLoaded
	}
	close(c.done)
	result := Result{Value: c.value, Source: c.source, Stale: c.stale}
	if hasPrev && c.stale {
		result.Age = now.Sub(prev.storedAt)
	}
	g.mu.Unlock()
	return result, c.err
}

func (g *Guard) observeLocked(key string) int {
	now := g.now()
	if now.Before(g.windowStart) || now.Sub(g.windowStart) >= g.cfg.Window {
		g.counts = map[string]int{}
		g.windowStart = now
	}
	g.counts[key]++
	return g.counts[key]
}

// Invalidate 主动删除本地值与空值标记，用于配置变更或人工修复。
func (g *Guard) Invalidate(key string) {
	g.mu.Lock()
	defer g.mu.Unlock()
	delete(g.entries, key)
	delete(g.negative, key)
}