《后端架构设计·演进与治理》3.3 服务网格的收益边界：Sidecar、xDS 与运维成本

// file: internal/platform/discovery/routing.go
// tier: L1
// verify: go test ./internal/platform/discovery/ -count=1
package discovery

import "fmt"
import "math"
import "sort"
import "strings"

// RouteAction names the destination cluster of a matched route.
type RouteAction struct {
	Cluster string
	Weight  int
}

// Route is one ordered, first-match-wins route entry. Host "" matches any host.
type Route struct {
	Name    string
	Host    string
	Prefix  string
	Headers map[string]string
	Action  RouteAction
}

// RouteTable is an ordered route list plus the clusters the control plane
// knows about. Order is semantic: the first matching route wins.
type RouteTable struct {
	Routes   []Route
	Clusters map[string]bool
}

// Issue is one validation finding.
type Issue struct {
	Route, Kind, Detail string
}

// RouteReport separates hard errors from shadowing warnings.
type RouteReport struct {
	Errors, Shadowed []Issue
}

// Valid reports whether the table can be published as-is.
func (r RouteReport) Valid() bool { return len(r.Errors) == 0 }

// CheckRoutes validates references, match syntax, duplicate matches and
// unreachable routes. strictShadow promotes shadowing to a hard error.
func CheckRoutes(t RouteTable, strictShadow bool) RouteReport {
	var rep RouteReport
	names, matches := make(map[string]bool), make(map[string]string)
	for _, rt := range t.Routes {
		if rt.Name == "" || names[rt.Name] {
			rep.Errors = append(rep.Errors, Issue{rt.Name, "duplicate_name", "route name is empty or reused"})
		}
		names[rt.Name] = true
		if !strings.HasPrefix(rt.Prefix, "/") {
			rep.Errors = append(rep.Errors, Issue{rt.Name, "bad_prefix", "prefix must start with /"})
		}
		if rt.Action.Cluster == "" || !t.Clusters[rt.Action.Cluster] {
			rep.Errors = append(rep.Errors, Issue{rt.Name, "unknown_cluster", "action cluster is missing or undefined"})
		}
		if rt.Action.Weight < 0 {
			rep.Errors = append(rep.Errors, Issue{rt.Name, "bad_weight", "weight must not be negative"})
		}
		for k, v := range rt.Headers {
			if k == "" || v == "" {
				rep.Errors = append(rep.Errors, Issue{rt.Name, "bad_header", "header name and value must be non-empty"})
			}
		}
		key := matchKey(rt)
		if prev, ok := matches[key]; ok {
			rep.Errors = append(rep.Errors, Issue{rt.Name, "duplicate_match", "same match as " + prev})
		} else {
			matches[key] = rt.Name
		}
	}
	for i := 0; i < len(t.Routes); i++ {
		for j := i + 1; j < len(t.Routes); j++ {
			a, b := t.Routes[i], t.Routes[j]
			if !covers(a, b) {
				continue
			}
			iss := Issue{b.Name, "shadowed", "never reached; " + a.Name + " matches first"}
			if strictShadow {
				rep.Errors = append(rep.Errors, iss)
			} else {
				rep.Shadowed = append(rep.Shadowed, iss)
			}
		}
	}
	return rep
}

// covers reports whether every request matched by b is also matched by a.
func covers(a, b Route) bool {
	if a.Host != "" && a.Host != b.Host {
		return false
	}
	if !strings.HasPrefix(b.Prefix, a.Prefix) {
		return false
	}
	for k, v := range a.Headers {
		if b.Headers[k] != v {
			return false
		}
	}
	return true
}

func matchKey(rt Route) string {
	keys := make([]string, 0, len(rt.Headers))
	for k := range rt.Headers {
		keys = append(keys, k)
	}
	sort.Strings(keys)
	var sb strings.Builder
	sb.WriteString(rt.Host + "\x00" + rt.Prefix)
	for _, k := range keys {
		sb.WriteString("\x00" + k + "=" + rt.Headers[k])
	}
	return sb.String()
}

// MeshCostInput holds example values for a sidecar mesh cost model.
type MeshCostInput struct {
	Pods                   int
	CPUMillicoresPerPod    float64
	MemoryMiBPerPod        float64
	NodeCPUCores           float64
	NodeMemoryMiB          float64
	ConfigChangesPerDay    int
	ReviewMinutesPerChange float64
	DaysPerMonth           float64
}

// MeshCost is a monthly estimate, not a measurement.
type MeshCost struct {
	SidecarCPUCores, SidecarMemoryMiB       float64
	CPUNodeEquivalent, MemoryNodeEquivalent float64
	CapacityNodes, ReviewHoursPerMonth      float64
}

// EstimateMeshCost converts sidecar quotas and config review effort into
// capacity and human-hour estimates. Zero DaysPerMonth defaults to 30.
func EstimateMeshCost(in MeshCostInput) (MeshCost, error) {
	if in.Pods < 0 || in.CPUMillicoresPerPod < 0 || in.MemoryMiBPerPod < 0 {
		return MeshCost{}, fmt.Errorf("discovery: pod counts and sidecar resources must not be negative")
	}
	if in.NodeCPUCores <= 0 || in.NodeMemoryMiB <= 0 {
		return MeshCost{}, fmt.Errorf("discovery: node capacity must be positive")
	}
	if in.ConfigChangesPerDay < 0 || in.ReviewMinutesPerChange < 0 {
		return MeshCost{}, fmt.Errorf("discovery: review inputs must not be negative")
	}
	days := in.DaysPerMonth
	if days == 0 {
		days = 30
	}
	cost := MeshCost{
		SidecarCPUCores:     float64(in.Pods) * in.CPUMillicoresPerPod / 1000,
		SidecarMemoryMiB:    float64(in.Pods) * in.MemoryMiBPerPod,
		ReviewHoursPerMonth: float64(in.ConfigChangesPerDay) * days * in.ReviewMinutesPerChange / 60,
	}
	cost.CPUNodeEquivalent = cost.SidecarCPUCores / in.NodeCPUCores
	cost.MemoryNodeEquivalent = cost.SidecarMemoryMiB / in.NodeMemoryMiB
	cost.CapacityNodes = math.Max(cost.CPUNodeEquivalent, cost.MemoryNodeEquivalent)
	return cost, nil
}

// file: internal/platform/discovery/routing_test.go
// tier: L1
// verify: go test ./internal/platform/discovery/ -count=1
package discovery

import "math"
import "testing"

func hasKind(issues []Issue, kind string) bool {
	for _, iss := range issues {
		if iss.Kind == kind {
			return true
		}
	}
	return false
}

func TestCheckRoutesRejectsBrokenTable(t *testing.T) {
	table := RouteTable{
		Clusters: map[string]bool{"orders": true},
		Routes: []Route{
			{Name: "bad-prefix", Prefix: "api", Action: RouteAction{"orders", 1}},
			{Name: "bad-prefix", Prefix: "/dup-name", Action: RouteAction{"orders", 1}},
			{Name: "ghost", Prefix: "/missing", Action: RouteAction{"inventory", 1}},
			{Name: "base", Prefix: "/api", Action: RouteAction{"orders", 1}},
			{Name: "same", Prefix: "/api", Action: RouteAction{"orders", 1}},
			{Name: "bad-header", Prefix: "/api/v2", Headers: map[string]string{"x-tenant": ""}, Action: RouteAction{"orders", 1}},
		},
	}
	rep := CheckRoutes(table, true)
	for _, kind := range []string{"bad_prefix", "duplicate_name", "unknown_cluster", "duplicate_match", "bad_header", "shadowed"} {
		if !hasKind(rep.Errors, kind) {
			t.Errorf("missing error kind %q in %+v", kind, rep.Errors)
		}
	}
	if rep.Valid() {
		t.Fatal("broken table reported valid")
	}
}

func TestCheckRoutesShadowing(t *testing.T) {
	table := RouteTable{
		Clusters: map[string]bool{"orders": true},
		Routes: []Route{
			{Name: "broad", Prefix: "/api", Action: RouteAction{"orders", 1}},
			{Name: "narrow", Prefix: "/api/orders", Action: RouteAction{"orders", 1}},
		},
	}
	rep := CheckRoutes(table, false)
	if len(rep.Shadowed) != 1 || rep.Shadowed[0].Route != "narrow" {
		t.Fatalf("shadowed=%+v, want narrow", rep.Shadowed)
	}
	if !rep.Valid() {
		t.Fatalf("warning-only report is invalid: %+v", rep.Errors)
	}
	if strict := CheckRoutes(table, true); strict.Valid() {
		t.Fatal("strict mode accepted a shadowed route")
	}
	reordered := RouteTable{Clusters: table.Clusters, Routes: []Route{table.Routes[1], table.Routes[0]}}
	if rep := CheckRoutes(reordered, true); !rep.Valid() || len(rep.Shadowed) != 0 {
		t.Fatalf("narrow-first errors=%+v shadowed=%+v", rep.Errors, rep.Shadowed)
	}
}

func TestEstimateMeshCost(t *testing.T) {
	cost, err := EstimateMeshCost(MeshCostInput{
		Pods: 120, CPUMillicoresPerPod: 50, MemoryMiBPerPod: 80,
		NodeCPUCores: 16, NodeMemoryMiB: 65536,
		ConfigChangesPerDay: 5, ReviewMinutesPerChange: 15, DaysPerMonth: 30,
	})
	if err != nil {
		t.Fatalf("EstimateMeshCost: %v", err)
	}
	checks := []struct {
		name string
		got  float64
		want float64
	}{
		{"cpu cores", cost.SidecarCPUCores, 6},
		{"memory MiB", cost.SidecarMemoryMiB, 9600},
		{"cpu node equivalent", cost.CPUNodeEquivalent, 0.375},
		{"memory node equivalent", cost.MemoryNodeEquivalent, 9600.0 / 65536.0},
		{"capacity nodes", cost.CapacityNodes, 0.375},
		{"review hours", cost.ReviewHoursPerMonth, 37.5},
	}
	for _, c := range checks {
		if math.Abs(c.got-c.want) > 1e-9 {
			t.Errorf("%s=%v, want %v", c.name, c.got, c.want)
		}
	}
	if _, err := EstimateMeshCost(MeshCostInput{NodeCPUCores: 0}); err == nil {
		t.Fatal("zero node capacity accepted")
	}
}

$ cd .local/checks/be-arch-gov-ch03
$ gofmt -l . && go vet ./... && go test ./internal/platform/discovery/ -count=1 -v -run '^(TestCheckRoutes|TestEstimateMeshCost)'
=== RUN   TestCheckRoutesRejectsBrokenTable
--- PASS: TestCheckRoutesRejectsBrokenTable (0.00s)
=== RUN   TestCheckRoutesShadowing
--- PASS: TestCheckRoutesShadowing (0.00s)
=== RUN   TestEstimateMeshCost
--- PASS: TestEstimateMeshCost (0.00s)
PASS
ok  	archlab/internal/platform/discovery	0.262s