《互联网产品的服务端架构·规模化与架构演进》13.1 从 MVP 到规模化的路线图

// file: internal/scalebase/roadmap.go
// tier: L1
// verify: go test ./internal/scalebase/

package scalebase

import (
	"fmt"
	"sort"
)

// Stage 是规模化路线图上的一个阶段。
// Order 决定先后顺序，Exit 列出离开该阶段必须同时满足的退出条件。
type Stage struct {
	Name  string
	Order int
	Exit  []string
}

// Validate 检查路线图的结构约束。
// 它只关心“路线图是否自洽”，不关心某个团队实际走到了哪一步：
// 顺序必须唯一且为正，阶段名必须唯一，每个阶段至少有一个退出条件。
func Validate(stages []Stage) error {
	if len(stages) == 0 {
		return fmt.Errorf("scalebase: roadmap is empty")
	}
	orders := make(map[int]string, len(stages))
	names := make(map[string]struct{}, len(stages))
	for i, s := range stages {
		if s.Name == "" {
			return fmt.Errorf("scalebase: stage at index %d has empty name", i)
		}
		if _, ok := names[s.Name]; ok {
			return fmt.Errorf("scalebase: duplicate stage name %q", s.Name)
		}
		names[s.Name] = struct{}{}
		if s.Order <= 0 {
			return fmt.Errorf("scalebase: stage %q has non-positive order %d", s.Name, s.Order)
		}
		if other, ok := orders[s.Order]; ok {
			return fmt.Errorf("scalebase: stages %q and %q share order %d", other, s.Name, s.Order)
		}
		orders[s.Order] = s.Name
		if len(s.Exit) == 0 {
			return fmt.Errorf("scalebase: stage %q has no exit condition", s.Name)
		}
		for j, e := range s.Exit {
			if e == "" {
				return fmt.Errorf("scalebase: stage %q exit condition %d is empty", s.Name, j)
			}
		}
	}
	return nil
}

// Next 返回按 Order 排序后第一个尚未完成的阶段。
// done 以阶段名为键；传 nil 表示一个阶段都没完成。
// 所有阶段都完成时返回错误，因为“没有下一步”本身就是路线图走完的信号，
// 调用方不应该把它和“还没开始”混为一谈。
func Next(stages []Stage, done map[string]bool) (Stage, error) {
	if err := Validate(stages); err != nil {
		return Stage{}, err
	}
	ordered := make([]Stage, len(stages))
	copy(ordered, stages)
	sort.Slice(ordered, func(i, j int) bool { return ordered[i].Order < ordered[j].Order })
	for _, s := range ordered {
		if !done[s.Name] {
			return s, nil
		}
	}
	return Stage{}, fmt.Errorf("scalebase: all %d stages are done", len(ordered))
}

// file: internal/scalebase/roadmap_test.go
// tier: L1
// verify: go test ./internal/scalebase/

package scalebase

import "testing"

func sampleRoadmap() []Stage {
	return []Stage{
		{Name: "single-node", Order: 1, Exit: []string{"one deployable binary", "restore tested"}},
		{Name: "split-read", Order: 2, Exit: []string{"replica lag < 2s"}},
		{Name: "sharded", Order: 3, Exit: []string{"routing versioned", "rebalance rehearsed"}},
	}
}

func TestValidate(t *testing.T) {
	if err := Validate(sampleRoadmap()); err != nil {
		t.Fatalf("valid roadmap: %v", err)
	}
	if err := Validate(nil); err == nil {
		t.Fatal("want error for empty roadmap")
	}
	if err := Validate([]Stage{{Name: "a", Order: 1, Exit: []string{"x"}}, {Name: "b", Order: 1, Exit: []string{"y"}}}); err == nil {
		t.Fatal("want error for duplicate order")
	}
	if err := Validate([]Stage{{Name: "a", Order: 1, Exit: []string{"x"}}, {Name: "a", Order: 2, Exit: []string{"y"}}}); err == nil {
		t.Fatal("want error for duplicate name")
	}
	if err := Validate([]Stage{{Name: "a", Order: 0, Exit: []string{"x"}}}); err == nil {
		t.Fatal("want error for non-positive order")
	}
	if err := Validate([]Stage{{Name: "a", Order: 1}}); err == nil {
		t.Fatal("want error for stage without exit condition")
	}
	if err := Validate([]Stage{{Name: "a", Order: 1, Exit: []string{""}}}); err == nil {
		t.Fatal("want error for empty exit condition")
	}
	if err := Validate([]Stage{{Order: 1, Exit: []string{"x"}}}); err == nil {
		t.Fatal("want error for empty stage name")
	}
}

func TestNextFollowsOrder(t *testing.T) {
	stages := []Stage{
		{Name: "sharded", Order: 3, Exit: []string{"routing versioned"}},
		{Name: "single-node", Order: 1, Exit: []string{"restore tested"}},
		{Name: "split-read", Order: 2, Exit: []string{"replica lag < 2s"}},
	}
	got, err := Next(stages, nil)
	if err != nil {
		t.Fatalf("Next(nil done): %v", err)
	}
	if got.Name != "single-node" {
		t.Fatalf("first stage = %q, want single-node", got.Name)
	}
	got, err = Next(stages, map[string]bool{"single-node": true})
	if err != nil {
		t.Fatalf("Next(after single-node): %v", err)
	}
	if got.Name != "split-read" {
		t.Fatalf("second stage = %q, want split-read", got.Name)
	}
}

func TestNextAllDone(t *testing.T) {
	done := map[string]bool{"single-node": true, "split-read": true, "sharded": true}
	if _, err := Next(sampleRoadmap(), done); err == nil {
		t.Fatal("want error when every stage is done")
	}
}

func TestNextRejectsInvalidRoadmap(t *testing.T) {
	if _, err := Next(nil, nil); err == nil {
		t.Fatal("want error for empty roadmap")
	}
	if _, err := Next([]Stage{{Name: "a", Order: 1}}, nil); err == nil {
		t.Fatal("want error for stage without exit condition")
	}
}

cd .local/checks/webapp-lab && go test ./internal/scalebase/ -run 'TestValidate|TestNext' -count=1 -v

=== RUN   TestValidate
--- PASS: TestValidate (0.00s)
=== RUN   TestNextFollowsOrder
--- PASS: TestNextFollowsOrder (0.00s)
=== RUN   TestNextAllDone
--- PASS: TestNextAllDone (0.00s)
=== RUN   TestNextRejectsInvalidRoadmap
--- PASS: TestNextRejectsInvalidRoadmap (0.00s)
PASS
ok  	webapp/internal/scalebase	0.230s