《游戏服务端编程实践》21.4 AI 驱动的游戏逻辑与测试

// file: ch21/aitest/aitest.go
// tier: L1
// verify: go test ./ch21/aitest/

// Package aitest 演示 AI 生成配置进入服务端之前的最后一道门：先做 JSON
// 结构与未知字段校验，再做必填项、唯一性和数值范围校验。模型输出是输入，
// 不是已经被信任的配置。
package aitest

import (
	"bytes"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"math"
	"strings"
	"unicode/utf8"
)

const (
	MaxNPCs         = 200
	MaxDrops        = 500
	MaxVersionRunes = 64
	MaxNameRunes    = 32
	MaxLevel        = 100
	MaxHP           = 1_000_000
	MaxAttack       = 100_000
	MaxAggroRange   = 50
	MaxDropWeight   = 10_000
)

// Config 是 AI 生成的关卡配置子集。真实项目字段更多，但校验分层的原则相同：
// 结构由解码器负责，语义由 Validate 负责，二者都不能省。
type Config struct {
	Version string     `json:"version"`
	NPCs    []NPC      `json:"npcs"`
	Drops   []DropItem `json:"drops"`
}

type NPC struct {
	ID         string  `json:"id"`
	Name       string  `json:"name"`
	Level      int     `json:"level"`
	HP         int     `json:"hp"`
	Attack     int     `json:"attack"`
	AggroRange float64 `json:"aggro_range"`
}

type DropItem struct {
	ItemID string `json:"item_id"`
	Weight int    `json:"weight"`
}

// Issue 是一条可定位的校验结论。Field 使用 JSON 路径，方便直接回写给
// 生成器或展示在审核界面上，而不是只给一句 “配置不合法”。
type Issue struct {
	Field  string
	Reason string
}

func (i Issue) String() string {
	return i.Field + ": " + i.Reason
}

// Parse 解码并校验一份配置。JSON 解码失败时返回单个 $ 路径的问题；
// 解码成功后继续收集全部语义问题，避免审核者每修一处就重跑一次。
func Parse(data []byte) (Config, []Issue) {
	var cfg Config
	dec := json.NewDecoder(bytes.NewReader(data))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&cfg); err != nil {
		return Config{}, []Issue{{Field: "$", Reason: "invalid json: " + err.Error()}}
	}
	var trailing any
	if err := dec.Decode(&trailing); !errors.Is(err, io.EOF) {
		return cfg, []Issue{{Field: "$", Reason: "trailing data after config"}}
	}
	return cfg, mergeIssues(presenceIssues(data), Validate(cfg))
}

// presenceIssues 检查必填键是否真的出现。0 是合法的 attack 和 aggro_range，
// 也是 Go 的零值，所以仅靠 Validate 无法区分“没写”和“显式写 0”。
func presenceIssues(data []byte) []Issue {
	var raw struct {
		Version *json.RawMessage              `json:"version"`
		NPCs    *[]map[string]json.RawMessage `json:"npcs"`
		Drops   []map[string]json.RawMessage  `json:"drops"`
	}
	if err := json.Unmarshal(data, &raw); err != nil {
		return nil
	}

	var issues []Issue
	require := func(field string) {
		issues = append(issues, Issue{Field: field, Reason: "required"})
	}
	if raw.Version == nil {
		require("$.version")
	}
	if raw.NPCs == nil {
		require("$.npcs")
	} else {
		for i, npc := range *raw.NPCs {
			for _, key := range []string{"id", "name", "level", "hp", "attack", "aggro_range"} {
				if _, ok := npc[key]; !ok {
					require(fmt.Sprintf("$.npcs[%d].%s", i, key))
				}
			}
		}
	}
	for i, drop := range raw.Drops {
		for _, key := range []string{"item_id", "weight"} {
			if _, ok := drop[key]; !ok {
				require(fmt.Sprintf("$.drops[%d].%s", i, key))
			}
		}
	}
	return issues
}

// mergeIssues 让结构问题和语义问题共用同一个字段路径。一个字段只保留
// 第一条结论，避免“缺字段”同时被报成“超出范围”。
func mergeIssues(schema, semantic []Issue) []Issue {
	seen := make(map[string]bool, len(schema)+len(semantic))
	out := make([]Issue, 0, len(schema)+len(semantic))
	for _, issue := range append(schema, semantic...) {
		if seen[issue.Field] {
			continue
		}
		seen[issue.Field] = true
		out = append(out, issue)
	}
	return out
}

// Validate 只做纯函数校验，不读文件、不访问网络，因此可以直接被单元测试、
// CI 和发布前的审核接口复用。
func Validate(cfg Config) []Issue {
	var issues []Issue
	add := func(field, reason string) {
		issues = append(issues, Issue{Field: field, Reason: reason})
	}

	version := strings.TrimSpace(cfg.Version)
	if version == "" {
		add("$.version", "required")
	} else if utf8.RuneCountInString(version) > MaxVersionRunes {
		add("$.version", fmt.Sprintf("must be at most %d runes", MaxVersionRunes))
	}

	if len(cfg.NPCs) == 0 {
		add("$.npcs", "at least one npc required")
	} else if len(cfg.NPCs) > MaxNPCs {
		add("$.npcs", fmt.Sprintf("must contain at most %d npcs", MaxNPCs))
	}

	seenNPC := make(map[string]int, len(cfg.NPCs))
	for i, npc := range cfg.NPCs {
		path := fmt.Sprintf("$.npcs[%d]", i)
		id := strings.TrimSpace(npc.ID)
		if id == "" {
			add(path+".id", "required")
		} else if prev, ok := seenNPC[id]; ok {
			add(path+".id", fmt.Sprintf("duplicate of index %d", prev))
		} else {
			seenNPC[id] = i
		}

		name := strings.TrimSpace(npc.Name)
		if name == "" {
			add(path+".name", "required")
		} else if utf8.RuneCountInString(name) > MaxNameRunes {
			add(path+".name", fmt.Sprintf("must be at most %d runes", MaxNameRunes))
		}

		if npc.Level < 1 || npc.Level > MaxLevel {
			add(path+".level", fmt.Sprintf("must be between 1 and %d", MaxLevel))
		}
		if npc.HP < 1 || npc.HP > MaxHP {
			add(path+".hp", fmt.Sprintf("must be between 1 and %d", MaxHP))
		}
		if npc.Attack < 0 || npc.Attack > MaxAttack {
			add(path+".attack", fmt.Sprintf("must be between 0 and %d", MaxAttack))
		}
		if math.IsNaN(npc.AggroRange) || math.IsInf(npc.AggroRange, 0) ||
			npc.AggroRange < 0 || npc.AggroRange > MaxAggroRange {
			add(path+".aggro_range", fmt.Sprintf("must be between 0 and %d", MaxAggroRange))
		}
	}

	if len(cfg.Drops) > MaxDrops {
		add("$.drops", fmt.Sprintf("must contain at most %d drops", MaxDrops))
	}
	seenDrop := make(map[string]int, len(cfg.Drops))
	for i, drop := range cfg.Drops {
		path := fmt.Sprintf("$.drops[%d]", i)
		itemID := strings.TrimSpace(drop.ItemID)
		if itemID == "" {
			add(path+".item_id", "required")
		} else if prev, ok := seenDrop[itemID]; ok {
			add(path+".item_id", fmt.Sprintf("duplicate of index %d", prev))
		}
		if itemID != "" {
			seenDrop[itemID] = i
		}
		if drop.Weight < 1 || drop.Weight > MaxDropWeight {
			add(path+".weight", fmt.Sprintf("must be between 1 and %d", MaxDropWeight))
		}
	}

	return issues
}

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

ok  	gspractice/ch21/aitest	0.405s