《游戏服务端编程实践》19.2 模块职责说明

// file: ch19/module/module.go
// tier: L1
// verify: go test ./ch19/module/

package module

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

var (
	ErrDuplicateModule   = errors.New("module: duplicate module")
	ErrUnknownDependency = errors.New("module: unknown dependency")
	ErrCycle             = errors.New("module: dependency cycle")
)

// Module 是一个可启动、可关闭的进程内模块。Name 在注册表内唯一，
// DependsOn 返回的是“必须先于本模块完成 Start”的模块名。
type Module interface {
	Name() string
	DependsOn() []string
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

// Readier 是可选接口。启动完成不等于可以接流量，预热、建连、加载配置
// 都可能失败，注册表在全部 Start 成功后统一调用 Ready。
type Readier interface {
	Ready(ctx context.Context) error
}

// Registry 负责注册、依赖排序和生命周期编排。它不关心模块内部做什么，
// 只保证依赖先启动、后关闭。
type Registry struct {
	mu      sync.Mutex
	modules map[string]Module
	started []string
	stopped bool
}

func NewRegistry() *Registry {
	return &Registry{modules: make(map[string]Module)}
}

func (r *Registry) Register(m Module) error {
	if m == nil {
		return errors.New("module: nil module")
	}
	name := strings.TrimSpace(m.Name())
	if name == "" {
		return errors.New("module: empty module name")
	}
	r.mu.Lock()
	defer r.mu.Unlock()
	if _, ok := r.modules[name]; ok {
		return fmt.Errorf("%w: %s", ErrDuplicateModule, name)
	}
	r.modules[name] = m
	return nil
}

// Plan 返回依赖优先的初始化顺序。它可以被单独调用，用于启动前检查配置。
func (r *Registry) Plan() ([]string, error) {
	r.mu.Lock()
	defer r.mu.Unlock()
	return r.planLocked()
}

func (r *Registry) planLocked() ([]string, error) {
	indegree := make(map[string]int, len(r.modules))
	dependents := make(map[string][]string, len(r.modules))
	for name, m := range r.modules {
		seen := make(map[string]bool, len(m.DependsOn()))
		for _, dep := range m.DependsOn() {
			if dep == name {
				return nil, fmt.Errorf("%w: %s depends on itself", ErrCycle, name)
			}
			if _, ok := r.modules[dep]; !ok {
				return nil, fmt.Errorf("%w: %s -> %s", ErrUnknownDependency, name, dep)
			}
			if seen[dep] {
				continue
			}
			seen[dep] = true
			indegree[name]++
			dependents[dep] = append(dependents[dep], name)
		}
	}

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

	order := make([]string, 0, len(r.modules))
	for len(ready) > 0 {
		name := ready[0]
		ready = ready[1:]
		order = append(order, name)
		next := append([]string(nil), dependents[name]...)
		sort.Strings(next)
		for _, dep := range next {
			indegree[dep]--
			if indegree[dep] == 0 {
				ready = append(ready, dep)
			}
		}
		sort.Strings(ready)
	}
	if len(order) != len(r.modules) {
		return nil, ErrCycle
	}
	return order, nil
}

// Start 按依赖顺序初始化全部模块。任一模块失败时，已经启动的模块会按
// 逆序关闭，避免留下半初始化的状态。
func (r *Registry) Start(ctx context.Context) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	if len(r.started) > 0 {
		return errors.New("module: already started")
	}
	order, err := r.planLocked()
	if err != nil {
		return err
	}
	for _, name := range order {
		if err := r.modules[name].Start(ctx); err != nil {
			rollbackErr := r.stopReverseLocked(ctx)
			return errors.Join(fmt.Errorf("module: start %s: %w", name, err), rollbackErr)
		}
		r.started = append(r.started, name)
	}
	r.stopped = false
	return nil
}

// Ready 按启动顺序调用实现了 Readier 的模块。返回错误说明进程可以
// 继续运行，但还不应该接入流量。
func (r *Registry) Ready(ctx context.Context) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	for _, name := range r.started {
		rd, ok := r.modules[name].(Readier)
		if !ok {
			continue
		}
		if err := rd.Ready(ctx); err != nil {
			return fmt.Errorf("module: ready %s: %w", name, err)
		}
	}
	return nil
}

// Stop 按启动顺序的逆序关闭。单个模块关闭失败不会中断后续关闭，
// 所有错误会合并返回。
func (r *Registry) Stop(ctx context.Context) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	if r.stopped {
		return nil
	}
	err := r.stopReverseLocked(ctx)
	r.stopped = true
	return err
}

func (r *Registry) stopReverseLocked(ctx context.Context) error {
	var errs []error
	for i := len(r.started) - 1; i >= 0; i-- {
		name := r.started[i]
		if err := r.modules[name].Stop(ctx); err != nil {
			errs = append(errs, fmt.Errorf("module: stop %s: %w", name, err))
		}
	}
	r.started = nil
	return errors.Join(errs...)
}

// Started 返回当前已成功启动的模块名，按启动顺序排列。
func (r *Registry) Started() []string {
	r.mu.Lock()
	defer r.mu.Unlock()
	return append([]string(nil), r.started...)
}

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

ok  	gspractice/ch19/module	0.732s