《游戏服务端架构·品类、状态与拓扑》9.3 小游戏后端的轻量化与快速上线

客户端 ──► 无状态 API 服务（2 个副本）
               │
      ┌────────┼─────────┐
      ▼        ▼         ▼
  Postgres   Redis    对象存储
   （主库）  （缓存）  （图片/回放）

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

import (
	"errors"
	"sort"
	"strings"
	"sync"
	"time"
)

var (
	ErrBadVersion     = errors.New("minibackend: version must be positive")
	ErrBadEnv         = errors.New("minibackend: env must be staging or prod")
	ErrNoLimit        = errors.New("minibackend: at least one rate limit is required")
	ErrBadLimit       = errors.New("minibackend: limit name, per-second and burst must be positive")
	ErrNoCostCap      = errors.New("minibackend: daily cost cap must be positive")
	ErrBadFlag        = errors.New("minibackend: flag name must not be blank")
	ErrVersionExists  = errors.New("minibackend: version already published")
	ErrBadRollback    = errors.New("minibackend: rollback target must be a published earlier version")
	ErrUnknownVersion = errors.New("minibackend: unknown version")
)

type Limit struct {
	PerSecond int
	Burst     int
}

// Config is one immutable release snapshot. Publish clones it, so a caller
// cannot mutate the live config through a retained map reference.
type Config struct {
	Version           int
	Env               string
	RollbackTo        int
	Limits            map[string]Limit
	DailyCostCapCents int
	Flags             map[string]bool
}

func (c Config) clone() Config {
	out := c
	out.Limits = make(map[string]Limit, len(c.Limits))
	for k, v := range c.Limits {
		out.Limits[k] = v
	}
	out.Flags = make(map[string]bool, len(c.Flags))
	for k, v := range c.Flags {
		out.Flags[k] = v
	}
	return out
}

func (c Config) validate() error {
	if c.Version <= 0 {
		return ErrBadVersion
	}
	if c.Env != "staging" && c.Env != "prod" {
		return ErrBadEnv
	}
	if len(c.Limits) == 0 {
		return ErrNoLimit
	}
	for name, l := range c.Limits {
		if strings.TrimSpace(name) == "" || l.PerSecond <= 0 || l.Burst <= 0 {
			return ErrBadLimit
		}
	}
	if c.DailyCostCapCents <= 0 {
		return ErrNoCostCap
	}
	for name := range c.Flags {
		if strings.TrimSpace(name) == "" {
			return ErrBadFlag
		}
	}
	return nil
}

// Store is a tiny versioned config registry backed by memory. The same
// contract (monotonic versions, explicit rollback target) applies in Redis.
type Store struct {
	mu      sync.Mutex
	configs map[int]Config
	current int
}

func NewStore() *Store {
	return &Store{configs: map[int]Config{}}
}

func (s *Store) Publish(c Config) error {
	if err := c.validate(); err != nil {
		return err
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	if _, exists := s.configs[c.Version]; exists {
		return ErrVersionExists
	}
	if c.RollbackTo != 0 {
		target, ok := s.configs[c.RollbackTo]
		if !ok || target.Version >= c.Version {
			return ErrBadRollback
		}
	}
	s.configs[c.Version] = c.clone()
	s.current = c.Version
	return nil
}

func (s *Store) Current() (Config, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	c, ok := s.configs[s.current]
	if !ok {
		return Config{}, false
	}
	return c.clone(), true
}

func (s *Store) Rollback(version int) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if _, ok := s.configs[version]; !ok {
		return ErrUnknownVersion
	}
	s.current = version
	return nil
}

// Limiter is a deterministic token bucket. The clock is injected so tests and
// incident drills can replay the same burst and refill sequence.
type Limiter struct {
	mu      sync.Mutex
	now     func() time.Time
	limit   Limit
	buckets map[string]*bucket
}

type bucket struct {
	tokens float64
	last   time.Time
}

func NewLimiter(limit Limit, now func() time.Time) *Limiter {
	if now == nil {
		now = time.Now
	}
	return &Limiter{now: now, limit: limit, buckets: map[string]*bucket{}}
}

func (l *Limiter) Allow(key string) bool {
	if l.limit.PerSecond <= 0 || l.limit.Burst <= 0 || strings.TrimSpace(key) == "" {
		return false
	}
	l.mu.Lock()
	defer l.mu.Unlock()
	now := l.now()
	b, ok := l.buckets[key]
	if !ok {
		b = &bucket{tokens: float64(l.limit.Burst), last: now}
		l.buckets[key] = b
	}
	if elapsed := now.Sub(b.last).Seconds(); elapsed > 0 {
		b.tokens += elapsed * float64(l.limit.PerSecond)
		if b.tokens > float64(l.limit.Burst) {
			b.tokens = float64(l.limit.Burst)
		}
		b.last = now
	}
	if b.tokens < 1 {
		return false
	}
	b.tokens--
	return true
}

// Release is what the operator claims about a build. Optional items may be
// waived; blocking items cannot, because they are the minimum launch bar.
type Release struct {
	RollbackVersion int
	HealthCheck     bool
	RateLimit       bool
	CostCap         bool
	Owner           string
	Runbook         string
	Alerts          bool
	GrayPlan        bool
	LoadTest        bool
	Waivers         map[string]string
}

type Issue struct {
	Item     string
	Blocking bool
	Message  string
}

type Report struct {
	Ready  bool
	Issues []Issue
}

type checkItem struct {
	id       string
	blocking bool
	present  func(Release) bool
}

var checklist = []checkItem{
	{"rollback", true, func(r Release) bool { return r.RollbackVersion > 0 }},
	{"health_check", true, func(r Release) bool { return r.HealthCheck }},
	{"rate_limit", true, func(r Release) bool { return r.RateLimit }},
	{"cost_cap", true, func(r Release) bool { return r.CostCap }},
	{"owner", true, func(r Release) bool { return strings.TrimSpace(r.Owner) != "" }},
	{"runbook", true, func(r Release) bool { return strings.TrimSpace(r.Runbook) != "" }},
	{"alerts", true, func(r Release) bool { return r.Alerts }},
	{"gray_plan", false, func(r Release) bool { return r.GrayPlan }},
	{"load_test", false, func(r Release) bool { return r.LoadTest }},
}

// Preflight returns every missing item, sorted by ID, plus whether the build
// may launch. A waiver on a blocking item is reported, not honored.
func Preflight(r Release) Report {
	issues := make([]Issue, 0, len(checklist))
	for _, item := range checklist {
		if _, waived := r.Waivers[item.id]; waived && !item.blocking {
			continue
		}
		if item.present(r) {
			continue
		}
		issue := Issue{Item: item.id, Blocking: item.blocking}
		if item.blocking {
			issue.Message = "blocking item missing"
			if _, waived := r.Waivers[item.id]; waived {
				issue.Message = "blocking item cannot be waived"
			}
		} else {
			issue.Message = "optional item missing; add it or record a waiver"
		}
		issues = append(issues, issue)
	}
	sort.Slice(issues, func(i, j int) bool { return issues[i].Item < issues[j].Item })
	for _, issue := range issues {
		if issue.Blocking {
			return Report{Ready: false, Issues: issues}
		}
	}
	return Report{Ready: true, Issues: issues}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/minibackend
$ go vet ./internal/minibackend/
$ go test -count=1 ./internal/minibackend/
ok  	gsarchlab/internal/minibackend	0.572s