《游戏服务端编程实践》12.1 实时状态与快照策略

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

// Package snapshot 演示游戏热状态的“全量快照 + 增量日志”恢复模型。
package snapshot

import (
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"sync"
)

var (
	// ErrBeforeSnapshot 表示请求的版本早于最近一次全量快照。
	ErrBeforeSnapshot = errors.New("snapshot: version predates the base snapshot")
	// ErrVersionGap 表示日志版本不连续，说明日志被误删或损坏。
	ErrVersionGap = errors.New("snapshot: wal version gap")
	// ErrEmptyKey 表示键为空。
	ErrEmptyKey = errors.New("snapshot: empty key")
)

// Image 是一份状态副本，既可作为快照落盘，也可作为恢复结果。
type Image struct {
	Version uint64            `json:"version"`
	Data    map[string]string `json:"data"`
}

// Store 是内存热状态。写操作先追加日志，再修改内存。
type Store struct {
	mu      sync.RWMutex
	data    map[string]string
	version uint64
	dir     string
	wal     *WAL

	snapMu      sync.Mutex
	snapVersion uint64
}

// Open 加载最近快照并重放其后的日志。
func Open(dir string) (*Store, error) {
	img, err := Load(dir, 0)
	if err != nil {
		return nil, err
	}
	wal, err := OpenWAL(dir)
	if err != nil {
		return nil, err
	}
	return &Store{
		data:        img.Data,
		version:     img.Version,
		dir:         dir,
		wal:         wal,
		snapVersion: img.Version,
	}, nil
}

// Load 从目录恢复状态。upto 为 0 表示恢复到最新版本，否则恢复到指定版本。
func Load(dir string, upto uint64) (*Image, error) {
	base := &Image{Version: 0, Data: map[string]string{}}
	raw, err := os.ReadFile(filepath.Join(dir, "snapshot.json"))
	switch {
	case err == nil:
		if err := json.Unmarshal(raw, base); err != nil {
			return nil, err
		}
		if base.Data == nil {
			base.Data = map[string]string{}
		}
	case !errors.Is(err, os.ErrNotExist):
		return nil, err
	}
	if upto != 0 && upto < base.Version {
		return nil, fmt.Errorf("%w: want %d, base %d", ErrBeforeSnapshot, upto, base.Version)
	}
	entries, err := readEntries(filepath.Join(dir, "wal.log"))
	if err != nil {
		return nil, err
	}
	last := base.Version
	for _, e := range entries {
		if e.Version <= base.Version {
			continue
		}
		if e.Version != last+1 {
			return nil, fmt.Errorf("%w: got %d after %d", ErrVersionGap, e.Version, last)
		}
		if upto != 0 && e.Version > upto {
			break
		}
		apply(base.Data, e)
		last = e.Version
	}
	if upto != 0 && last < upto {
		return nil, fmt.Errorf("%w: want %d, last %d", ErrVersionGap, upto, last)
	}
	base.Version = last
	return base, nil
}

// Put 写入一个键，返回分配到的版本号。
func (s *Store) Put(key, value string) (uint64, error) {
	if key == "" {
		return 0, ErrEmptyKey
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	next := s.version + 1
	if err := s.wal.Append(Entry{Version: next, Op: OpPut, Key: key, Value: value}); err != nil {
		return 0, err
	}
	s.data[key] = value
	s.version = next
	return next, nil
}

// Delete 删除一个键，返回分配到的版本号。
func (s *Store) Delete(key string) (uint64, error) {
	if key == "" {
		return 0, ErrEmptyKey
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	next := s.version + 1
	if err := s.wal.Append(Entry{Version: next, Op: OpDelete, Key: key}); err != nil {
		return 0, err
	}
	delete(s.data, key)
	s.version = next
	return next, nil
}

// Get 返回内存中的当前值。
func (s *Store) Get(key string) (string, bool) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	v, ok := s.data[key]
	return v, ok
}

// Version 返回当前版本号。
func (s *Store) Version() uint64 {
	s.mu.RLock()
	defer s.mu.RUnlock()
	return s.version
}

// Snapshot 复制当前状态并原子写入 snapshot.json，然后截断已被覆盖的日志。
// 复制在短读锁内完成，文件写入不阻塞 Put/Delete。
func (s *Store) Snapshot() (*Image, error) {
	s.mu.RLock()
	img := &Image{Version: s.version, Data: make(map[string]string, len(s.data))}
	for k, v := range s.data {
		img.Data[k] = v
	}
	s.mu.RUnlock()

	s.snapMu.Lock()
	defer s.snapMu.Unlock()
	if img.Version < s.snapVersion {
		return img, nil // 更新的快照已经落盘，放弃这次重复写。
	}
	if err := writeImage(filepath.Join(s.dir, "snapshot.json"), img); err != nil {
		return nil, err
	}
	s.snapVersion = img.Version
	if err := s.wal.Truncate(img.Version); err != nil {
		return nil, err
	}
	return img, nil
}

// Close 关闭日志句柄；内存状态仍然可读，但不再接受持久写入。
func (s *Store) Close() error {
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.wal.Close()
}

func apply(data map[string]string, e Entry) {
	switch e.Op {
	case OpPut:
		data[e.Key] = e.Value
	case OpDelete:
		delete(data, e.Key)
	}
}

func writeImage(path string, img *Image) error {
	raw, err := json.Marshal(img)
	if err != nil {
		return err
	}
	tmp := path + ".tmp"
	f, err := os.OpenFile(tmp, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644)
	if err != nil {
		return err
	}
	if _, err := f.Write(raw); err != nil {
		_ = f.Close()
		return err
	}
	if err := f.Sync(); err != nil {
		_ = f.Close()
		return err
	}
	if err := f.Close(); err != nil {
		return err
	}
	return os.Rename(tmp, path)
}

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

ok  	gspractice/ch12/snapshot	3.284s