《互联网产品的服务端架构·规模化与架构演进》1.3 一次拆分的回退方案

// file: internal/split/rollback.go
// tier: L1
// verify: go test ./internal/split/

package split

import (
	"fmt"
	"strings"
)

// Stage 是拆分计划里的一个可回退步骤。
// Forward 是向前执行的动作，Back 是它对应的回退动作。
type Stage struct {
	Name    string
	Forward string
	Back    string
}

// ValidateStages 检查每个阶段都有名字、向前动作与回退动作，且名字唯一。
// 同一包里已经有 Validate([]Module)，Go 不支持函数重载，所以这里单独命名。
func ValidateStages(stages []Stage) error {
	seen := make(map[string]bool, len(stages))
	for i, st := range stages {
		name := strings.TrimSpace(st.Name)
		if name == "" {
			return fmt.Errorf("split: stage[%d] has empty name", i)
		}
		if seen[name] {
			return fmt.Errorf("split: duplicate stage %q", name)
		}
		seen[name] = true
		if strings.TrimSpace(st.Forward) == "" {
			return fmt.Errorf("split: stage %q has no forward action", name)
		}
		if strings.TrimSpace(st.Back) == "" {
			return fmt.Errorf("split: stage %q has no rollback action", name)
		}
	}
	return nil
}

// RollbackPath 返回失败点之前的回退步骤，按执行顺序倒序排列。
// failed 是第一个失败的阶段下标；该阶段自身的清理由它的局部逻辑负责，
// 不在返回结果里。failed 等于阶段总数表示全部阶段完成后才发现问题，
// 此时回退全部阶段；其余越界值或计划不完整时返回错误。
func RollbackPath(stages []Stage, failed int) ([]Stage, error) {
	if err := ValidateStages(stages); err != nil {
		return nil, err
	}
	if failed < 0 || failed > len(stages) {
		return nil, fmt.Errorf("split: failed index %d out of range [0,%d]", failed, len(stages))
	}

	path := make([]Stage, 0, failed)
	for i := failed - 1; i >= 0; i-- {
		path = append(path, stages[i])
	}
	return path, nil
}

// file: internal/split/rollback_test.go
// tier: L1
// verify: go test ./internal/split/

package split

import (
	"reflect"
	"strings"
	"testing"
)

func TestValidateStagesAcceptsCompletePlan(t *testing.T) {
	stages := []Stage{
		{Name: "read-shadow", Forward: "start shadow reads", Back: "stop shadow reads"},
		{Name: "dual-write", Forward: "write both stores", Back: "disable new writes"},
		{Name: "cutover", Forward: "route reads to split", Back: "route reads back"},
	}
	if err := ValidateStages(stages); err != nil {
		t.Fatalf("ValidateStages() = %v, want nil", err)
	}
}

func TestValidateStagesRejectsIncompletePlan(t *testing.T) {
	cases := []struct {
		name   string
		stages []Stage
		want   string
	}{
		{"empty-name", []Stage{{Forward: "f", Back: "b"}}, "empty name"},
		{"duplicate-name", []Stage{
			{Name: "s1", Forward: "f1", Back: "b1"},
			{Name: "s1", Forward: "f2", Back: "b2"},
		}, "duplicate stage"},
		{"missing-forward", []Stage{{Name: "s1", Back: "b1"}}, "no forward action"},
		{"missing-back", []Stage{{Name: "s1", Forward: "f1"}}, "no rollback action"},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			err := ValidateStages(c.stages)
			if err == nil {
				t.Fatal("ValidateStages() = nil, want error")
			}
			if !strings.Contains(err.Error(), c.want) {
				t.Fatalf("ValidateStages() = %q, want substring %q", err, c.want)
			}
		})
	}
}

func TestRollbackPathRunsCompletedStagesInReverse(t *testing.T) {
	stages := []Stage{
		{Name: "a", Forward: "fa", Back: "ba"},
		{Name: "b", Forward: "fb", Back: "bb"},
		{Name: "c", Forward: "fc", Back: "bc"},
	}

	got, err := RollbackPath(stages, 3)
	if err != nil {
		t.Fatal(err)
	}
	want := []Stage{stages[2], stages[1], stages[0]}
	if !reflect.DeepEqual(got, want) {
		t.Fatalf("RollbackPath(3) = %v, want %v", got, want)
	}
}

func TestRollbackPathCoversOnlyCompletedStages(t *testing.T) {
	stages := []Stage{
		{Name: "a", Forward: "fa", Back: "ba"},
		{Name: "b", Forward: "fb", Back: "bb"},
	}

	got, err := RollbackPath(stages, 1)
	if err != nil {
		t.Fatal(err)
	}
	if !reflect.DeepEqual(got, []Stage{stages[0]}) {
		t.Fatalf("RollbackPath(1) = %v, want only stage a", got)
	}

	empty, err := RollbackPath(stages, 0)
	if err != nil {
		t.Fatal(err)
	}
	if len(empty) != 0 {
		t.Fatalf("RollbackPath(0) = %v, want empty", empty)
	}
}

func TestRollbackPathRejectsBadIndexAndPlan(t *testing.T) {
	stages := []Stage{
		{Name: "a", Forward: "fa", Back: "ba"},
		{Name: "b", Forward: "fb", Back: "bb"},
	}
	for _, idx := range []int{-1, 3} {
		if _, err := RollbackPath(stages, idx); err == nil {
			t.Fatalf("RollbackPath(%d) = nil error, want out of range", idx)
		}
	}

	broken := []Stage{{Name: "a", Forward: "fa"}}
	if _, err := RollbackPath(broken, 1); err == nil {
		t.Fatal("RollbackPath on broken plan = nil error, want validation error")
	}
}

cd .local/checks/webapp-lab && go test ./internal/split/ -run '^(TestValidateStages.*|TestRollbackPath.*)$' -count=1 -v

=== RUN   TestValidateStagesAcceptsCompletePlan
--- PASS: TestValidateStagesAcceptsCompletePlan (0.00s)
=== RUN   TestValidateStagesRejectsIncompletePlan
=== RUN   TestValidateStagesRejectsIncompletePlan/empty-name
=== RUN   TestValidateStagesRejectsIncompletePlan/duplicate-name
=== RUN   TestValidateStagesRejectsIncompletePlan/missing-forward
=== RUN   TestValidateStagesRejectsIncompletePlan/missing-back
--- PASS: TestValidateStagesRejectsIncompletePlan (0.00s)
    --- PASS: TestValidateStagesRejectsIncompletePlan/empty-name (0.00s)
    --- PASS: TestValidateStagesRejectsIncompletePlan/duplicate-name (0.00s)
    --- PASS: TestValidateStagesRejectsIncompletePlan/missing-forward (0.00s)
    --- PASS: TestValidateStagesRejectsIncompletePlan/missing-back (0.00s)
=== RUN   TestRollbackPathRunsCompletedStagesInReverse
--- PASS: TestRollbackPathRunsCompletedStagesInReverse (0.00s)
=== RUN   TestRollbackPathCoversOnlyCompletedStages
--- PASS: TestRollbackPathCoversOnlyCompletedStages (0.00s)
=== RUN   TestRollbackPathRejectsBadIndexAndPlan
--- PASS: TestRollbackPathRejectsBadIndexAndPlan (0.00s)
PASS
ok  	webapp/internal/split	0.297s