《后端架构设计·高性能与高可用》2.1 从业务指标到 QPS 与并发数

平均订单率 = 500000 / 86400 = 5.787 单/秒
平均 QPS   = 5.787 × 4      = 23.148 请求/秒
峰值 QPS   = 23.148 × 3.5   = 81.019 请求/秒

// file: internal/capacity/capacity.go
// tier: L1
// verify: go test ./internal/capacity/ -count=1 -v
package capacity

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

var (
	ErrDailyOrders   = errors.New("daily orders must be positive")
	ErrPeakFactor    = errors.New("peak factor must be at least 1")
	ErrAmplification = errors.New("request amplification must be at least 1")
	ErrLatency       = errors.New("p99 latency must be positive")
	ErrNoTraffic     = errors.New("hourly window has no traffic")
	ErrNegative      = errors.New("hourly counts must be non-negative")
)

// BusinessMetrics 的 DailyOrders 是业务目标，PeakFactor 与 Amplification
// 必须来自实测，P99 是 SLO 目标而不是当前观测值。
type BusinessMetrics struct {
	DailyOrders   float64
	PeakFactor    float64
	Amplification float64
	P99           time.Duration
}

func (m BusinessMetrics) Validate() error {
	switch {
	case m.DailyOrders <= 0:
		return ErrDailyOrders
	case m.PeakFactor < 1:
		return ErrPeakFactor
	case m.Amplification < 1:
		return ErrAmplification
	case m.P99 <= 0:
		return ErrLatency
	}
	return nil
}

func (m BusinessMetrics) AverageQPS() float64 {
	return m.DailyOrders * m.Amplification / 86400
}

func (m BusinessMetrics) PeakQPS() float64 {
	return m.AverageQPS() * m.PeakFactor
}

// Concurrency 是 Little's Law 的 L = λW；用 P99 得到尾延迟安全包络。
func (m BusinessMetrics) Concurrency() float64 {
	return m.PeakQPS() * m.P99.Seconds()
}

// MeanConcurrency 用平均延迟估计稳态并发，用于连接池和线程数下限。
func (m BusinessMetrics) MeanConcurrency(mean time.Duration) float64 {
	return m.PeakQPS() * mean.Seconds()
}

// HourlyCounts 是 24 个小时桶的原始计数，索引 0 表示 00:00-00:59。
type HourlyCounts [24]float64

// PeakFactorFromHourly 用实测小时分布计算：最忙一小时 ÷ 全天平均每小时。
func PeakFactorFromHourly(h HourlyCounts) (float64, error) {
	total, peak := 0.0, 0.0
	for _, v := range h {
		if v < 0 {
			return 0, ErrNegative
		}
		total += v
		if v > peak {
			peak = v
		}
	}
	if total == 0 {
		return 0, ErrNoTraffic
	}
	return peak / (total / 24), nil
}

// CheckPeakFactor 用相对误差校验声明值是否被实测分布支持。
func CheckPeakFactor(declared float64, h HourlyCounts, tolerance float64) error {
	if declared < 1 {
		return ErrPeakFactor
	}
	measured, err := PeakFactorFromHourly(h)
	if err != nil {
		return err
	}
	if diff := math.Abs(declared-measured) / measured; diff > tolerance {
		return fmt.Errorf("declared %.2f vs measured %.2f: %.1f%% off", declared, measured, diff*100)
	}
	return nil
}

// Order 与 Apply 只用于微基准，覆盖状态变更的进程内开销。
type Order struct {
	ID      string
	Status  string
	Version int
}

var ErrInvalidState = errors.New("invalid state transition")

func Apply(order *Order, next string) error {
	if order.Status == next {
		return ErrInvalidState
	}
	order.Version++
	order.Status = next
	return nil
}

// file: internal/capacity/capacity_test.go
// tier: L1
// verify: go test ./internal/capacity/ -count=1 -v
package capacity

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

func TestBusinessMetrics(t *testing.T) {
	tests := []struct {
		name        string
		metrics     BusinessMetrics
		avg, peak   float64
		concurrency float64
	}{
		{
			name:        "500k orders per day",
			metrics:     BusinessMetrics{DailyOrders: 500000, PeakFactor: 3.5, Amplification: 4, P99: 320 * time.Millisecond},
			avg:         500000.0 * 4 / 86400,
			peak:        500000.0 * 4 / 86400 * 3.5,
			concurrency: 500000.0 * 4 / 86400 * 3.5 * 0.32,
		},
		{
			name:    "flat day",
			metrics: BusinessMetrics{DailyOrders: 86400, PeakFactor: 1, Amplification: 1, P99: time.Second},
			avg:     1, peak: 1, concurrency: 1,
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			if err := tt.metrics.Validate(); err != nil {
				t.Fatal(err)
			}
			if got := tt.metrics.AverageQPS(); math.Abs(got-tt.avg) > 1e-9 {
				t.Fatalf("AverageQPS=%f want %f", got, tt.avg)
			}
			if got := tt.metrics.PeakQPS(); math.Abs(got-tt.peak) > 1e-9 {
				t.Fatalf("PeakQPS=%f want %f", got, tt.peak)
			}
			if got := tt.metrics.Concurrency(); math.Abs(got-tt.concurrency) > 1e-9 {
				t.Fatalf("Concurrency=%f want %f", got, tt.concurrency)
			}
		})
	}
}

func TestValidate(t *testing.T) {
	valid := BusinessMetrics{DailyOrders: 1, PeakFactor: 1, Amplification: 1, P99: time.Millisecond}
	tests := []struct {
		name   string
		mutate func(*BusinessMetrics)
		want   error
	}{
		{"zero orders", func(m *BusinessMetrics) { m.DailyOrders = 0 }, ErrDailyOrders},
		{"peak below one", func(m *BusinessMetrics) { m.PeakFactor = 0.9 }, ErrPeakFactor},
		{"amplification below one", func(m *BusinessMetrics) { m.Amplification = 0 }, ErrAmplification},
		{"zero latency", func(m *BusinessMetrics) { m.P99 = 0 }, ErrLatency},
		{"valid", func(m *BusinessMetrics) {}, nil},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			m := valid
			tt.mutate(&m)
			if err := m.Validate(); !errors.Is(err, tt.want) {
				t.Fatalf("Validate()=%v want %v", err, tt.want)
			}
		})
	}
}

func TestPeakFactor(t *testing.T) {
	var h HourlyCounts
	for i := range h {
		h[i] = 178
	}
	h[20] = 700
	factor, err := PeakFactorFromHourly(h)
	if err != nil || math.Abs(factor-3.5) > 0.01 {
		t.Fatalf("factor=%f err=%v want 3.50", factor, err)
	}
	if err := CheckPeakFactor(3.5, h, 0.05); err != nil {
		t.Fatalf("declared 3.5 should pass: %v", err)
	}
	if err := CheckPeakFactor(2.0, h, 0.05); err == nil {
		t.Fatal("declared 2.0 should fail")
	}
	var empty HourlyCounts
	if _, err := PeakFactorFromHourly(empty); !errors.Is(err, ErrNoTraffic) {
		t.Fatalf("empty=%v", err)
	}
	empty[0] = -1
	if _, err := PeakFactorFromHourly(empty); !errors.Is(err, ErrNegative) {
		t.Fatalf("negative=%v", err)
	}
}

func BenchmarkApply(b *testing.B) {
	order := &Order{ID: "o-1", Status: "CREATED"}
	for i := 0; i < b.N; i++ {
		order.Status = "CREATED"
		if err := Apply(order, "INVENTORY_RESERVED"); err != nil {
			b.Fatal(err)
		}
	}
}

func TestExampleReport(t *testing.T) {
	m := BusinessMetrics{DailyOrders: 500000, PeakFactor: 3.5, Amplification: 4, P99: 320 * time.Millisecond}
	t.Logf("daily_orders=%.0f type=target peak_factor=%.2f type=example amplification=%.1f type=example p99=%s type=target",
		m.DailyOrders, m.PeakFactor, m.Amplification, m.P99)
	t.Logf("average_qps=%.3f peak_qps=%.3f concurrency_p99=%.2f concurrency_mean_80ms=%.2f",
		m.AverageQPS(), m.PeakQPS(), m.Concurrency(), m.MeanConcurrency(80*time.Millisecond))
}

$ go test ./... -count=1 -v
--- PASS: TestBusinessMetrics (0.00s)
--- PASS: TestValidate (0.00s)
--- PASS: TestPeakFactor (0.00s)
--- PASS: TestExampleReport (0.00s)
    capacity_test.go:110: daily_orders=500000 type=target peak_factor=3.50 type=example amplification=4.0 type=example p99=320ms type=target
    capacity_test.go:112: average_qps=23.148 peak_qps=81.019 concurrency_p99=25.93 concurrency_mean_80ms=6.48
PASS
ok  	archlab/internal/capacity	0.238s

$ go test ./internal/capacity -run '^$' -bench BenchmarkApply -benchtime=1s -count=1
BenchmarkApply-10    	519307324	         2.228 ns/op
PASS
ok  	archlab/internal/capacity	1.642s