《游戏服务端编程实践》16.3 实战：构建后台管理系统

// file: ch16/admin/admin.go
// tier: L1
// verify: go test ./ch16/admin/

package admin

import (
	"errors"
	"fmt"
	"sync"
)

var (
	ErrInvalidRequest = errors.New("admin: invalid request")
	ErrUnknownAction  = errors.New("admin: unknown action")
	ErrQuotaExceeded  = errors.New("admin: quota exceeded")
	ErrKeyReused      = errors.New("admin: idempotency key reused with different payload")
)

const (
	StatusApplied   = "applied"
	StatusDuplicate = "duplicate"
	StatusFailed    = "failed"
)

// Request 是一次后台操作请求。
type Request struct {
	Key      string
	Action   string
	Target   string
	Operator string
	Args     map[string]string
}

// Operation 是可注册的后台操作。
type Operation interface {
	Name() string
	Validate(req Request) error
	Apply(req Request) (string, error)
}

// Result 是单条请求的执行结果。
type Result struct {
	Key       string
	Action    string
	Target    string
	Status    string
	Message   string
	Duplicate bool
}

type Failure struct {
	Index int
	Key   string
	Error string
}

// BatchReport 是批量操作的完整回执。
type BatchReport struct {
	Total      int
	Applied    int
	Duplicates int
	Failed     int
	Results    []Result
	Failures   []Failure
}

type cacheEntry struct {
	fingerprint string
	result      Result
}

type call struct {
	done chan struct{}
	fp   string
	res  Result
	err  error
}

// Executor 负责幂等缓存、配额与批量执行。
type Executor struct {
	mu           sync.Mutex
	ops          map[string]Operation
	cache        map[string]cacheEntry
	inflight     map[string]*call
	applied      map[string]int
	maxBatch     int
	defaultQuota int
}

func NewExecutor(maxBatch, defaultQuota int) *Executor {
	if maxBatch < 1 {
		maxBatch = 1
	}
	if defaultQuota < 1 {
		defaultQuota = 1
	}
	return &Executor{
		ops:          make(map[string]Operation),
		cache:        make(map[string]cacheEntry),
		inflight:     make(map[string]*call),
		applied:      make(map[string]int),
		maxBatch:     maxBatch,
		defaultQuota: defaultQuota,
	}
}

func (e *Executor) Register(op Operation) error {
	if op == nil || op.Name() == "" {
		return fmt.Errorf("%w: invalid operation", ErrInvalidRequest)
	}
	e.mu.Lock()
	defer e.mu.Unlock()
	if _, ok := e.ops[op.Name()]; ok {
		return fmt.Errorf("admin: operation %q already registered", op.Name())
	}
	e.ops[op.Name()] = op
	return nil
}

func (e *Executor) Applied(operator string) int {
	e.mu.Lock()
	defer e.mu.Unlock()
	return e.applied[operator]
}

// Run 执行一条请求；相同 Key 与相同载荷的重复提交直接返回缓存结果。
func (e *Executor) Run(req Request) (Result, error) {
	if req.Key == "" || req.Action == "" || req.Operator == "" {
		return Result{}, ErrInvalidRequest
	}
	fp := fingerprint(req)

	e.mu.Lock()
	if entry, ok := e.cache[req.Key]; ok {
		e.mu.Unlock()
		if entry.fingerprint != fp {
			return Result{}, ErrKeyReused
		}
		return duplicate(entry.result), nil
	}
	if pending, ok := e.inflight[req.Key]; ok {
		e.mu.Unlock()
		<-pending.done
		if pending.fp != fp {
			return Result{}, ErrKeyReused
		}
		if pending.err != nil {
			return Result{}, pending.err
		}
		return duplicate(pending.res), nil
	}
	op, ok := e.ops[req.Action]
	if !ok {
		e.mu.Unlock()
		return Result{}, ErrUnknownAction
	}
	if err := op.Validate(req); err != nil {
		e.mu.Unlock()
		return Result{}, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
	}
	if !e.reserveLocked(req.Operator) {
		e.mu.Unlock()
		return Result{}, ErrQuotaExceeded
	}
	pending := &call{done: make(chan struct{}), fp: fp}
	e.inflight[req.Key] = pending
	e.mu.Unlock()

	msg, err := op.Apply(req)

	e.mu.Lock()
	delete(e.inflight, req.Key)
	if err != nil {
		e.releaseLocked(req.Operator)
		pending.err = err
	} else {
		pending.res = Result{
			Key: req.Key, Action: req.Action, Target: req.Target,
			Status: StatusApplied, Message: msg,
		}
		e.cache[req.Key] = cacheEntry{fingerprint: fp, result: pending.res}
	}
	close(pending.done)
	e.mu.Unlock()
	return pending.res, pending.err
}

// RunBatch 逐条执行并汇总部分失败，不会因为一条失败而中止后续请求。
func (e *Executor) RunBatch(reqs []Request) (BatchReport, error) {
	if len(reqs) > e.maxBatch {
		return BatchReport{Total: len(reqs)},
			fmt.Errorf("%w: batch size %d exceeds limit %d", ErrQuotaExceeded, len(reqs), e.maxBatch)
	}
	report := BatchReport{Total: len(reqs), Results: make([]Result, 0, len(reqs))}
	for i, req := range reqs {
		res, err := e.Run(req)
		if err != nil {
			report.Failed++
			report.Failures = append(report.Failures, Failure{
				Index: i, Key: req.Key, Error: err.Error(),
			})
			report.Results = append(report.Results, Result{
				Key: req.Key, Action: req.Action, Target: req.Target,
				Status: StatusFailed, Message: err.Error(),
			})
			continue
		}
		report.Results = append(report.Results, res)
		if res.Status == StatusDuplicate {
			report.Duplicates++
		} else {
			report.Applied++
		}
	}
	return report, nil
}

func (e *Executor) reserveLocked(operator string) bool {
	if e.applied[operator] >= e.defaultQuota {
		return false
	}
	e.applied[operator]++
	return true
}

func (e *Executor) releaseLocked(operator string) {
	if e.applied[operator] > 0 {
		e.applied[operator]--
	}
}

func duplicate(res Result) Result {
	res.Duplicate = true
	res.Status = StatusDuplicate
	return res
}

func fingerprint(req Request) string {
	return fmt.Sprintf("%s\x00%s\x00%v", req.Action, req.Target, req.Args)
}

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