《后端架构设计·架构基础与边界》3.1 子域、限界上下文与团队边界

// file: internal/contextmap/map.go
// tier: L1
// verify: go test ./internal/contextmap/
package contextmap

import (
	"fmt"
	"strings"
)

type Kind string

const (
	KindCore       Kind = "CORE"
	KindSupporting Kind = "SUPPORTING"
	KindGeneric    Kind = "GENERIC"
)

type Pattern string

const (
	PatternPartnership      Pattern = "PARTNERSHIP"
	PatternCustomerSupplier Pattern = "CUSTOMER_SUPPLIER"
	PatternACL              Pattern = "ANTICORRUPTION_LAYER"
	PatternSharedKernel     Pattern = "SHARED_KERNEL"
)

type Context struct {
	Name    string
	Kind    Kind
	Owner   string
	Package string
	Owns    []string
}

type Dependency struct {
	Upstream   string
	Downstream string
	Pattern    Pattern
	Reason     string
}

type SharedKernel struct {
	Name    string
	Owner   string
	Members []string
}

type Map struct {
	Contexts []Context
	Deps     []Dependency
	Kernels  []SharedKernel
}

// Validate 返回全部违规，而不是遇到第一条就退出：一次修完比来回跑 CI 便宜。
func (m Map) Validate() []string {
	var out []string
	byName := make(map[string]Context, len(m.Contexts))
	byPackage := make(map[string]string, len(m.Contexts))

	for _, c := range m.Contexts {
		if _, dup := byName[c.Name]; dup {
			out = append(out, "duplicate context "+c.Name)
		}
		byName[c.Name] = c
		if c.Owner == "" {
			out = append(out, "missing owner "+c.Name)
		}
		if prev, used := byPackage[c.Package]; used {
			out = append(out, fmt.Sprintf("package %s used by %s and %s", c.Package, prev, c.Name))
		}
		byPackage[c.Package] = c.Name
	}

	for _, d := range m.Deps {
		if _, ok := byName[d.Upstream]; !ok {
			out = append(out, "unknown upstream "+d.Upstream)
		}
		if _, ok := byName[d.Downstream]; !ok {
			out = append(out, "unknown downstream "+d.Downstream)
		}
		if d.Upstream == d.Downstream {
			out = append(out, "self dependency "+d.Upstream)
		}
	}

	for _, k := range m.Kernels {
		if len(k.Members) < 2 {
			out = append(out, "kernel too small "+k.Name)
		}
		for _, member := range k.Members {
			if _, ok := byName[member]; !ok {
				out = append(out, "unknown kernel member "+k.Name+"."+member)
			}
		}
	}

	for _, d := range m.Deps {
		if d.Pattern == PatternSharedKernel && !sharesKernel(m.Kernels, d.Upstream, d.Downstream) {
			out = append(out, "undeclared shared kernel "+d.Upstream+" -> "+d.Downstream)
		}
	}
	return append(out, m.cycles()...)
}

func sharesKernel(kernels []SharedKernel, a, b string) bool {
	for _, k := range kernels {
		if contains(k.Members, a) && contains(k.Members, b) {
			return true
		}
	}
	return false
}

func contains(values []string, want string) bool {
	for _, v := range values {
		if v == want {
			return true
		}
	}
	return false
}

func (m Map) cycles() []string {
	adj := make(map[string][]string, len(m.Contexts))
	for _, d := range m.Deps {
		adj[d.Downstream] = append(adj[d.Downstream], d.Upstream)
	}
	const white, gray, black = 0, 1, 2
	color := make(map[string]int, len(m.Contexts))
	var stack []string
	var out []string

	var visit func(string)
	visit = func(node string) {
		color[node] = gray
		stack = append(stack, node)
		for _, next := range adj[node] {
			switch color[next] {
			case white:
				visit(next)
			case gray:
				begin := 0
				for i, n := range stack {
					if n == next {
						begin = i
						break
					}
				}
				path := append(append([]string(nil), stack[begin:]...), next)
				out = append(out, "dependency cycle "+strings.Join(path, " -> "))
			}
		}
		stack = stack[:len(stack)-1]
		color[node] = black
	}
	for _, c := range m.Contexts {
		if color[c.Name] == white {
			visit(c.Name)
		}
	}
	return out
}

// file: internal/contextmap/map_test.go
// tier: L1
// verify: go test ./internal/contextmap/ -v
package contextmap

import (
	"strings"
	"testing"
)

func archLabMap() Map {
	return Map{
		Contexts: []Context{
			{Name: "order", Kind: KindCore, Owner: "team-order", Package: "internal/order",
				Owns: []string{"orders", "order_items", "order_status_history"}},
			{Name: "catalog", Kind: KindCore, Owner: "team-catalog", Package: "internal/catalog",
				Owns: []string{"sku", "price_book"}},
			{Name: "inventory", Kind: KindSupporting, Owner: "team-inventory", Package: "internal/inventory",
				Owns: []string{"stock", "inventory_reservations"}},
			{Name: "fulfillment", Kind: KindSupporting, Owner: "team-fulfillment", Package: "internal/fulfillment",
				Owns: []string{"shipments", "shipment_items"}},
			{Name: "payment", Kind: KindGeneric, Owner: "team-payments", Package: "internal/payment",
				Owns: []string{"payments", "provider_refs"}},
			{Name: "identity", Kind: KindGeneric, Owner: "team-identity", Package: "internal/identity",
				Owns: []string{"accounts", "credentials"}},
			{Name: "notification", Kind: KindGeneric, Owner: "team-notify", Package: "internal/notification",
				Owns: []string{"templates", "delivery_log"}},
		},
		Deps: []Dependency{
			{Upstream: "catalog", Downstream: "order", Pattern: PatternCustomerSupplier, Reason: "下单读取 SKU 与价格"},
			{Upstream: "order", Downstream: "inventory", Pattern: PatternCustomerSupplier, Reason: "预留与释放命令"},
			{Upstream: "order", Downstream: "fulfillment", Pattern: PatternCustomerSupplier, Reason: "履约任务"},
			{Upstream: "order", Downstream: "payment", Pattern: PatternCustomerSupplier, Reason: "扣款与退款命令"},
			{Upstream: "identity", Downstream: "order", Pattern: PatternACL, Reason: "订单只保存 CustomerID"},
			{Upstream: "order", Downstream: "notification", Pattern: PatternCustomerSupplier, Reason: "订阅订单事件"},
			{Upstream: "order", Downstream: "payment", Pattern: PatternSharedKernel, Reason: "共用 Money 值对象"},
		},
		Kernels: []SharedKernel{
			{Name: "money", Owner: "team-platform", Members: []string{"order", "catalog", "payment", "fulfillment"}},
		},
	}
}

func has(violations []string, fragment string) bool {
	for _, v := range violations {
		if strings.Contains(v, fragment) {
			return true
		}
	}
	return false
}

func TestArchLabMapIsValid(t *testing.T) {
	if violations := archLabMap().Validate(); len(violations) != 0 {
		t.Fatalf("arch-lab map should be valid, got %v", violations)
	}
}

func TestValidateTable(t *testing.T) {
	tests := []struct {
		name   string
		mutate func(*Map)
		want   string
	}{
		{"duplicate context", func(m *Map) { m.Contexts = append(m.Contexts, m.Contexts[0]) }, "duplicate context order"},
		{"missing owner", func(m *Map) { m.Contexts[0].Owner = "" }, "missing owner order"},
		{"duplicate package", func(m *Map) { m.Contexts[1].Package = m.Contexts[0].Package }, "used by order and catalog"},
		{"unknown dependency", func(m *Map) {
			m.Deps = append(m.Deps, Dependency{Upstream: "ghost", Downstream: "order", Pattern: PatternCustomerSupplier})
		}, "unknown upstream ghost"},
		{"self dependency", func(m *Map) {
			m.Deps = append(m.Deps, Dependency{Upstream: "order", Downstream: "order", Pattern: PatternCustomerSupplier})
		}, "self dependency order"},
		{"unknown kernel member", func(m *Map) {
			m.Kernels[0].Members = append(m.Kernels[0].Members, "ghost")
		}, "unknown kernel member money.ghost"},
		{"undeclared shared kernel", func(m *Map) {
			m.Deps = append(m.Deps, Dependency{Upstream: "inventory", Downstream: "fulfillment", Pattern: PatternSharedKernel})
		}, "undeclared shared kernel inventory -> fulfillment"},
		{"dependency cycle", func(m *Map) {
			m.Deps = append(m.Deps, Dependency{Upstream: "inventory", Downstream: "order", Pattern: PatternCustomerSupplier})
		}, "dependency cycle order -> inventory -> order"},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			m := archLabMap()
			tt.mutate(&m)
			if violations := m.Validate(); !has(violations, tt.want) {
				t.Fatalf("violations = %v, want %q", violations, tt.want)
			}
		})
	}
}

=== RUN   TestArchLabMapIsValid
--- PASS: TestArchLabMapIsValid (0.00s)
=== RUN   TestValidateTable
=== RUN   TestValidateTable/dependency_cycle
--- PASS: TestValidateTable (0.00s)
    --- PASS: TestValidateTable/dependency_cycle (0.00s)
PASS
ok  	archlab/internal/contextmap	0.455s