《后端架构设计·架构基础与边界》11.1 部署单元与故障域：订单系统怎么切

// file: internal/deploymap/deploymap.go
// tier: L1
// verify: go test ./internal/deploymap/
package deploymap

import (
	"fmt"
	"sort"
)

// Unit 是一个可以独立发布、独立扩容、独立失败的最小运行时单位。
// AcceptedSPOF 不是豁免，而是要求把恢复手段写出来。
type Unit struct {
	Name           string
	Replicas       int
	Zones          []string
	AcceptedSPOF   bool
	SPOFMitigation string
}

// CallKind 只区分同步与异步：同步会把下游延迟和故障传回调用方，
// 异步则把两者隔开，这是发布影响面计算的核心区别。
type CallKind string

const (
	Sync  CallKind = "SYNC"
	Async CallKind = "ASYNC"
)

// Dependency 中 Required 表示失败会阻断调用方核心路径；TimeoutMS 为 0
// 表示没有上限；Fallback 为空表示没有设计降级路径。
type Dependency struct {
	From      string
	To        string
	Kind      CallKind
	Required  bool
	TimeoutMS int
	Fallback  string
}

type Plan struct {
	Units []Unit
	Deps  []Dependency
}

type Finding struct {
	Code    string
	Subject string
	Detail  string
}

// Validate 一次返回全部问题：一个未声明单点往往同时带来故障域重叠。
func (p Plan) Validate() []Finding {
	var out []Finding
	seen := make(map[string]bool, 8)
	add := func(code, subject, detail string) {
		key := code + "\x00" + subject
		if !seen[key] {
			seen[key] = true
			out = append(out, Finding{Code: code, Subject: subject, Detail: detail})
		}
	}

	units := make(map[string]Unit, len(p.Units))
	for _, u := range p.Units {
		units[u.Name] = u
		if u.Replicas <= 1 && !u.AcceptedSPOF {
			add("UNDECLARED_SPOF", u.Name, fmt.Sprintf("replicas=%d", u.Replicas))
		}
		// 多副本全挤在一个可用区，副本数只是账面数字。
		if zones := unique(u.Zones); u.Replicas >= 2 && len(zones) == 1 {
			add("ZONE_CONCENTRATION", u.Name, "all replicas in "+zones[0])
		}
	}

	for _, d := range p.Deps {
		from, okFrom := units[d.From]
		to, okTo := units[d.To]
		if !okFrom || !okTo || d.From == d.To || d.Kind != Sync || !d.Required {
			continue
		}
		subject := d.From + " -> " + d.To
		// 跨单元强依赖不是“有调用”就算问题，而是既无超时又无降级时，
		// 下游的故障会无界地传成上游的故障。
		switch {
		case d.TimeoutMS <= 0:
			add("CROSS_UNIT_STRONG_DEP", subject, "required sync call has no timeout")
		case d.Fallback == "":
			add("CROSS_UNIT_STRONG_DEP", subject, "required sync call has no fallback")
		}
		z1, ok1 := onlyZone(from)
		z2, ok2 := onlyZone(to)
		if ok1 && ok2 && z1 == z2 {
			add("FAILURE_DOMAIN_OVERLAP", subject, "both units only in "+z1)
		}
	}
	return out
}

// BlastRadius 返回某单元发布或故障时，会被同步调用链拖住的单元集合。
// 异步边被刻意排除：消息积压是运维问题，不是调用方不可用。
func (p Plan) BlastRadius(name string) []string {
	reverse := make(map[string][]string, len(p.Deps))
	for _, d := range p.Deps {
		if d.Kind == Sync && d.Required {
			reverse[d.To] = append(reverse[d.To], d.From)
		}
	}
	seen := map[string]bool{name: true}
	queue := []string{name}
	var out []string
	for len(queue) > 0 {
		cur := queue[0]
		queue = queue[1:]
		for _, caller := range reverse[cur] {
			if !seen[caller] {
				seen[caller] = true
				out = append(out, caller)
				queue = append(queue, caller)
			}
		}
	}
	sort.Strings(out)
	return out
}

func onlyZone(u Unit) (string, bool) {
	zones := unique(u.Zones)
	if len(zones) != 1 {
		return "", false
	}
	return zones[0], true
}

func unique(values []string) []string {
	seen := make(map[string]bool, len(values))
	out := make([]string, 0, len(values))
	for _, v := range values {
		if v != "" && !seen[v] {
			seen[v] = true
			out = append(out, v)
		}
	}
	return out
}

// file: internal/deploymap/deploymap_test.go
// tier: L1
// verify: go test ./internal/deploymap/
package deploymap

import (
	"strings"
	"testing"
)

// baseline 是 arch-lab 在 2026-10 的部署图：四个业务单元、三个数据单元。
// 三个库各有单主，但都登记为可接受单点并写明恢复手段。
func baseline() Plan {
	return Plan{
		Units: []Unit{
			{Name: "order-api", Replicas: 3, Zones: []string{"az-a", "az-b", "az-c"}},
			{Name: "catalog-svc", Replicas: 2, Zones: []string{"az-a", "az-b"}},
			{Name: "inventory-svc", Replicas: 3, Zones: []string{"az-a", "az-b", "az-c"}},
			{Name: "payment-worker", Replicas: 2, Zones: []string{"az-a", "az-b"}},
			{Name: "orders-db", Replicas: 1, Zones: []string{"az-a"}, AcceptedSPOF: true, SPOFMitigation: "managed failover, WAL archive, RTO 90s, RPO 5min"},
			{Name: "catalog-db", Replicas: 1, Zones: []string{"az-b"}, AcceptedSPOF: true, SPOFMitigation: "managed failover, nightly snapshot, RTO 15min, RPO 24h"},
			{Name: "inventory-db", Replicas: 1, Zones: []string{"az-c"}, AcceptedSPOF: true, SPOFMitigation: "managed failover, WAL archive, RTO 90s, RPO 5min"},
		},
		Deps: []Dependency{
			{From: "order-api", To: "catalog-svc", Kind: Sync, Required: true, TimeoutMS: 300, Fallback: "cached price, max 5m stale"},
			{From: "order-api", To: "inventory-svc", Kind: Sync, Required: true, TimeoutMS: 800, Fallback: "reject with INVENTORY_UNAVAILABLE"},
			{From: "order-api", To: "payment-worker", Kind: Async, Required: false},
			{From: "order-api", To: "orders-db", Kind: Sync, Required: true, TimeoutMS: 1000, Fallback: "fail request"},
			{From: "catalog-svc", To: "catalog-db", Kind: Sync, Required: true, TimeoutMS: 500, Fallback: "serve cached catalog"},
			{From: "inventory-svc", To: "inventory-db", Kind: Sync, Required: true, TimeoutMS: 1000, Fallback: "fail reservation"},
			{From: "payment-worker", To: "orders-db", Kind: Sync, Required: true, TimeoutMS: 2000, Fallback: "outbox retry"},
			{From: "payment-worker", To: "inventory-svc", Kind: Async, Required: false},
		},
	}
}

func TestBaselineIsClean(t *testing.T) {
	p := baseline()
	strong := 0
	for _, d := range p.Deps {
		if d.Kind == Sync && d.Required && d.From != d.To {
			strong++
		}
	}
	findings := p.Validate()
	t.Logf("units=%d deps=%d strong_cross_unit=%d findings=%d",
		len(p.Units), len(p.Deps), strong, len(findings))
	if len(findings) != 0 {
		t.Fatalf("baseline should be clean, got %v", findings)
	}
}

func TestValidateCatchesDeploymentDrift(t *testing.T) {
	cases := []struct {
		name    string
		mutate  func(*Plan)
		code    string
		subject string
	}{
		{"single point without declaration", func(p *Plan) {
			u := unitIndex(p, "orders-db")
			p.Units[u].AcceptedSPOF, p.Units[u].SPOFMitigation = false, ""
		}, "UNDECLARED_SPOF", "orders-db"},
		{"replicas in one zone", func(p *Plan) {
			p.Units[unitIndex(p, "catalog-svc")].Zones = []string{"az-a"}
		}, "ZONE_CONCENTRATION", "catalog-svc"},
		{"strong dependency without timeout", func(p *Plan) {
			p.Deps[depIndex(p, "order-api", "inventory-svc")].TimeoutMS = 0
		}, "CROSS_UNIT_STRONG_DEP", "order-api -> inventory-svc"},
		{"strong dependency without fallback", func(p *Plan) {
			p.Deps[depIndex(p, "payment-worker", "orders-db")].Fallback = ""
		}, "CROSS_UNIT_STRONG_DEP", "payment-worker -> orders-db"},
		{"database and caller in same zone", func(p *Plan) {
			p.Units[unitIndex(p, "inventory-svc")].Zones = []string{"az-c"}
		}, "FAILURE_DOMAIN_OVERLAP", "inventory-svc -> inventory-db"},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			p := baseline()
			tc.mutate(&p)
			if !has(p.Validate(), tc.code, tc.subject) {
				t.Fatalf("want %s on %q, got %v", tc.code, tc.subject, p.Validate())
			}
		})
	}
}

func TestBlastRadiusFollowsSyncEdgesOnly(t *testing.T) {
	p := baseline()
	want := map[string]string{
		"catalog-svc":    "order-api",
		"orders-db":      "order-api,payment-worker",
		"inventory-db":   "inventory-svc,order-api",
		"payment-worker": "",
	}
	for unit, w := range want {
		if got := strings.Join(p.BlastRadius(unit), ","); got != w {
			t.Fatalf("%s: want %q, got %q", unit, w, got)
		}
	}
}

func unitIndex(p *Plan, name string) int {
	for i := range p.Units {
		if p.Units[i].Name == name {
			return i
		}
	}
	panic(name)
}

func depIndex(p *Plan, from, to string) int {
	for i := range p.Deps {
		if p.Deps[i].From == from && p.Deps[i].To == to {
			return i
		}
	}
	panic(from + " -> " + to)
}

func has(findings []Finding, code, subject string) bool {
	for _, f := range findings {
		if f.Code == code && f.Subject == subject {
			return true
		}
	}
	return false
}

$ go test ./internal/deploymap/ -run TestBaselineIsClean -v
=== RUN   TestBaselineIsClean
    deploymap_test.go:46: units=7 deps=8 strong_cross_unit=6 findings=0
--- PASS: TestBaselineIsClean (0.00s)
PASS
ok  	archlab/internal/deploymap	0.308s