《互联网产品的服务端架构·产品、流量与基础能力》10.2 灰度、开关与回滚

// file: internal/release/rollout.go
// tier: L1
// verify: go test ./internal/release/

package release

import "fmt"

// Stage 是灰度计划里的一个台阶。
// Percent 是放量比例，Minutes 是在该比例下至少观察的分钟数。
type Stage struct {
	Percent int
	Minutes int
}

// Plan 是完整的灰度计划。
type Plan struct {
	Stages []Stage
}

// ValidatePlan 检查灰度计划：从 0% 起步，严格递增，最后到 100%。
func ValidatePlan(p Plan) error {
	if len(p.Stages) == 0 {
		return fmt.Errorf("release: rollout plan has no stages")
	}
	if p.Stages[0].Percent != 0 {
		return fmt.Errorf("release: rollout must start at 0%%, got %d%%", p.Stages[0].Percent)
	}
	prev := -1
	for i, s := range p.Stages {
		if s.Percent < 0 || s.Percent > 100 {
			return fmt.Errorf("release: stage %d percent %d out of range", i, s.Percent)
		}
		if s.Minutes < 0 {
			return fmt.Errorf("release: stage %d minutes %d is negative", i, s.Minutes)
		}
		if i > 0 && s.Percent == prev {
			return fmt.Errorf("release: stage %d repeats percent %d%%", i, s.Percent)
		}
		if s.Percent < prev {
			return fmt.Errorf("release: stage %d moves backward from %d%% to %d%%", i, prev, s.Percent)
		}
		prev = s.Percent
	}
	if last := p.Stages[len(p.Stages)-1].Percent; last != 100 {
		return fmt.Errorf("release: rollout must end at 100%%, got %d%%", last)
	}
	return nil
}

// Advance 返回计划里的第 idx 个阶段。索引越界或计划非法时返回错误。
func Advance(p Plan, idx int) (Stage, error) {
	if err := ValidatePlan(p); err != nil {
		return Stage{}, err
	}
	if idx < 0 || idx >= len(p.Stages) {
		return Stage{}, fmt.Errorf("release: stage index %d out of range [0,%d)", idx, len(p.Stages))
	}
	return p.Stages[idx], nil
}

// Guard 是自动回滚的观测阈值。
// 样本数至少要达到 MinSamples，错误率严格高于 MaxErrorRate 才触发回滚。
type Guard struct {
	MaxErrorRate float64
	MinSamples   int
}

// ShouldRollback 判断当前观测是否足以触发回滚。
// 样本不足时一律返回 false，避免小样本抖动造成误回滚。
func ShouldRollback(g Guard, samples int, errorRate float64) bool {
	if samples < 0 || samples < g.MinSamples {
		return false
	}
	return errorRate > g.MaxErrorRate
}

// file: internal/release/rollout_test.go
// tier: L1
// verify: go test ./internal/release/

package release

import (
	"strings"
	"testing"
)

func TestValidatePlanAcceptsMonotonicStages(t *testing.T) {
	p := Plan{Stages: []Stage{
		{Percent: 0, Minutes: 0},
		{Percent: 1, Minutes: 30},
		{Percent: 5, Minutes: 60},
		{Percent: 25, Minutes: 120},
		{Percent: 100, Minutes: 0},
	}}
	if err := ValidatePlan(p); err != nil {
		t.Fatalf("Validate() = %v, want nil", err)
	}
}

func TestValidatePlanRejectsBadStages(t *testing.T) {
	cases := []struct {
		name string
		plan Plan
		want string
	}{
		{name: "empty", plan: Plan{}, want: "no stages"},
		{name: "no zero stage", plan: Plan{Stages: []Stage{{Percent: 5, Minutes: 10}, {Percent: 100}}}, want: "start at 0%"},
		{name: "no hundred stage", plan: Plan{Stages: []Stage{{Percent: 0}, {Percent: 50}}}, want: "end at 100%"},
		{name: "repeated percent", plan: Plan{Stages: []Stage{{Percent: 0}, {Percent: 10}, {Percent: 10}, {Percent: 100}}}, want: "repeats"},
		{name: "backward percent", plan: Plan{Stages: []Stage{{Percent: 0}, {Percent: 20}, {Percent: 10}, {Percent: 100}}}, want: "backward"},
		{name: "out of range", plan: Plan{Stages: []Stage{{Percent: 0}, {Percent: 120}, {Percent: 100}}}, want: "out of range"},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			err := ValidatePlan(tc.plan)
			if err == nil {
				t.Fatal("Validate() = nil, want error")
			}
			if !strings.Contains(err.Error(), tc.want) {
				t.Fatalf("Validate() = %q, want substring %q", err, tc.want)
			}
		})
	}
}

func TestAdvanceReturnsStageAndRejectsOutOfRange(t *testing.T) {
	p := Plan{Stages: []Stage{
		{Percent: 0, Minutes: 0},
		{Percent: 10, Minutes: 30},
		{Percent: 100, Minutes: 60},
	}}
	got, err := Advance(p, 1)
	if err != nil {
		t.Fatal(err)
	}
	if got.Percent != 10 || got.Minutes != 30 {
		t.Fatalf("Advance(1) = %+v, want {10 30}", got)
	}
	for _, idx := range []int{-1, 3} {
		if _, err := Advance(p, idx); err == nil {
			t.Fatalf("Advance(%d) = nil error, want out of range", idx)
		}
	}
	if _, err := Advance(Plan{}, 0); err == nil {
		t.Fatal("Advance on invalid plan = nil error")
	}
}

func TestShouldRollbackNeedsEnoughSamples(t *testing.T) {
	g := Guard{MaxErrorRate: 0.02, MinSamples: 500}
	if ShouldRollback(g, 100, 0.50) {
		t.Fatal("rollback fired with 100 samples, want false")
	}
	if ShouldRollback(g, 500, 0.02) {
		t.Fatal("rollback fired at exactly the threshold, want false")
	}
	if !ShouldRollback(g, 500, 0.021) {
		t.Fatal("rollback did not fire above the threshold")
	}
	if ShouldRollback(g, -1, 0.90) {
		t.Fatal("rollback fired with negative samples, want false")
	}
}

cd .local/checks/webapp-lab && go test ./internal/release/ -count=1 -run 'TestValidatePlan|TestAdvance|TestShouldRollback' -v

=== RUN   TestValidatePlanAcceptsMonotonicStages
--- PASS: TestValidatePlanAcceptsMonotonicStages (0.00s)
=== RUN   TestValidatePlanRejectsBadStages
=== RUN   TestValidatePlanRejectsBadStages/empty
=== RUN   TestValidatePlanRejectsBadStages/no_zero_stage
=== RUN   TestValidatePlanRejectsBadStages/no_hundred_stage
=== RUN   TestValidatePlanRejectsBadStages/repeated_percent
=== RUN   TestValidatePlanRejectsBadStages/backward_percent
=== RUN   TestValidatePlanRejectsBadStages/out_of_range
--- PASS: TestValidatePlanRejectsBadStages (0.00s)
    --- PASS: TestValidatePlanRejectsBadStages/empty (0.00s)
    --- PASS: TestValidatePlanRejectsBadStages/no_zero_stage (0.00s)
    --- PASS: TestValidatePlanRejectsBadStages/no_hundred_stage (0.00s)
    --- PASS: TestValidatePlanRejectsBadStages/repeated_percent (0.00s)
    --- PASS: TestValidatePlanRejectsBadStages/backward_percent (0.00s)
    --- PASS: TestValidatePlanRejectsBadStages/out_of_range (0.00s)
=== RUN   TestAdvanceReturnsStageAndRejectsOutOfRange
--- PASS: TestAdvanceReturnsStageAndRejectsOutOfRange (0.00s)
=== RUN   TestShouldRollbackNeedsEnoughSamples
--- PASS: TestShouldRollbackNeedsEnoughSamples (0.00s)
PASS
ok  	webapp/internal/release	0.235s