《互联网产品的服务端架构·规模化与架构演进》11.1 容量规划与压测

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

package promo

import (
	"errors"
	"fmt"
	"math"
)

// ErrInvalidCapacity 表示容量输入本身不成立。
var ErrInvalidCapacity = errors.New("promo: invalid capacity input")

// InstanceQPS 是单实例在目标延迟下可承载的 QPS（案例假设值）。
// 生产环境应替换为压测得到的实测值，而不是照抄这个常量。
const InstanceQPS = 400.0

// HeadroomFloor 是推荐的最低余量比例。
const HeadroomFloor = 0.2

// Input 是一次大促容量测算的输入。
// BaselineQPS 是日常基线，PeakFactor 是峰值相对基线的倍数，
// SafeRate 是安全系数（1.3 表示在峰值上再留 30% 余量）。
type Input struct {
	BaselineQPS float64
	PeakFactor  float64
	SafeRate    float64
}

// Capacity 是测算结果。
// PeakQPS 是未经安全系数的峰值，Instances 是按 SafeRate 扩容后的实例数，
// Headroom 是安全系数折算出的余量比例。
type Capacity struct {
	PeakQPS   float64
	Instances float64
	Headroom  float64
}

func (i Input) validate() error {
	switch {
	case i.BaselineQPS <= 0:
		return fmt.Errorf("%w: baseline QPS must be positive, got %v", ErrInvalidCapacity, i.BaselineQPS)
	case i.PeakFactor < 1:
		return fmt.Errorf("%w: peak factor must be at least 1, got %v", ErrInvalidCapacity, i.PeakFactor)
	case i.SafeRate < 1:
		return fmt.Errorf("%w: safe rate must be at least 1, got %v", ErrInvalidCapacity, i.SafeRate)
	}
	return nil
}

// Plan 从业务峰值推出需要承载的 QPS 与实例数。
// 第二个返回值是 warning：余量低于 HeadroomFloor 时提示风险，
// 但仍然返回测算结果，方便调用方在预案里显式记录“已知余量不足”。
func Plan(i Input) (Capacity, string, error) {
	if err := i.validate(); err != nil {
		return Capacity{}, "", err
	}
	peak := i.BaselineQPS * i.PeakFactor
	instances := math.Ceil(peak * i.SafeRate / InstanceQPS)
	headroom := i.SafeRate - 1
	c := Capacity{PeakQPS: peak, Instances: instances, Headroom: headroom}
	if headroom < HeadroomFloor-1e-9 {
		return c, fmt.Sprintf("promo: headroom %.0f%% is below the %.0f%% floor", headroom*100, HeadroomFloor*100), nil
	}
	return c, "", nil
}

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

package promo

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

func TestPlanScalesPeakAndInstances(t *testing.T) {
	c, warn, err := Plan(Input{BaselineQPS: 1000, PeakFactor: 4, SafeRate: 1.3})
	if err != nil {
		t.Fatalf("Plan returned error: %v", err)
	}
	if warn != "" {
		t.Fatalf("unexpected warning: %q", warn)
	}
	if math.Abs(c.PeakQPS-4000) > 1e-9 {
		t.Fatalf("PeakQPS = %v, want 4000", c.PeakQPS)
	}
	// 4000 * 1.3 / 400 = 13，刚好整除。
	if math.Abs(c.Instances-13) > 1e-9 {
		t.Fatalf("Instances = %v, want 13", c.Instances)
	}
	if math.Abs(c.Headroom-0.3) > 1e-9 {
		t.Fatalf("Headroom = %v, want 0.3", c.Headroom)
	}
}

func TestPlanRoundsInstancesUp(t *testing.T) {
	c, warn, err := Plan(Input{BaselineQPS: 1100, PeakFactor: 4, SafeRate: 1.3})
	if err != nil {
		t.Fatalf("Plan returned error: %v", err)
	}
	if warn != "" {
		t.Fatalf("unexpected warning: %q", warn)
	}
	// 4400 * 1.3 / 400 = 14.3，向上取整为 15。
	if math.Abs(c.Instances-15) > 1e-9 {
		t.Fatalf("Instances = %v, want 15", c.Instances)
	}
}

func TestPlanWarnsWhenHeadroomBelowFloor(t *testing.T) {
	c, warn, err := Plan(Input{BaselineQPS: 1000, PeakFactor: 4, SafeRate: 1.1})
	if err != nil {
		t.Fatalf("Plan returned error: %v", err)
	}
	if warn == "" {
		t.Fatal("want warning for 10% headroom")
	}
	if !strings.Contains(warn, "below") {
		t.Fatalf("warning %q should explain the floor", warn)
	}
	if math.Abs(c.Headroom-0.1) > 1e-9 {
		t.Fatalf("Headroom = %v, want 0.1", c.Headroom)
	}
}

func TestPlanAcceptsExactFloor(t *testing.T) {
	_, warn, err := Plan(Input{BaselineQPS: 1000, PeakFactor: 4, SafeRate: 1.2})
	if err != nil {
		t.Fatalf("Plan returned error: %v", err)
	}
	if warn != "" {
		t.Fatalf("headroom exactly at floor should not warn, got %q", warn)
	}
}

func TestPlanRejectsInvalidInput(t *testing.T) {
	cases := []Input{
		{BaselineQPS: 0, PeakFactor: 2, SafeRate: 1.2},
		{BaselineQPS: -1, PeakFactor: 2, SafeRate: 1.2},
		{BaselineQPS: 100, PeakFactor: 0.9, SafeRate: 1.2},
		{BaselineQPS: 100, PeakFactor: 2, SafeRate: 0.99},
	}
	for _, in := range cases {
		_, _, err := Plan(in)
		if !errors.Is(err, ErrInvalidCapacity) {
			t.Fatalf("Plan(%+v) error = %v, want ErrInvalidCapacity", in, err)
		}
	}
}

cd .local/checks/webapp-lab && go test ./internal/promo/ -run 'TestPlan' -count=1 -v

=== RUN   TestPlanScalesPeakAndInstances
--- PASS: TestPlanScalesPeakAndInstances (0.00s)
=== RUN   TestPlanRoundsInstancesUp
--- PASS: TestPlanRoundsInstancesUp (0.00s)
=== RUN   TestPlanWarnsWhenHeadroomBelowFloor
--- PASS: TestPlanWarnsWhenHeadroomBelowFloor (0.00s)
=== RUN   TestPlanAcceptsExactFloor
--- PASS: TestPlanAcceptsExactFloor (0.00s)
=== RUN   TestPlanRejectsInvalidInput
--- PASS: TestPlanRejectsInvalidInput (0.00s)
PASS
ok  	webapp/internal/promo	0.304s