《游戏服务端架构·规模化、全球化与成本》8.3 有状态服务的灾难恢复

账号与登录
   |
   +--> 玩家资产（背包、货币）
   |       |
   |       +--> 商城与支付确认
   |       |
   |       +--> 匹配与房间
   |               |
   |               +--> 对局结算
   |
   +--> 社交与聊天（可独立降级）

世界状态（SLG）
   |
   +--> 联盟与占领
   +--> 赛季与排行榜
   +--> 离线推进与定时结算

// file: internal/statedr/statedr.go
// tier: L1
// verify: go test ./internal/statedr/
package statedr

import (
	"errors"
	"fmt"
)

var (
	ErrGap        = errors.New("event gap")
	ErrDuplicate  = errors.New("duplicate sequence")
	ErrIncomplete = errors.New("target sequence not reached")
)

// Event 是房间状态的一条增量；Seq 必须连续，不能跳号。
type Event struct {
	Seq      uint64
	PlayerID string
	Delta    int64
	AtUnixMs int64
}

// Snapshot 是某一时刻的房间状态；Balances 在恢复时会被复制，调用方无需加锁。
type Snapshot struct {
	RoomID   string
	Seq      uint64
	AtUnixMs int64
	Balances map[string]int64
}

func (s Snapshot) clone() Snapshot {
	out := Snapshot{
		RoomID:   s.RoomID,
		Seq:      s.Seq,
		AtUnixMs: s.AtUnixMs,
		Balances: make(map[string]int64, len(s.Balances)),
	}
	for k, v := range s.Balances {
		out.Balances[k] = v
	}
	return out
}

// Restore 把快照推进到 target。事件必须从 Seq+1 开始连续；跳号或重复都返回错误，
// 因为“少一条事件”比“恢复失败”危险得多。
func Restore(s Snapshot, events []Event, target uint64) (Snapshot, int, error) {
	out := s.clone()
	if target <= s.Seq {
		return out, 0, nil
	}
	expect := s.Seq + 1
	applied := 0
	for _, e := range events {
		if e.Seq <= s.Seq {
			continue
		}
		if e.Seq > target {
			break
		}
		switch {
		case e.Seq < expect:
			return Snapshot{}, 0, fmt.Errorf("%w: seq=%d", ErrDuplicate, e.Seq)
		case e.Seq > expect:
			return Snapshot{}, 0, fmt.Errorf("%w: want=%d got=%d", ErrGap, expect, e.Seq)
		}
		out.Balances[e.PlayerID] += e.Delta
		out.Seq = e.Seq
		if e.AtUnixMs > out.AtUnixMs {
			out.AtUnixMs = e.AtUnixMs
		}
		expect++
		applied++
	}
	if out.Seq < target {
		return out, applied, fmt.Errorf("%w: target=%d reached=%d", ErrIncomplete, target, out.Seq)
	}
	return out, applied, nil
}

// Reconnect 是重连补偿计划；Expired 为 true 时客户端必须接受“从新状态开始”。
type Reconnect struct {
	RoomID  string
	FromSeq uint64
	ToSeq   uint64
	Replay  []Event
	Expired bool
	Reason  string
}

// PlanReconnect 计算断线重连需要补发的事件。快照超过 TTL 时不再回放，
// 因为长时间离线后的状态已经无法用增量解释，继续回放只会制造幻觉。
func PlanReconnect(s Snapshot, events []Event, current uint64, nowMs, ttlMs int64) Reconnect {
	rc := Reconnect{RoomID: s.RoomID, FromSeq: s.Seq, ToSeq: current}
	if ttlMs > 0 && nowMs-s.AtUnixMs > ttlMs {
		rc.Expired = true
		rc.Reason = "snapshot_expired"
		return rc
	}
	if current <= s.Seq {
		rc.Reason = "already_current"
		return rc
	}
	expect := s.Seq + 1
	for _, e := range events {
		if e.Seq <= s.Seq || e.Seq > current {
			continue
		}
		if e.Seq != expect {
			rc.Expired = true
			rc.Reason = "event_gap"
			rc.Replay = nil
			return rc
		}
		rc.Replay = append(rc.Replay, e)
		expect++
	}
	if expect != current+1 {
		rc.Expired = true
		rc.Reason = "event_gap"
		rc.Replay = nil
	}
	return rc
}

// file: internal/statedr/idempotent.go
// tier: L1
// verify: go test ./internal/statedr/
package statedr

import "errors"

// ErrNegativeAmount 拒绝负额度，避免“幂等”掩盖金额错误。
var ErrNegativeAmount = errors.New("amount must be non-negative")

// RequestLog 是有限容量的幂等键表：按键缓存成功结果，重复请求直接返回旧值。
type RequestLog struct {
	capacity int
	results  map[string]int64
	order    []string
}

func NewRequestLog(capacity int) *RequestLog {
	if capacity <= 0 {
		capacity = 1
	}
	return &RequestLog{
		capacity: capacity,
		results:  make(map[string]int64, capacity),
	}
}

// Once 执行 fn 并在成功后记住结果；replayed 为 true 表示没有再次执行 fn。
// 失败不缓存，这样客户端重试仍有机会成功。
func (l *RequestLog) Once(key string, fn func() (int64, error)) (result int64, replayed bool, err error) {
	if v, ok := l.results[key]; ok {
		return v, true, nil
	}
	v, err := fn()
	if err != nil {
		return 0, false, err
	}
	l.results[key] = v
	l.order = append(l.order, key)
	if len(l.order) > l.capacity {
		oldest := l.order[0]
		l.order = l.order[1:]
		delete(l.results, oldest)
	}
	return v, false, nil
}

// Ledger 是奖励账本；同一个 grant key 只生效一次，重复请求返回 false。
type Ledger struct {
	applied map[string]struct{}
	Balance int64
}

func NewLedger() *Ledger {
	return &Ledger{applied: make(map[string]struct{})}
}

// Grant 以业务键去重后入账。返回 false 表示这是重复请求，账本没有变化。
func (l *Ledger) Grant(key string, amount int64) (bool, error) {
	if amount < 0 {
		return false, ErrNegativeAmount
	}
	if _, ok := l.applied[key]; ok {
		return false, nil
	}
	l.applied[key] = struct{}{}
	l.Balance += amount
	return true, nil
}

cd .local/checks/gsarch-lab
gofmt -l internal/statedr
go vet ./internal/statedr/
go test -count=1 ./internal/statedr/