《游戏服务端编程实践》8.2.1 指令投递与执行队列

// file: ch08/skill/queue.go
// tier: L1
// verify: go test ./ch08/skill/

package skill

import (
	"errors"
	"sort"
)

var (
	ErrInvalidCommand = errors.New("invalid command")
	ErrQueueClosed    = errors.New("command queue closed")
)

// Command 是客户端意图，不是结果。Frame 表示希望在第几帧执行，
// ExpireFrame 为 0 表示不主动过期。
type Command struct {
	PlayerID    uint64
	ID          uint64
	Frame       uint64
	Kind        string
	Target      uint64
	Priority    int
	ExpireFrame uint64
}

type Rejection struct {
	Command Command
	Reason  error
}

type QueueStats struct {
	Accepted  int
	Duplicate int
	Expired   int
	Rejected  int
	Popped    int
}

type commandKey struct {
	player uint64
	id     uint64
}

type pendingCommand struct {
	Command
	seq uint64
}

// CommandQueue 只负责排序、去重、过期和拒绝记录，不执行战斗逻辑。
type CommandQueue struct {
	dedupeWindow uint64
	validate     func(Command) error

	seq     uint64
	pending []pendingCommand
	seen    map[commandKey]uint64
	stats   QueueStats
	rejects []Rejection
	closed  bool
}

func NewCommandQueue(dedupeWindow uint64) *CommandQueue {
	if dedupeWindow == 0 {
		dedupeWindow = 120
	}
	return &CommandQueue{dedupeWindow: dedupeWindow, seen: make(map[commandKey]uint64)}
}

// SetValidator 在出队时校验目标、距离、冷却等依赖当前世界状态的条件。
func (q *CommandQueue) SetValidator(fn func(Command) error) { q.validate = fn }

func (q *CommandQueue) Close() { q.closed = true }

func (q *CommandQueue) Len() int { return len(q.pending) }

func (q *CommandQueue) Stats() QueueStats { return q.stats }

func (q *CommandQueue) Rejections() []Rejection {
	return append([]Rejection(nil), q.rejects...)
}

func (q *CommandQueue) Push(cmd Command) error {
	if q.closed {
		return ErrQueueClosed
	}
	if cmd.PlayerID == 0 || cmd.ID == 0 || cmd.Kind == "" {
		q.reject(cmd, ErrInvalidCommand)
		return ErrInvalidCommand
	}
	if cmd.ExpireFrame != 0 && cmd.ExpireFrame < cmd.Frame {
		q.reject(cmd, ErrInvalidCommand)
		return ErrInvalidCommand
	}
	q.pruneSeen(cmd.Frame)
	key := commandKey{player: cmd.PlayerID, id: cmd.ID}
	if _, ok := q.seen[key]; ok {
		q.stats.Duplicate++
		return nil
	}
	q.seen[key] = cmd.Frame
	q.seq++
	q.pending = append(q.pending, pendingCommand{Command: cmd, seq: q.seq})
	q.stats.Accepted++
	return nil
}

// PopDue 取出 Frame <= frame 的全部指令，按帧号、优先级、到达顺序排序。
// 同帧内 Priority 大的先执行；优先级相同则按 Push 的先后执行。
func (q *CommandQueue) PopDue(frame uint64) []Command {
	kept := q.pending[:0]
	due := make([]pendingCommand, 0, len(q.pending))
	for _, p := range q.pending {
		if p.Frame > frame {
			kept = append(kept, p)
			continue
		}
		if p.ExpireFrame != 0 && frame > p.ExpireFrame {
			q.stats.Expired++
			continue
		}
		if q.validate != nil {
			if err := q.validate(p.Command); err != nil {
				q.reject(p.Command, err)
				continue
			}
		}
		due = append(due, p)
	}
	q.pending = kept
	sort.Slice(due, func(i, j int) bool {
		if due[i].Frame != due[j].Frame {
			return due[i].Frame < due[j].Frame
		}
		if due[i].Priority != due[j].Priority {
			return due[i].Priority > due[j].Priority
		}
		return due[i].seq < due[j].seq
	})
	q.pruneSeen(frame)
	out := make([]Command, len(due))
	for i := range due {
		out[i] = due[i].Command
	}
	q.stats.Popped += len(out)
	return out
}

// pruneSeen 把去重窗口外的指令号释放掉，避免 seen 无限增长。
func (q *CommandQueue) pruneSeen(frame uint64) {
	for key, f := range q.seen {
		if f+q.dedupeWindow < frame {
			delete(q.seen, key)
		}
	}
}

func (q *CommandQueue) reject(cmd Command, err error) {
	q.stats.Rejected++
	q.rejects = append(q.rejects, Rejection{Command: cmd, Reason: err})
}

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

ok  	gspractice/ch08/skill	0.293s