《游戏服务端架构·品类、状态与拓扑》8.1 全球同服的大地图与分片

玩家视角
  ┌──────────────────────────────────────────┐
  │              一张 4096×4096 大地图        │
  │   ┌─────────┬─────────┬─────────┐        │
  │   │ cn-west │ cn-east │ cn-south│  ...   │
  │   └─────────┴─────────┴─────────┘        │
  └──────────────────────────────────────────┘
服务端视角
  region=cn  ->  [cn-west: x∈[0,2047], y∈[0,2047]]
                 [cn-east: x∈[2048,4095], y∈[0,2047]]
  region=eu  ->  [eu-core: x∈[0,4095], y∈[0,4095]]

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

import (
	"errors"
	"fmt"
)

type Region string

const (
	RegionCN Region = "cn"
	RegionEU Region = "eu"
	RegionNA Region = "na"
)

var (
	ErrEmptyID     = errors.New("worldmap: empty shard id")
	ErrDuplicateID = errors.New("worldmap: duplicate shard id")
	ErrBadBounds   = errors.New("worldmap: min must not exceed max")
	ErrOverlap     = errors.New("worldmap: shards overlap in one region")
	ErrOutsideMap  = errors.New("worldmap: point outside every shard")
	ErrNotOwner    = errors.New("worldmap: shard does not own the origin")
	ErrWrongShard  = errors.New("worldmap: message delivered to the wrong shard")
	ErrStaleEpoch  = errors.New("worldmap: ownership epoch does not match")
	ErrOutOfOrder  = errors.New("worldmap: sequence already applied")
)

// Point is an inclusive map cell. Coordinates never cross a region boundary.
type Point struct{ X, Y int }

// Bounds is an inclusive rectangle; both corners belong to the shard.
type Bounds struct{ Min, Max Point }

func (b Bounds) Contains(p Point) bool {
	return p.X >= b.Min.X && p.X <= b.Max.X && p.Y >= b.Min.Y && p.Y <= b.Max.Y
}

func (b Bounds) Valid() bool {
	return b.Min.X <= b.Max.X && b.Min.Y <= b.Max.Y
}

// Shard owns a rectangle inside one region. A cell has at most one owner.
type Shard struct {
	ID     string
	Region Region
	Bounds Bounds
}

type Router struct {
	byRegion map[Region][]Shard
}

// NewRouter validates the layout once and answers ownership without fallback.
// It deliberately has no "global default shard": an unmapped cell is an error,
// not a reason to route into another region.
func NewRouter(layout []Shard) (*Router, error) {
	ids := make(map[string]bool, len(layout))
	for _, s := range layout {
		if s.ID == "" {
			return nil, ErrEmptyID
		}
		if ids[s.ID] {
			return nil, fmt.Errorf("%w: %s", ErrDuplicateID, s.ID)
		}
		ids[s.ID] = true
		if !s.Bounds.Valid() {
			return nil, fmt.Errorf("%w: %s", ErrBadBounds, s.ID)
		}
	}
	for i := range layout {
		for j := i + 1; j < len(layout); j++ {
			a, b := layout[i], layout[j]
			if a.Region != b.Region {
				continue
			}
			if a.Bounds.Min.X <= b.Bounds.Max.X && b.Bounds.Min.X <= a.Bounds.Max.X &&
				a.Bounds.Min.Y <= b.Bounds.Max.Y && b.Bounds.Min.Y <= a.Bounds.Max.Y {
				return nil, fmt.Errorf("%w: %s and %s", ErrOverlap, a.ID, b.ID)
			}
		}
	}
	r := &Router{byRegion: make(map[Region][]Shard)}
	for _, s := range layout {
		r.byRegion[s.Region] = append(r.byRegion[s.Region], s)
	}
	return r, nil
}

// Owner returns the single shard that owns the cell in this region.
func (r *Router) Owner(region Region, p Point) (Shard, bool) {
	for _, s := range r.byRegion[region] {
		if s.Bounds.Contains(p) {
			return s, true
		}
	}
	return Shard{}, false
}

// Handoff is the command that transfers one entity between shards. Epoch is
// the destination ownership epoch; the receiver rejects older epochs so a
// delayed message cannot resurrect a previous owner.
type Handoff struct {
	Entity string
	From   string
	To     string
	Seq    uint64
	Epoch  uint64
}

// PlanMove validates authority before producing a handoff. Moving inside one
// shard returns ok=false and no message, which keeps the common path cheap.
func (r *Router) PlanMove(region Region, entity, fromShard string,
	from, to Point, seq, epoch uint64) (Handoff, bool, error) {
	if entity == "" || fromShard == "" {
		return Handoff{}, false, ErrEmptyID
	}
	origin, ok := r.Owner(region, from)
	if !ok {
		return Handoff{}, false, fmt.Errorf("%w: origin (%d,%d)", ErrOutsideMap, from.X, from.Y)
	}
	if origin.ID != fromShard {
		return Handoff{}, false, fmt.Errorf("%w: %s claims (%d,%d) owned by %s",
			ErrNotOwner, fromShard, from.X, from.Y, origin.ID)
	}
	dest, ok := r.Owner(region, to)
	if !ok {
		return Handoff{}, false, fmt.Errorf("%w: target (%d,%d)", ErrOutsideMap, to.X, to.Y)
	}
	if dest.ID == origin.ID {
		return Handoff{}, false, nil
	}
	return Handoff{
		Entity: entity,
		From:   origin.ID,
		To:     dest.ID,
		Seq:    seq,
		Epoch:  epoch,
	}, true, nil
}

// Message is one cross-shard command delivered to a destination shard.
type Message struct {
	Entity string
	From   string
	To     string
	Seq    uint64
	Epoch  uint64
}

// Inbox applies cross-shard messages in order. It is intentionally not a
// reordering buffer: out-of-order and duplicate messages are rejected, and the
// sender is expected to replay from its last acknowledged sequence.
type Inbox struct {
	shard   string
	epoch   uint64
	applied map[string]uint64
}

func NewInbox(shard string, epoch uint64) *Inbox {
	return &Inbox{shard: shard, epoch: epoch, applied: make(map[string]uint64)}
}

func (in *Inbox) Accept(m Message) error {
	if m.To != in.shard {
		return fmt.Errorf("%w: got %q want %q", ErrWrongShard, m.To, in.shard)
	}
	if m.Epoch != in.epoch {
		return fmt.Errorf("%w: got %d want %d", ErrStaleEpoch, m.Epoch, in.epoch)
	}
	if last, ok := in.applied[m.Entity]; ok && m.Seq <= last {
		return fmt.Errorf("%w: entity %s seq %d <= %d", ErrOutOfOrder, m.Entity, m.Seq, last)
	}
	in.applied[m.Entity] = m.Seq
	return nil
}

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

源分片 A                         目标分片 B
   │                                  │
   │ 1. 标记实体冻结，停止接受新命令   │
   │ 2. 写入 handoff(entity,seq,epoch) │
   │────────────── 消息 ─────────────>│
   │                                  │ 3. 校验 epoch，应用实体
   │<────────────── ack ──────────────│
   │ 4. 收到 ack 后删除本地副本         │
   │ 5. 客户端重新拉取路由              │