《游戏服务端架构·平台化与架构治理》10.2 单体到平台、单游戏到多游戏

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

import (
	"errors"
	"fmt"
	"sort"
)

// Decision is the outcome of one capability review.
type Decision string

const (
	// DecisionExtract moves the capability into the shared platform.
	DecisionExtract Decision = "extract"
	// DecisionKeep leaves the capability inside the game boundary.
	DecisionKeep Decision = "keep"
	// DecisionDefer waits for a prerequisite before deciding again.
	DecisionDefer Decision = "defer"
)

var (
	ErrInvalidCapability = errors.New("platformevolution: invalid capability")
	ErrInvalidTenant     = errors.New("platformevolution: invalid tenant")
	ErrDependencyCycle   = errors.New("platformevolution: dependency cycle")
	ErrUnknownDependency = errors.New("platformevolution: unknown dependency")
	ErrDuplicateItem     = errors.New("platformevolution: duplicate item")
)

// Capability is the input to an extract-or-keep review. Counts are ordinal
// judgements from the review, not measurements.
type Capability struct {
	Name             string
	Games            int
	GameSpecificData bool
	Dependencies     int
	ReleaseFrequency int
	Criticality      int
}

func (c Capability) Validate() error {
	switch {
	case c.Name == "":
		return fmt.Errorf("%w: empty name", ErrInvalidCapability)
	case c.Games < 1:
		return fmt.Errorf("%w: %s games=%d", ErrInvalidCapability, c.Name, c.Games)
	case c.Dependencies < 0:
		return fmt.Errorf("%w: %s dependencies=%d", ErrInvalidCapability, c.Name, c.Dependencies)
	case c.ReleaseFrequency < 0:
		return fmt.Errorf("%w: %s release frequency=%d", ErrInvalidCapability, c.Name, c.ReleaseFrequency)
	case c.Criticality < 1 || c.Criticality > 5:
		return fmt.Errorf("%w: %s criticality=%d", ErrInvalidCapability, c.Name, c.Criticality)
	}
	return nil
}

// Recommend applies the review order explicitly: data ownership first, then
// consumer count, then coupling, then lifecycle pressure. The first matching
// rule wins, so the reason string always names the deciding rule.
func Recommend(c Capability) (Decision, string, error) {
	if err := c.Validate(); err != nil {
		return "", "", err
	}
	switch {
	case c.GameSpecificData:
		return DecisionKeep, "玩法数据与单款游戏强绑定，抽出会把游戏规则带进平台", nil
	case c.Games < 2:
		return DecisionDefer, "只有一个消费方，平台化收益无法覆盖协调成本", nil
	case c.Dependencies >= 4:
		return DecisionDefer, "下游依赖过多，先降低耦合再抽", nil
	case c.ReleaseFrequency >= 4 || c.Criticality >= 4:
		return DecisionExtract, "多游戏共用且生命周期压力大，独立发布收益最高", nil
	default:
		return DecisionKeep, "共用收益有限，留在游戏内更便宜", nil
	}
}

// Isolation is the tenant separation level for a shared capability.
type Isolation string

const (
	IsolationSharedDB         Isolation = "shared_database"
	IsolationSharedSchema     Isolation = "shared_schema"
	IsolationSchemaPerTenant  Isolation = "schema_per_tenant"
	IsolationDedicatedCluster Isolation = "dedicated_cluster"
)

// Tenant describes the consumers of one platform capability. Thresholds in
// ChooseIsolation are example design targets and must be re-tuned per studio.
type Tenant struct {
	Name              string
	Games             int
	PeakQPS           int
	Regulated         bool
	DataResidency     bool
	NoisyNeighborRisk int
}

func (t Tenant) Validate() error {
	switch {
	case t.Name == "":
		return fmt.Errorf("%w: empty name", ErrInvalidTenant)
	case t.Games < 1:
		return fmt.Errorf("%w: %s games=%d", ErrInvalidTenant, t.Name, t.Games)
	case t.PeakQPS < 0:
		return fmt.Errorf("%w: %s peak qps=%d", ErrInvalidTenant, t.Name, t.PeakQPS)
	case t.NoisyNeighborRisk < 1 || t.NoisyNeighborRisk > 5:
		return fmt.Errorf("%w: %s noisy neighbor risk=%d", ErrInvalidTenant, t.Name, t.NoisyNeighborRisk)
	}
	return nil
}

// ChooseIsolation escalates isolation only when a hard requirement or a
// measured risk justifies the extra operating cost.
func ChooseIsolation(t Tenant) (Isolation, error) {
	if err := t.Validate(); err != nil {
		return "", err
	}
	switch {
	case t.Regulated || t.DataResidency:
		return IsolationDedicatedCluster, nil
	case t.NoisyNeighborRisk >= 4 || t.PeakQPS >= 20000:
		return IsolationSchemaPerTenant, nil
	case t.Games >= 3:
		return IsolationSharedSchema, nil
	default:
		return IsolationSharedDB, nil
	}
}

// Edge means From depends on To. Extraction must therefore handle To first.
type Edge struct {
	From string
	To   string
}

// ExtractionOrder returns a deterministic topological order with dependencies
// before dependents. It rejects cycles instead of guessing a safe order.
func ExtractionOrder(edges []Edge) ([]string, error) {
	nodes := make(map[string]bool)
	indegree := make(map[string]int)
	next := make(map[string][]string)
	seen := make(map[[2]string]bool)
	for _, e := range edges {
		if e.From == "" || e.To == "" {
			return nil, fmt.Errorf("%w: empty node", ErrUnknownDependency)
		}
		if e.From == e.To {
			return nil, fmt.Errorf("%w: self edge %s", ErrDependencyCycle, e.From)
		}
		key := [2]string{e.From, e.To}
		if seen[key] {
			continue
		}
		seen[key] = true
		nodes[e.From] = true
		nodes[e.To] = true
		next[e.To] = append(next[e.To], e.From)
		indegree[e.From]++
	}

	ready := make([]string, 0, len(nodes))
	for n := range nodes {
		if indegree[n] == 0 {
			ready = append(ready, n)
		}
	}
	sort.Strings(ready)

	order := make([]string, 0, len(nodes))
	for len(ready) > 0 {
		n := ready[0]
		ready = ready[1:]
		order = append(order, n)
		children := append([]string(nil), next[n]...)
		sort.Strings(children)
		for _, child := range children {
			indegree[child]--
			if indegree[child] == 0 {
				ready = append(ready, child)
				sort.Strings(ready)
			}
		}
	}
	if len(order) != len(nodes) {
		return nil, ErrDependencyCycle
	}
	return order, nil
}