《游戏服务端编程实践》6.1.1 Player 基础字段设计

CREATE TABLE `player` (
  `player_id`  BIGINT UNSIGNED NOT NULL,
  `account_id` BIGINT UNSIGNED NOT NULL,
  `region`     VARCHAR(32)  NOT NULL,
  `name`       VARCHAR(64)  NOT NULL,
  `avatar`     VARCHAR(255) NOT NULL DEFAULT '',
  `level`      INT UNSIGNED NOT NULL DEFAULT 1,
  `exp`        BIGINT       NOT NULL DEFAULT 0,
  `banned`     TINYINT(1)   NOT NULL DEFAULT 0,
  `created_at` DATETIME(3)  NOT NULL,
  `updated_at` DATETIME(3)  NOT NULL,
  `version`    BIGINT UNSIGNED NOT NULL DEFAULT 1,
  PRIMARY KEY (`player_id`),
  UNIQUE KEY `uk_region_name` (`region`, `name`),
  KEY `idx_account` (`account_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

// file: ch06/model/player.go
// tier: L1
// verify: go test ./ch06/model/

package model

import (
	"errors"
	"strings"
	"time"
	"unicode/utf8"
)

const (
	maxNameRunes = 32
	maxLevel     = 200
)

var (
	ErrInvalidPlayer   = errors.New("player: invalid field")
	ErrPlayerNotFound  = errors.New("player: not found")
	ErrVersionConflict = errors.New("player: version conflict")
)

// Player is persisted mutable state. Buffs, temporary coordinates and battle
// state are runtime-only and must not appear here.
type Player struct {
	PlayerID  uint64 // 区服内角色主键
	AccountID uint64 // 跨区稳定账号 ID
	Region    string

	Name   string
	Avatar string

	Level uint32
	Exp   int64

	Online bool // 仅路由提示，登录态以会话表为准
	Banned bool

	CreatedAt time.Time
	UpdatedAt time.Time
	Version   uint64 // 乐观锁令牌
}

func (p *Player) Validate() error {
	switch {
	case p.PlayerID == 0:
		return errors.Join(ErrInvalidPlayer, errors.New("player_id"))
	case p.AccountID == 0:
		return errors.Join(ErrInvalidPlayer, errors.New("account_id"))
	case strings.TrimSpace(p.Region) == "":
		return errors.Join(ErrInvalidPlayer, errors.New("region"))
	case strings.TrimSpace(p.Name) == "":
		return errors.Join(ErrInvalidPlayer, errors.New("name"))
	case utf8.RuneCountInString(p.Name) > maxNameRunes:
		return errors.Join(ErrInvalidPlayer, errors.New("name too long"))
	case p.Level == 0 || p.Level > maxLevel:
		return errors.Join(ErrInvalidPlayer, errors.New("level out of range"))
	case p.Exp < 0:
		return errors.Join(ErrInvalidPlayer, errors.New("negative exp"))
	case p.CreatedAt.IsZero() || p.UpdatedAt.IsZero():
		return errors.Join(ErrInvalidPlayer, errors.New("timestamps"))
	case p.UpdatedAt.Before(p.CreatedAt):
		return errors.Join(ErrInvalidPlayer, errors.New("updated_at before created_at"))
	}
	return nil
}

// PlayerStore stands in for a transactional repository.
type PlayerStore struct {
	players map[uint64]Player
	now     func() time.Time
}

func NewPlayerStore(now func() time.Time) *PlayerStore {
	if now == nil {
		now = time.Now
	}
	return &PlayerStore{players: make(map[uint64]Player), now: now}
}

// Create inserts a player and assigns version 1.
func (s *PlayerStore) Create(p Player) (Player, error) {
	if _, exists := s.players[p.PlayerID]; exists || p.Version != 0 {
		return Player{}, ErrVersionConflict
	}
	now := s.now().UTC()
	p.CreatedAt, p.UpdatedAt, p.Version = now, now, 1
	if err := p.Validate(); err != nil {
		return Player{}, err
	}
	s.players[p.PlayerID] = p
	return p, nil
}

// Save is compare-and-swap. Online comes from the session layer, so a save
// payload never overwrites it.
func (s *PlayerStore) Save(p Player, expectedVersion uint64) (Player, error) {
	current, ok := s.players[p.PlayerID]
	if !ok {
		return Player{}, ErrPlayerNotFound
	}
	if current.Version != expectedVersion {
		return Player{}, ErrVersionConflict
	}
	p.Online, p.CreatedAt = current.Online, current.CreatedAt
	p.UpdatedAt, p.Version = s.now().UTC(), current.Version+1
	if err := p.Validate(); err != nil {
		return Player{}, err
	}
	s.players[p.PlayerID] = p
	return p, nil
}

func (s *PlayerStore) Get(playerID uint64) (Player, error) {
	p, ok := s.players[playerID]
	if !ok {
		return Player{}, ErrPlayerNotFound
	}
	return p, nil
}

// file: ch06/model/player_test.go
// tier: L1
// verify: go test ./ch06/model/

package model

import (
	"errors"
	"testing"
	"time"
)

func testClock() time.Time { return time.Date(2026, 11, 4, 1, 0, 0, 0, time.UTC) }

func validPlayer() Player {
	return Player{PlayerID: 1001, AccountID: 77, Region: "s1", Name: "雾港旅人", Level: 12, Exp: 3400}
}

func TestPlayerValidateRejectsBadFields(t *testing.T) {
	tests := []struct {
		name   string
		mutate func(*Player)
	}{
		{"zero player id", func(p *Player) { p.PlayerID = 0 }},
		{"zero account id", func(p *Player) { p.AccountID = 0 }},
		{"blank region", func(p *Player) { p.Region = "  " }},
		{"blank name", func(p *Player) { p.Name = "" }},
		{"name too long", func(p *Player) { p.Name = string(make([]rune, 33)) }},
		{"zero level", func(p *Player) { p.Level = 0 }},
		{"negative exp", func(p *Player) { p.Exp = -1 }},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			p := validPlayer()
			tc.mutate(&p)
			if err := p.Validate(); !errors.Is(err, ErrInvalidPlayer) {
				t.Fatalf("Validate() = %v, want ErrInvalidPlayer", err)
			}
		})
	}
}

func TestPlayerStoreCreateAssignsVersionAndUTC(t *testing.T) {
	loc := time.FixedZone("UTC+8", 8*3600)
	store := NewPlayerStore(func() time.Time { return testClock().In(loc) })
	p, err := store.Create(validPlayer())
	if err != nil {
		t.Fatal(err)
	}
	if p.Version != 1 || p.CreatedAt.Location() != time.UTC {
		t.Fatalf("version=%d created_at=%v", p.Version, p.CreatedAt)
	}
	if _, err := store.Create(p); !errors.Is(err, ErrVersionConflict) {
		t.Fatalf("duplicate create error=%v", err)
	}
}

func TestPlayerStoreSaveRejectsStaleVersion(t *testing.T) {
	store := NewPlayerStore(testClock)
	created, err := store.Create(validPlayer())
	if err != nil {
		t.Fatal(err)
	}
	first := created
	first.Level = 13
	updated, err := store.Save(first, created.Version)
	if err != nil || updated.Version != 2 {
		t.Fatalf("update=%+v err=%v", updated, err)
	}
	stale := created
	stale.Level = 99
	if _, err := store.Save(stale, created.Version); !errors.Is(err, ErrVersionConflict) {
		t.Fatalf("stale save error=%v, want ErrVersionConflict", err)
	}
	got, _ := store.Get(created.PlayerID)
	if got.Level != 13 || got.Version != 2 {
		t.Fatalf("stale write leaked: %+v", got)
	}
}

func TestPlayerStoreDoesNotPersistOnlineFlag(t *testing.T) {
	store := NewPlayerStore(testClock)
	created, err := store.Create(validPlayer())
	if err != nil {
		t.Fatal(err)
	}
	created.Online = true
	created.Exp = 4000
	updated, err := store.Save(created, created.Version)
	if err != nil {
		t.Fatal(err)
	}
	if updated.Online || updated.Exp != 4000 {
		t.Fatalf("save result=%+v", updated)
	}
}

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

ok  	gspractice/ch06/model	0.259s