《互联网产品的服务端架构·规模化与架构演进》3.2 弹性扩容与预热

// file: internal/burst/capacity.go
// tier: L1
// verify: go test ./internal/burst/

package burst

import (
	"errors"
	"fmt"
)

var (
	// ErrInvalidPlan 表示容量计划本身不成立。
	ErrInvalidPlan = errors.New("burst: invalid capacity plan")
	// ErrInvalidPreheat 表示预热窗口不合法。
	ErrInvalidPreheat = errors.New("burst: preheat minutes must be positive")
)

// Plan 描述一次热点容量测算。
// BaselineQPS 是日常基线，PeakFactor 是峰值相对基线的倍数，
// Headroom 是额外留出的余量比例（0.2 表示再留 20%）。
type Plan struct {
	BaselineQPS float64
	PeakFactor  float64
	Headroom    float64
}

func (p Plan) validate() error {
	switch {
	case p.BaselineQPS <= 0:
		return fmt.Errorf("%w: baseline QPS must be positive", ErrInvalidPlan)
	case p.PeakFactor < 1:
		return fmt.Errorf("%w: peak factor must be at least 1", ErrInvalidPlan)
	case p.Headroom < 0:
		return fmt.Errorf("%w: headroom must not be negative", ErrInvalidPlan)
	}
	return nil
}

// Required 返回峰值期间需要承载的 QPS。
func Required(p Plan) (float64, error) {
	if err := p.validate(); err != nil {
		return 0, err
	}
	return p.BaselineQPS * p.PeakFactor * (1 + p.Headroom), nil
}

// Preheat 返回每分钟需要预热的实例比例。
// 计算方式是：先算出峰值需要的新增容量，均摊到预热窗口的每一分钟，
// 再除以最终实例池大小。0.08 表示每分钟要拉起初始终态 8% 的实例。
func Preheat(p Plan, minutes int) (float64, error) {
	if minutes <= 0 {
		return 0, fmt.Errorf("%w: got %d", ErrInvalidPreheat, minutes)
	}
	required, err := Required(p)
	if err != nil {
		return 0, err
	}
	extra := required - p.BaselineQPS
	if extra <= 0 {
		return 0, nil
	}
	return extra / required / float64(minutes), nil
}

// file: internal/burst/capacity_test.go
// tier: L1
// verify: go test ./internal/burst/

package burst

import (
	"errors"
	"math"
	"testing"
)

func TestRequiredMultipliesPeakAndHeadroom(t *testing.T) {
	got, err := Required(Plan{BaselineQPS: 1000, PeakFactor: 4, Headroom: 0.25})
	if err != nil {
		t.Fatalf("Required returned error: %v", err)
	}
	if math.Abs(got-5000) > 1e-9 {
		t.Fatalf("Required = %v, want 5000", got)
	}
}

func TestRequiredRejectsInvalidPlan(t *testing.T) {
	cases := []Plan{
		{BaselineQPS: 0, PeakFactor: 2, Headroom: 0.1},
		{BaselineQPS: -1, PeakFactor: 2, Headroom: 0.1},
		{BaselineQPS: 100, PeakFactor: 0.5, Headroom: 0.1},
		{BaselineQPS: 100, PeakFactor: 2, Headroom: -0.1},
	}
	for _, p := range cases {
		if _, err := Required(p); !errors.Is(err, ErrInvalidPlan) {
			t.Fatalf("Required(%+v) error = %v, want ErrInvalidPlan", p, err)
		}
	}
}

func TestPreheatSpreadsGrowthPerMinute(t *testing.T) {
	got, err := Preheat(Plan{BaselineQPS: 1000, PeakFactor: 4, Headroom: 0.25}, 10)
	if err != nil {
		t.Fatalf("Preheat returned error: %v", err)
	}
	if math.Abs(got-0.08) > 1e-9 {
		t.Fatalf("Preheat = %v, want 0.08", got)
	}
}

func TestPreheatShorterWindowNeedsMorePerMinute(t *testing.T) {
	fast, err := Preheat(Plan{BaselineQPS: 1000, PeakFactor: 4, Headroom: 0.25}, 5)
	if err != nil {
		t.Fatalf("Preheat returned error: %v", err)
	}
	slow, err := Preheat(Plan{BaselineQPS: 1000, PeakFactor: 4, Headroom: 0.25}, 20)
	if err != nil {
		t.Fatalf("Preheat returned error: %v", err)
	}
	if !(fast > slow) {
		t.Fatalf("5-minute rate %v should exceed 20-minute rate %v", fast, slow)
	}
}

func TestPreheatNoGrowthIsZero(t *testing.T) {
	got, err := Preheat(Plan{BaselineQPS: 500, PeakFactor: 1, Headroom: 0}, 10)
	if err != nil {
		t.Fatalf("Preheat returned error: %v", err)
	}
	if got != 0 {
		t.Fatalf("Preheat = %v, want 0 when there is no growth", got)
	}
}

func TestPreheatRejectsNonPositiveMinutes(t *testing.T) {
	p := Plan{BaselineQPS: 1000, PeakFactor: 2, Headroom: 0.1}
	for _, minutes := range []int{0, -1} {
		if _, err := Preheat(p, minutes); !errors.Is(err, ErrInvalidPreheat) {
			t.Fatalf("Preheat(minutes=%d) error = %v, want ErrInvalidPreheat", minutes, err)
		}
	}
}

func TestPreheatPropagatesPlanError(t *testing.T) {
	if _, err := Preheat(Plan{BaselineQPS: 0, PeakFactor: 2}, 10); !errors.Is(err, ErrInvalidPlan) {
		t.Fatalf("error = %v, want ErrInvalidPlan", err)
	}
}

cd .local/checks/webapp-lab && go test ./internal/burst/ -count=1 -run 'TestRequired|TestPreheat' -v

=== RUN   TestRequiredMultipliesPeakAndHeadroom
--- PASS: TestRequiredMultipliesPeakAndHeadroom (0.00s)
=== RUN   TestRequiredRejectsInvalidPlan
--- PASS: TestRequiredRejectsInvalidPlan (0.00s)
=== RUN   TestPreheatSpreadsGrowthPerMinute
--- PASS: TestPreheatSpreadsGrowthPerMinute (0.00s)
=== RUN   TestPreheatShorterWindowNeedsMorePerMinute
--- PASS: TestPreheatShorterWindowNeedsMorePerMinute (0.00s)
=== RUN   TestPreheatNoGrowthIsZero
--- PASS: TestPreheatNoGrowthIsZero (0.00s)
=== RUN   TestPreheatRejectsNonPositiveMinutes
--- PASS: TestPreheatRejectsNonPositiveMinutes (0.00s)
=== RUN   TestPreheatPropagatesPlanError
--- PASS: TestPreheatPropagatesPlanError (0.00s)
PASS
ok  	webapp/internal/burst	0.226s