《游戏服务端编程实践》11.1 架构拆分与职责边界

// file: ch11/boundary/boundary.go
// tier: L1
// verify: go test ./ch11/boundary/

package boundary

import (
	"errors"
	"fmt"
	"sort"
	"strings"
	"sync"
)

var (
	ErrEmptyService      = errors.New("boundary: empty service name")
	ErrDuplicateService  = errors.New("boundary: duplicate service")
	ErrUnknownService    = errors.New("boundary: unknown service")
	ErrSelfDependency    = errors.New("boundary: service depends on itself")
	ErrUnknownDependency = errors.New("boundary: unknown dependency")
	ErrCycle             = errors.New("boundary: dependency cycle")
	ErrEmptyResource     = errors.New("boundary: empty resource")
	ErrResourceConflict  = errors.New("boundary: resource already owned")
	ErrUnknownResource   = errors.New("boundary: unknown resource")
	ErrNotOwner          = errors.New("boundary: service does not own resource")
	ErrNoReadGrant       = errors.New("boundary: no read grant for resource")
)

// ResourceKind 区分表与主题，两者的所有权规则相同，但冲突时的排查路径不同。
type ResourceKind string

const (
	KindTable ResourceKind = "table"
	KindTopic ResourceKind = "topic"
)

type AccessMode int

const (
	Read AccessMode = iota
	Write
)

// Service 声明自己依赖谁、拥有哪些资源。拥有意味着只有它能写这份数据。
type Service struct {
	Name      string
	DependsOn []string
	Owns      map[string]ResourceKind
}

type node struct {
	dependsOn []string
	owned     []string
}

// Graph 保存服务依赖与资源归属，注册阶段就拒绝重复归属。
type Graph struct {
	mu       sync.RWMutex
	nodes    map[string]*node
	owners   map[string]string
	resource map[string]ResourceKind
}

func NewGraph() *Graph {
	return &Graph{
		nodes:    make(map[string]*node),
		owners:   make(map[string]string),
		resource: make(map[string]ResourceKind),
	}
}

// Register 注册服务，任何资源只能有一个所有者。
func (g *Graph) Register(s Service) error {
	name := strings.TrimSpace(s.Name)
	if name == "" {
		return ErrEmptyService
	}
	owned := make([]string, 0, len(s.Owns))
	for res, kind := range s.Owns {
		if strings.TrimSpace(res) == "" {
			return ErrEmptyResource
		}
		if kind != KindTable && kind != KindTopic {
			return fmt.Errorf("boundary: invalid resource kind %q", kind)
		}
		owned = append(owned, res)
	}
	sort.Strings(owned)
	deps := append([]string(nil), s.DependsOn...)
	sort.Strings(deps)

	g.mu.Lock()
	defer g.mu.Unlock()
	if _, ok := g.nodes[name]; ok {
		return fmt.Errorf("%w: %s", ErrDuplicateService, name)
	}
	for _, res := range owned {
		if owner, ok := g.owners[res]; ok {
			return fmt.Errorf("%w: %s owned by %s", ErrResourceConflict, res, owner)
		}
	}
	g.nodes[name] = &node{dependsOn: deps, owned: owned}
	for _, res := range owned {
		g.owners[res] = name
		g.resource[res] = s.Owns[res]
	}
	return nil
}

// Check 校验依赖存在且无环。环的报错会带上完整路径，便于定位拆分方案。
func (g *Graph) Check() error {
	g.mu.RLock()
	defer g.mu.RUnlock()

	names := make([]string, 0, len(g.nodes))
	for name := range g.nodes {
		names = append(names, name)
	}
	sort.Strings(names)

	for _, name := range names {
		for _, dep := range g.nodes[name].dependsOn {
			if dep == name {
				return fmt.Errorf("%w: %s", ErrSelfDependency, name)
			}
			if _, ok := g.nodes[dep]; !ok {
				return fmt.Errorf("%w: %s -> %s", ErrUnknownDependency, name, dep)
			}
		}
	}

	state := make(map[string]int, len(g.nodes))
	var stack []string
	var visit func(string) error
	visit = func(name string) error {
		switch state[name] {
		case 1:
			start := 0
			for i, n := range stack {
				if n == name {
					start = i
					break
				}
			}
			path := append(append([]string(nil), stack[start:]...), name)
			return fmt.Errorf("%w: %s", ErrCycle, strings.Join(path, " -> "))
		case 2:
			return nil
		}
		state[name] = 1
		stack = append(stack, name)
		for _, dep := range g.nodes[name].dependsOn {
			if err := visit(dep); err != nil {
				return err
			}
		}
		stack = stack[:len(stack)-1]
		state[name] = 2
		return nil
	}
	for _, name := range names {
		if state[name] == 0 {
			if err := visit(name); err != nil {
				return err
			}
		}
	}
	return nil
}

// Owner 返回资源的所有者，第二返回值为 false 表示资源未注册。
func (g *Graph) Owner(resource string) (string, bool) {
	g.mu.RLock()
	defer g.mu.RUnlock()
	owner, ok := g.owners[resource]
	return owner, ok
}

// OwnedBy 返回服务拥有的资源快照，调用方修改不会影响图内部状态。
func (g *Graph) OwnedBy(service string) []string {
	g.mu.RLock()
	defer g.mu.RUnlock()
	n, ok := g.nodes[service]
	if !ok {
		return nil
	}
	return append([]string(nil), n.owned...)
}

// CheckAccess 执行运行时边界检查：写只能由所有者执行，读需要显式依赖所有者。
func (g *Graph) CheckAccess(service, resource string, mode AccessMode) error {
	g.mu.RLock()
	defer g.mu.RUnlock()

	n, ok := g.nodes[service]
	if !ok {
		return fmt.Errorf("%w: %s", ErrUnknownService, service)
	}
	owner, ok := g.owners[resource]
	if !ok {
		return fmt.Errorf("%w: %s", ErrUnknownResource, resource)
	}
	if owner == service {
		return nil
	}
	if mode == Write {
		return fmt.Errorf("%w: %s cannot write %s owned by %s", ErrNotOwner, service, resource, owner)
	}
	for _, dep := range n.dependsOn {
		if dep == owner {
			return nil
		}
	}
	return fmt.Errorf("%w: %s cannot read %s owned by %s", ErrNoReadGrant, service, resource, owner)
}

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

ok  	gspractice/ch11/boundary	0.240s