《游戏服务端架构·核心系统与契约》12.1 账号、支付、社交、数据平台的职责

// file: internal/platformcore/roster.go
// tier: L1
// verify: go test ./internal/platformcore/
package platformcore

import (
	"fmt"
	"sort"
)

// Roster is the platform capability registry. Registration is cheap; the
// graph is checked by Validate so teams can register in any order.
type Roster struct {
	caps map[string]Capability
}

func NewRoster() *Roster {
	return &Roster{caps: map[string]Capability{}}
}

// Register adds one capability. It rejects names that are empty, duplicated,
// layered outside the known range, or that describe gameplay rules.
func (r *Roster) Register(c Capability) error {
	if c.Name == "" {
		return ErrEmptyName
	}
	if c.Kind == KindGameplay {
		return ErrGameplay
	}
	if !knownKind(c.Kind) {
		return ErrBadKind
	}
	if c.Layer < LayerFoundation || c.Layer >= layerMax {
		return ErrBadLayer
	}
	if _, ok := r.caps[c.Name]; ok {
		return ErrDuplicate
	}
	r.caps[c.Name] = c
	return nil
}

// Validate returns every problem instead of the first one, because a broken
// dependency graph usually has several independent mistakes.
func (r *Roster) Validate() []Problem {
	var problems []Problem
	for _, name := range r.names() {
		c := r.caps[name]
		for _, dep := range c.Depends {
			target, ok := r.caps[dep]
			if !ok {
				problems = append(problems, Problem{name, "unknown-dependency", dep})
				continue
			}
			if target.Layer > c.Layer {
				problems = append(problems, Problem{name, "dependency-direction", dep})
			}
		}
	}
	if cycle := r.findCycle(); cycle != "" {
		problems = append(problems, Problem{cycle, "dependency-cycle", cycle})
	}
	return problems
}

// Remove deletes a capability only when nothing depends on it. The returned
// error names one blocker so the owner can migrate that caller first.
func (r *Roster) Remove(name string) error {
	if _, ok := r.caps[name]; !ok {
		return ErrUnknown
	}
	if deps := r.Dependents(name); len(deps) > 0 {
		return fmt.Errorf("%w: %s", ErrDependents, deps[0])
	}
	delete(r.caps, name)
	return nil
}

// Dependents lists capabilities that would break if name disappeared. It is
// the answer to "who do I have to call before shutting this down".
func (r *Roster) Dependents(name string) []string {
	var out []string
	for _, other := range r.names() {
		for _, dep := range r.caps[other].Depends {
			if dep == name {
				out = append(out, other)
				break
			}
		}
	}
	return out
}

func (r *Roster) names() []string {
	out := make([]string, 0, len(r.caps))
	for name := range r.caps {
		out = append(out, name)
	}
	sort.Strings(out)
	return out
}

// findCycle reports one capability on a dependency cycle, or the empty string.
// Depth-first colouring is enough because the graph is small and Validate is
// called during review, not per request.
func (r *Roster) findCycle() string {
	const (
		white = 0
		grey  = 1
		black = 2
	)
	color := map[string]int{}
	var visit func(string) string
	visit = func(name string) string {
		color[name] = grey
		for _, dep := range r.caps[name].Depends {
			if _, ok := r.caps[dep]; !ok {
				continue
			}
			switch color[dep] {
			case grey:
				return name
			case white:
				if found := visit(dep); found != "" {
					return found
				}
			}
		}
		color[name] = black
		return ""
	}
	for _, name := range r.names() {
		if color[name] == white {
			if found := visit(name); found != "" {
				return found
			}
		}
	}
	return ""
}

func knownKind(k Kind) bool {
	switch k {
	case KindAccount, KindPayment, KindSocial, KindData, KindConfig, KindNotice:
		return true
	}
	return false
}

// file: internal/platformcore/direction_test.go
// tier: L1
package platformcore

import (
	"errors"
	"testing"
)

func TestDependencyDirection(t *testing.T) {
	tests := []struct {
		name     string
		cap      Capability
		wantRule string
	}{
		{
			name:     "foundation may not depend on insight",
			cap:      Capability{Name: "config-v2", Kind: KindConfig, Layer: LayerFoundation, Depends: []string{"data"}},
			wantRule: "dependency-direction",
		},
		{
			name:     "same layer is allowed",
			cap:      Capability{Name: "notice", Kind: KindNotice, Layer: LayerEngagement, Depends: []string{"social"}},
			wantRule: "",
		},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			r := baseRoster(t)
			if err := r.Register(tc.cap); err != nil {
				t.Fatalf("Register: %v", err)
			}
			problems := r.Validate()
			if tc.wantRule == "" {
				if len(problems) != 0 {
					t.Fatalf("Validate() = %v, want none", problems)
				}
				return
			}
			for _, p := range problems {
				if p.Rule == tc.wantRule {
					return
				}
			}
			t.Fatalf("Validate() = %v, missing %q", problems, tc.wantRule)
		})
	}
}

func TestRemovalIsGuarded(t *testing.T) {
	tests := []struct {
		name   string
		target string
		want   error
	}{
		{"foundation still in use", "account", ErrDependents},
		{"leaf can be removed", "data", nil},
		{"unknown capability", "missing", ErrUnknown},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			r := baseRoster(t)
			if err := r.Remove(tc.target); !errors.Is(err, tc.want) {
				t.Fatalf("Remove(%s) = %v, want %v", tc.target, err, tc.want)
			}
		})
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/platformcore
$ go vet ./internal/platformcore/...
$ go test -count=1 ./internal/platformcore/...
ok  	gsarchlab/internal/platformcore