《游戏服务端架构·品类、状态与拓扑》12.1 C4、部署视图与数据流

玩家 ──登录/支付──> northstar-platform ──推送──> 推送网关
                          │
                          ├──匹配──> 匹配服务
                          ├──结算──> 支付渠道
                          └──登录──> 账号中心

region: ap-east
┌─ node-a ──────────────┐   ┌─ node-b ──────────────┐
│ gateway x 4           │   │ room x 32             │
│ lobby x 2             │   │ battle-log x 2        │
└───────────────────────┘   └───────────────────────┘

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

import (
	"fmt"
	"strings"
)

// Kind is one of the five views the team keeps current.
type Kind string

const (
	Context    Kind = "context"
	Container  Kind = "container"
	Component  Kind = "component"
	Deployment Kind = "deployment"
	DataFlow   Kind = "dataflow"
)

var kinds = map[Kind]bool{
	Context:    true,
	Container:  true,
	Component:  true,
	Deployment: true,
	DataFlow:   true,
}

// Profile records who reads a view and when it must be refreshed.
type Profile struct {
	Readers string
	Cadence string
}

// Profiles is code, not wiki text: an unowned view goes stale by default.
var Profiles = map[Kind]Profile{
	Context:    {"制作人、新同事", "产品边界变化时"},
	Container:  {"服务端与平台工程师", "部署单元变化时"},
	Component:  {"模块负责人", "模块职责变化时"},
	Deployment: {"SRE、值班", "每次发布或扩缩容变更"},
	DataFlow:   {"数据、合规、后端", "数据模型或保留策略变化时"},
}

// Element is a box in exactly one view.
type Element struct {
	ID     string
	Name   string
	Type   string // person, system, container, component, store, topic, node
	Anchor string // repository path or config key that proves it exists
	Parent string // component only: the container ID that owns it
}

// Link is a directed relationship between two elements in the same view.
type Link struct {
	From  string
	To    string
	Label string
}

// View is one diagram plus the metadata needed to check it.
type View struct {
	Kind     Kind
	Elements []Element
	Links    []Link
}

// AnchorIndex is the set of paths and keys the repository actually contains.
type AnchorIndex map[string]bool

// Validate checks one view in isolation: identity, anchors, and endpoints.
func Validate(v View) []error {
	var errs []error
	if !kinds[v.Kind] {
		errs = append(errs, fmt.Errorf("unknown view kind %q", v.Kind))
	}
	seen := make(map[string]bool, len(v.Elements))
	for i, e := range v.Elements {
		if strings.TrimSpace(e.ID) == "" {
			errs = append(errs, fmt.Errorf("%s element %d: empty id", v.Kind, i))
			continue
		}
		if seen[e.ID] {
			errs = append(errs, fmt.Errorf("%s: duplicate element id %q", v.Kind, e.ID))
		}
		seen[e.ID] = true
		for _, f := range []struct{ name, value string }{
			{"name", e.Name}, {"type", e.Type}, {"anchor", e.Anchor},
		} {
			if strings.TrimSpace(f.value) == "" {
				errs = append(errs, fmt.Errorf("%s element %q: empty %s", v.Kind, e.ID, f.name))
			}
		}
		if v.Kind == Component && strings.TrimSpace(e.Parent) == "" {
			errs = append(errs, fmt.Errorf("component %q: missing parent container", e.ID))
		}
		if v.Kind != Component && e.Parent != "" {
			errs = append(errs, fmt.Errorf("%s element %q: parent only valid in component view", v.Kind, e.ID))
		}
	}
	for _, l := range v.Links {
		if !seen[l.From] || !seen[l.To] {
			errs = append(errs, fmt.Errorf("%s link %q->%q: unknown endpoint", v.Kind, l.From, l.To))
		}
		if l.From == l.To {
			errs = append(errs, fmt.Errorf("%s link %q: self reference", v.Kind, l.From))
		}
		if strings.TrimSpace(l.Label) == "" {
			errs = append(errs, fmt.Errorf("%s link %q->%q: empty label", v.Kind, l.From, l.To))
		}
	}
	return errs
}

// CheckAnchors rejects elements whose anchor is absent from the repository.
func CheckAnchors(v View, idx AnchorIndex) []error {
	var errs []error
	for _, e := range v.Elements {
		if strings.TrimSpace(e.Anchor) == "" {
			continue // already reported by Validate
		}
		if !idx[e.Anchor] {
			errs = append(errs, fmt.Errorf("%s element %q: anchor %q not found", v.Kind, e.ID, e.Anchor))
		}
	}
	return errs
}

// CrossCheck enforces the rules that only make sense across views:
// consistent identity, hosted containers, known parents, and stores that
// exist in the container view.
func CrossCheck(all []View) []error {
	var errs []error
	byID := make(map[string]Element)
	viewOf := make(map[string]Kind)
	containers := make(map[string]bool)
	containerViewIDs := make(map[string]bool)
	hosted := make(map[string]bool)
	var components []Element
	var stores []Element

	for _, v := range all {
		for _, e := range v.Elements {
			if prev, ok := byID[e.ID]; ok {
				if prev.Name != e.Name || prev.Type != e.Type {
					errs = append(errs, fmt.Errorf("element %q differs between %s and %s", e.ID, viewOf[e.ID], v.Kind))
				}
				if prev.Anchor != e.Anchor && v.Kind != Deployment && viewOf[e.ID] != Deployment {
					errs = append(errs, fmt.Errorf("element %q: anchor %q vs %q", e.ID, prev.Anchor, e.Anchor))
				}
			} else {
				byID[e.ID] = e
				viewOf[e.ID] = v.Kind
			}
			switch v.Kind {
			case Container:
				containerViewIDs[e.ID] = true
				if e.Type == "container" {
					containers[e.ID] = true
				}
			case Component:
				components = append(components, e)
			case DataFlow:
				stores = append(stores, e)
			}
		}
		for _, l := range v.Links {
			if v.Kind == Deployment && l.Label == "hosts" {
				hosted[l.To] = true
			}
		}
	}

	for _, c := range components {
		if !containers[c.Parent] {
			errs = append(errs, fmt.Errorf("component %q: parent %q is not a container", c.ID, c.Parent))
		}
	}
	for _, s := range stores {
		if !containerViewIDs[s.ID] {
			errs = append(errs, fmt.Errorf("dataflow store %q: missing from container view", s.ID))
		}
	}
	for id := range containers {
		if !hosted[id] {
			errs = append(errs, fmt.Errorf("container %q: no deployment element hosts it", id))
		}
	}
	return errs
}

$ cd .local/checks/gsarch-lab
$ go test -count=1 ./internal/views/
ok  	gsarchlab/internal/views	0.275s