《MMO 服务器开发》1.2 什么时候该拆、什么时候不该

// file: internal/split/decision.go
// tier: L1
// verify: go test ./internal/split/
// Package split turns "should we shard this yet" from a gut call into a
// function. Section 1.2 lists what a split costs and what it buys; this file
// puts a number on both sides, so the answer is reproducible.
//
// The model is deliberately small: one node has a known CCU ceiling, we hold
// back a headroom fraction for spikes, and a split adds a known number of
// cross-node hops to a player action. A split is worth it only when the single
// node genuinely runs out of room AND the hops it adds stay inside the latency
// budget AND the operational cost stays under the ceiling. Any one of those
// failing means "scale up one node first, split later".
package split

import (
	"fmt"
	"math"
)

// Capacity describes how much one aegis node can carry, and what we need it to.
type Capacity struct {
	// NodeCCU is the CCU a single node serves while staying inside its CPU
	// budget, measured on the target hardware.
	NodeCCU int
	// HeadroomPct is the fraction of NodeCCU held back for login spikes and
	// bursts, e.g. 0.30 for thirty percent.
	HeadroomPct float64
	// ProjectedCCU is the peak CCU we must serve after the next content update.
	ProjectedCCU int
}

// Cost is what splitting adds. Every field is a real, measurable quantity; none
// of them is a feeling.
type Cost struct {
	// HopsPerAction is the cross-node RPCs added to one player action.
	HopsPerAction int
	// PerHopMs is the p99 latency of one internal hop.
	PerHopMs float64
	// BudgetMs is the latency budget for that action, end to end.
	BudgetMs float64
	// OpsMultiplier is the operational cost of the split relative to one node,
	// e.g. 2.5 for "two and a half times the moving parts", never below 1.
	OpsMultiplier float64
}

// Policy is the line between "split" and "not yet".
type Policy struct {
	// MaxLatencyShare is the largest share of BudgetMs the added hops may take.
	MaxLatencyShare float64
	// MaxOpsMultiplier is the operational multiplier above which a split is
	// refused even if it would fit, because it is not worth running.
	MaxOpsMultiplier float64
}

// DefaultPolicy is the policy used throughout the book's examples: added hops
// may take at most a quarter of the budget, and a split may not multiply the
// operational surface by more than four.
var DefaultPolicy = Policy{MaxLatencyShare: 0.25, MaxOpsMultiplier: 4.0}

// Decision is the answer, carrying the arithmetic that produced it so the
// caller can print why.
type Decision struct {
	Split       bool
	NodesNeeded int
	UsableCCU   float64
	AddedMs     float64
	Reason      string
}

// Decide returns whether the split is worth doing under policy p.
func Decide(c Capacity, cost Cost, p Policy) Decision {
	usable := float64(c.NodeCCU) * (1 - c.HeadroomPct)
	if usable <= 0 {
		return Decision{Reason: "NodeCCU or headroom leaves no usable capacity"}
	}
	nodes := int(math.Ceil(float64(c.ProjectedCCU) / usable))
	added := float64(cost.HopsPerAction) * cost.PerHopMs
	d := Decision{NodesNeeded: nodes, UsableCCU: usable, AddedMs: added}

	// One node still fits: a split would add cost for no capacity gain.
	if nodes <= 1 {
		d.Reason = fmt.Sprintf("one node carries %d CCU with room; do not split", c.ProjectedCCU)
		return d
	}
	// The hops a split adds blow the latency budget: fix the hot path first.
	if cost.BudgetMs > 0 && added > cost.BudgetMs*p.MaxLatencyShare {
		d.Reason = fmt.Sprintf("split adds %.1fms, over the %.1fms budget share", added, cost.BudgetMs*p.MaxLatencyShare)
		return d
	}
	// The split multiplies the operational surface past the ceiling.
	if cost.OpsMultiplier > p.MaxOpsMultiplier {
		d.Reason = fmt.Sprintf("split multiplies ops by %.1fx, over the %.1fx ceiling", cost.OpsMultiplier, p.MaxOpsMultiplier)
		return d
	}
	d.Split = true
	d.Reason = fmt.Sprintf("needs %d nodes, adds %.1fms, ops x%.1f; split is worth it", nodes, added, cost.OpsMultiplier)
	return d
}

// file: internal/split/decision_test.go
// tier: L1
// verify: go test ./internal/split/
package split

import "testing"

func TestSingleNodeFitsSoNoSplit(t *testing.T) {
	// 8000 CCU peak, a node serves 12000 with 30% held back -> 8400 usable.
	// One node fits, so splitting would only add cost.
	c := Capacity{NodeCCU: 12000, HeadroomPct: 0.30, ProjectedCCU: 8000}
	d := Decide(c, Cost{HopsPerAction: 2, PerHopMs: 0.4, BudgetMs: 20, OpsMultiplier: 2}, DefaultPolicy)
	if d.Split {
		t.Fatalf("expected no split, got %+v", d)
	}
	if d.NodesNeeded != 1 {
		t.Errorf("NodesNeeded = %d, want 1", d.NodesNeeded)
	}
}

func TestSplitWhenCapacityRunsOutAndCostIsCheap(t *testing.T) {
	// 20000 CCU peak against 8400 usable needs 3 nodes, and the hops are cheap.
	c := Capacity{NodeCCU: 12000, HeadroomPct: 0.30, ProjectedCCU: 20000}
	d := Decide(c, Cost{HopsPerAction: 2, PerHopMs: 0.4, BudgetMs: 20, OpsMultiplier: 2}, DefaultPolicy)
	if !d.Split {
		t.Fatalf("expected split, got %+v", d)
	}
	if d.NodesNeeded != 3 {
		t.Errorf("NodesNeeded = %d, want 3", d.NodesNeeded)
	}
}

func TestRefuseWhenHopsBlowTheBudget(t *testing.T) {
	// Capacity says split, but 6 hops at 3ms is 18ms against a 20ms budget,
	// which is 90% of it: over the quarter-share policy. Fix the hot path first.
	c := Capacity{NodeCCU: 12000, HeadroomPct: 0.30, ProjectedCCU: 20000}
	d := Decide(c, Cost{HopsPerAction: 6, PerHopMs: 3, BudgetMs: 20, OpsMultiplier: 2}, DefaultPolicy)
	if d.Split {
		t.Fatalf("expected refusal on latency, got %+v", d)
	}
}

func TestRefuseWhenOpsMultiplierTooHigh(t *testing.T) {
	c := Capacity{NodeCCU: 12000, HeadroomPct: 0.30, ProjectedCCU: 20000}
	d := Decide(c, Cost{HopsPerAction: 2, PerHopMs: 0.4, BudgetMs: 20, OpsMultiplier: 5}, DefaultPolicy)
	if d.Split {
		t.Fatalf("expected refusal on ops multiplier, got %+v", d)
	}
}

func TestBoundaryIsInclusive(t *testing.T) {
	// Exactly at the usable ceiling is still one node.
	c := Capacity{NodeCCU: 10000, HeadroomPct: 0.30, ProjectedCCU: 7000}
	d := Decide(c, Cost{HopsPerAction: 1, PerHopMs: 0.5, BudgetMs: 10, OpsMultiplier: 1.5}, DefaultPolicy)
	if d.NodesNeeded != 1 || d.Split {
		t.Fatalf("exactly-at-ceiling must not split, got %+v", d)
	}
	// One CCU past the ceiling needs two nodes.
	c.ProjectedCCU = 7001
	d = Decide(c, Cost{HopsPerAction: 1, PerHopMs: 0.5, BudgetMs: 10, OpsMultiplier: 1.5}, DefaultPolicy)
	if d.NodesNeeded != 2 || !d.Split {
		t.Fatalf("one past the ceiling must split, got %+v", d)
	}
}

=== RUN   TestSingleNodeFitsSoNoSplit
--- PASS: TestSingleNodeFitsSoNoSplit (0.00s)
=== RUN   TestSplitWhenCapacityRunsOutAndCostIsCheap
--- PASS: TestSplitWhenCapacityRunsOutAndCostIsCheap (0.00s)
=== RUN   TestRefuseWhenHopsBlowTheBudget
--- PASS: TestRefuseWhenHopsBlowTheBudget (0.00s)
=== RUN   TestRefuseWhenOpsMultiplierTooHigh
--- PASS: TestRefuseWhenOpsMultiplierTooHigh (0.00s)
=== RUN   TestBoundaryIsInclusive
--- PASS: TestBoundaryIsInclusive (0.00s)
PASS
ok  	aegis/internal/split	0.632s