《游戏服务端编程实践》12.3 状态一致性与幂等性

UPDATE player_asset
SET gold = gold - 100, version = version + 1
WHERE player_id = ? AND version = ?;

// file: ch12/idempotent/idempotent.go
// tier: L1
// verify: go test ./ch12/idempotent/

// Package idempotent 演示版本号 CAS、乐观锁重试与带过期时间的幂等表。
package idempotent

import (
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"runtime"
	"sync"
	"time"
)

var (
	ErrEmptyKey            = errors.New("idempotent: empty key")
	ErrEmptyFingerprint    = errors.New("idempotent: empty fingerprint")
	ErrVersionConflict     = errors.New("idempotent: version conflict")
	ErrFingerprintMismatch = errors.New("idempotent: fingerprint mismatch")
)

// Record 是带版本号的玩家状态片段。Version 从 0 开始，每次成功写入加一。
type Record struct {
	Version uint64
	Value   string
}

// Store 保存版本化记录，CAS 是唯一的写入口。
type Store struct {
	mu      sync.Mutex
	records map[string]Record
}

func NewStore() *Store {
	return &Store{records: make(map[string]Record)}
}

// Get 返回记录副本；第二个返回值表示键是否存在。
func (s *Store) Get(key string) (Record, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	r, ok := s.records[key]
	return r, ok
}

// CAS 只有当前版本等于 expected 时才写入 value，并把版本加一。
// 新键的当前版本视为 0，因此首次写入需要传 expected=0。
func (s *Store) CAS(key string, expected uint64, value string) (Record, error) {
	if key == "" {
		return Record{}, ErrEmptyKey
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	cur := s.records[key]
	if cur.Version != expected {
		return cur, fmt.Errorf("%w: key=%s current=%d expected=%d",
			ErrVersionConflict, key, cur.Version, expected)
	}
	next := Record{Version: expected + 1, Value: value}
	s.records[key] = next
	return next, nil
}

// Apply 在版本冲突时重新读取并重试，mutate 收到当前记录并返回新值。
// 重试次数不设上限，但每次冲突都让出 CPU，避免在锁竞争下忙等。
func (s *Store) Apply(key string, mutate func(Record) (string, error)) (Record, error) {
	for {
		cur, _ := s.Get(key)
		value, err := mutate(cur)
		if err != nil {
			return Record{}, err
		}
		next, err := s.CAS(key, cur.Version, value)
		if err == nil {
			return next, nil
		}
		if !errors.Is(err, ErrVersionConflict) {
			return Record{}, err
		}
		runtime.Gosched()
	}
}

// Result 是幂等执行缓存下来的结果。
type Result struct {
	Version uint64
	Value   string
}

type entry struct {
	fingerprint string
	result      Result
	expiresAt   time.Time
}

type inflight struct {
	fingerprint string
	done        chan struct{}
	result      Result
	err         error
}

// Idempotency 用 key 去重，用 fingerprint 防止同一个 key 被不同请求复用。
// 结果只在 ttl 内复用，过期后允许重新执行。
type Idempotency struct {
	mu       sync.Mutex
	ttl      time.Duration
	now      func() time.Time
	entries  map[string]entry
	inflight map[string]*inflight
}

// New 创建幂等表。now 为 nil 时使用 time.Now，测试可以注入可控时钟。
func New(ttl time.Duration, now func() time.Time) *Idempotency {
	if now == nil {
		now = time.Now
	}
	return &Idempotency{
		ttl:      ttl,
		now:      now,
		entries:  make(map[string]entry),
		inflight: make(map[string]*inflight),
	}
}

// Do 在 key 未命中时执行 fn，命中未过期结果时直接返回缓存。
// replayed 表示本次调用没有真正执行 fn。
func (i *Idempotency) Do(key, fingerprint string, fn func() (Result, error)) (Result, bool, error) {
	if key == "" {
		return Result{}, false, ErrEmptyKey
	}
	if fingerprint == "" {
		return Result{}, false, ErrEmptyFingerprint
	}

	i.mu.Lock()
	if e, ok := i.entries[key]; ok {
		if i.now().Before(e.expiresAt) {
			if e.fingerprint != fingerprint {
				i.mu.Unlock()
				return Result{}, false, ErrFingerprintMismatch
			}
			i.mu.Unlock()
			return e.result, true, nil
		}
		delete(i.entries, key)
	}
	if call, ok := i.inflight[key]; ok {
		if call.fingerprint != fingerprint {
			i.mu.Unlock()
			return Result{}, false, ErrFingerprintMismatch
		}
		i.mu.Unlock()
		<-call.done
		return call.result, true, call.err
	}
	call := &inflight{fingerprint: fingerprint, done: make(chan struct{})}
	i.inflight[key] = call
	i.mu.Unlock()

	result, err := fn()

	i.mu.Lock()
	delete(i.inflight, key)
	if err == nil {
		i.entries[key] = entry{
			fingerprint: fingerprint,
			result:      result,
			expiresAt:   i.now().Add(i.ttl),
		}
	}
	call.result, call.err = result, err
	close(call.done)
	i.mu.Unlock()
	return result, false, err
}

// Fingerprint 把业务参数规范化后拼成请求指纹。
// 分隔符用 0x00，避免 ("ab","c") 与 ("a","bc") 得到同一个摘要。
func Fingerprint(parts ...string) string {
	h := sha256.New()
	for _, p := range parts {
		h.Write([]byte(p))
		h.Write([]byte{0})
	}
	return hex.EncodeToString(h.Sum(nil))
}

cd .local/checks/gs-practice-lab && gofmt -l ch12/idempotent && go vet ./ch12/idempotent/ && go test ./ch12/idempotent/ -count=1

ok  	gspractice/ch12/idempotent	0.334s