《游戏服务端编程实践》7.1.2 地图加载与分片机制

// file: ch07/world/loader.go
// tier: L1
// verify: go test ./ch07/world/

package world

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

var (
	ErrMapNotFound      = errors.New("world: map data not found")
	ErrMapVersion       = errors.New("world: map version mismatch")
	ErrMapKeyMismatch   = errors.New("world: loader returned data for another key")
	ErrMapBusy          = errors.New("world: map is still referenced")
	ErrMapReleaseUnheld = errors.New("world: release without acquire")
)

// MapKey 唯一标识一个可加载单元：地图 ID + 实例 ID + 分区。
// 副本用 InstanceID 区分，同一张地图的不同实例绝不共享动态状态。
type MapKey struct {
	MapID      string
	InstanceID uint32
	Zone       ZoneID
}

func (k MapKey) String() string {
	return fmt.Sprintf("%s/%d/%s", k.MapID, k.InstanceID, k.Zone)
}

// MapData 是加载后的只读地图数据。加载完成后调用方不得原地修改，
// 需要修改时必须走版本化重建，而不是在共享数据上加锁。
type MapData struct {
	Key     MapKey
	Version uint32
	Blocks  [][2]WorldCoord // 阻挡矩形：左下角、右上角
	Spawns  []WorldCoord
}

// MapLoader 抽象存储：可以是本地文件、对象存储或版本化配置中心。
type MapLoader interface {
	Load(key MapKey) (MapData, error)
}

type mapEntry struct {
	data MapData
	refs int
}

type inflightLoad struct {
	done chan struct{}
	err  error
}

// MapStore 按 key 懒加载地图数据，并用引用计数决定何时卸载。
// 同一个 key 的并发加载只会真正执行一次。
type MapStore struct {
	mu       sync.Mutex
	loader   MapLoader
	entries  map[MapKey]*mapEntry
	inflight map[MapKey]*inflightLoad
	required map[string]uint32
	loads    int
}

func NewMapStore(loader MapLoader) *MapStore {
	return &MapStore{
		loader:   loader,
		entries:  make(map[MapKey]*mapEntry),
		inflight: make(map[MapKey]*inflightLoad),
		required: make(map[string]uint32),
	}
}

// RequireVersion 声明某张地图当前必须使用的数据版本。加载到不一致的
// 数据时直接失败，避免新旧阻挡规则混用。
func (s *MapStore) RequireVersion(mapID string, version uint32) {
	s.mu.Lock()
	s.required[mapID] = version
	s.mu.Unlock()
}

// Acquire 取得地图数据并增加一次引用。调用方用完必须 Release。
func (s *MapStore) Acquire(key MapKey) (MapData, error) {
	s.mu.Lock()
	if e, ok := s.entries[key]; ok {
		e.refs++
		data := e.data
		s.mu.Unlock()
		return data, nil
	}
	if f, ok := s.inflight[key]; ok {
		s.mu.Unlock()
		<-f.done
		if f.err != nil {
			return MapData{}, f.err
		}
		s.mu.Lock()
		e, ok := s.entries[key]
		if !ok {
			s.mu.Unlock()
			// 极端情况：加载完成后、本协程拿到锁之前，最后一个引用已释放。
			return s.Acquire(key)
		}
		e.refs++
		data := e.data
		s.mu.Unlock()
		return data, nil
	}

	f := &inflightLoad{done: make(chan struct{})}
	s.inflight[key] = f
	s.mu.Unlock()

	data, loadErr := s.loader.Load(key)

	s.mu.Lock()
	s.loads++
	err := loadErr
	if err == nil {
		err = s.checkLocked(key, data)
	}
	delete(s.inflight, key)
	f.err = err
	if err == nil {
		s.entries[key] = &mapEntry{data: data, refs: 1}
	}
	close(f.done)
	s.mu.Unlock()

	if err != nil {
		return MapData{}, err
	}
	return data, nil
}

func (s *MapStore) checkLocked(key MapKey, data MapData) error {
	if data.Key != key {
		return fmt.Errorf("%w: got %s, want %s", ErrMapKeyMismatch, data.Key, key)
	}
	if want, ok := s.required[key.MapID]; ok && data.Version != want {
		return fmt.Errorf("%w: got %d, want %d", ErrMapVersion, data.Version, want)
	}
	return nil
}

// Release 减少一次引用；归零时立刻从内存卸载，下次访问重新加载。
func (s *MapStore) Release(key MapKey) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	e, ok := s.entries[key]
	if !ok {
		return fmt.Errorf("%w: %s", ErrMapReleaseUnheld, key)
	}
	if e.refs <= 1 {
		delete(s.entries, key)
		return nil
	}
	e.refs--
	return nil
}

// Invalidate 让下一次 Acquire 重新加载。仍有引用时拒绝执行，
// 否则正在使用地图的玩家会拿到半新半旧的数据。
func (s *MapStore) Invalidate(key MapKey) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if e, ok := s.entries[key]; ok {
		if e.refs > 0 {
			return fmt.Errorf("%w: %s refs=%d", ErrMapBusy, key, e.refs)
		}
		delete(s.entries, key)
	}
	return nil
}

// Stats 返回当前已加载的 key 数量与累计实际加载次数，供监控和测试使用。
func (s *MapStore) Stats() (loaded, loads int) {
	s.mu.Lock()
	defer s.mu.Unlock()
	return len(s.entries), s.loads
}

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

ok  	gspractice/ch07/world	0.266s