《游戏服务端架构·品类、状态与拓扑》2.2 ADR：把决策、备选与后果写下来

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

import (
	"fmt"
	"strings"
)

// Status is the lifecycle state of a decision record.
type Status string

const (
	Proposed   Status = "proposed"
	Accepted   Status = "accepted"
	Rejected   Status = "rejected"
	Superseded Status = "superseded"
)

var validStatuses = map[Status]bool{
	Proposed:   true,
	Accepted:   true,
	Rejected:   true,
	Superseded: true,
}

// Alternative is an option that was seriously considered. The rejection
// reason is mandatory: options listed after the fact are not alternatives.
type Alternative struct {
	Name            string
	RejectedBecause string
}

// ADR is the minimum record for a durable decision. ExitConditions is what
// makes the decision revisitable.
type ADR struct {
	ID             string
	Title          string
	Status         Status
	Context        string
	Alternatives   []Alternative
	Decision       string
	Consequences   []string
	ExitConditions []string
}

func (a ADR) Validate() error {
	var missing []string
	add := func(name, value string) {
		if strings.TrimSpace(value) == "" {
			missing = append(missing, name)
		}
	}
	add("id", a.ID)
	add("title", a.Title)
	add("status", string(a.Status))
	add("context", a.Context)
	add("decision", a.Decision)
	if len(missing) > 0 {
		return fmt.Errorf("ADR %q: missing %s", a.ID, strings.Join(missing, ", "))
	}
	if !validStatuses[a.Status] {
		return fmt.Errorf("ADR %q: unknown status %q", a.ID, a.Status)
	}
	if len(a.Alternatives) < 2 {
		return fmt.Errorf("ADR %q: needs at least two alternatives, got %d", a.ID, len(a.Alternatives))
	}
	for i, alt := range a.Alternatives {
		if strings.TrimSpace(alt.Name) == "" {
			return fmt.Errorf("ADR %q: alternative %d has no name", a.ID, i+1)
		}
		if strings.TrimSpace(alt.RejectedBecause) == "" {
			return fmt.Errorf("ADR %q: alternative %q has no rejection reason", a.ID, alt.Name)
		}
	}
	if len(a.Consequences) == 0 {
		return fmt.Errorf("ADR %q: missing consequences", a.ID)
	}
	if len(a.ExitConditions) == 0 {
		return fmt.Errorf("ADR %q: missing exit conditions", a.ID)
	}
	for i, c := range a.ExitConditions {
		if strings.TrimSpace(c) == "" {
			return fmt.Errorf("ADR %q: exit condition %d is empty", a.ID, i+1)
		}
	}
	return nil
}

// ValidateAll also enforces unique IDs.
func ValidateAll(records []ADR) []error {
	var errs []error
	seen := make(map[string]bool, len(records))
	for _, a := range records {
		if err := a.Validate(); err != nil {
			errs = append(errs, err)
			continue
		}
		if seen[a.ID] {
			errs = append(errs, fmt.Errorf("ADR %q: duplicate id", a.ID))
			continue
		}
		seen[a.ID] = true
	}
	return errs
}

// file: internal/adr/adr_test.go
// tier: L1
// verify: go test ./internal/adr/
package adr

import (
	"strings"
	"testing"
)

func validADR() ADR {
	return ADR{
		ID:     "ADR-005",
		Title:  "匹配状态由匹配服务独占",
		Status: Accepted,
		Context: "《群岛纪元》跨地域匹配需要持久化匹配票据，" +
			"世界分片不能各自维护一份。",
		Alternatives: []Alternative{
			{Name: "世界分片持有匹配状态", RejectedBecause: "跨分片匹配没有单一权威，状态会分叉"},
			{Name: "匹配票据放共享 Redis", RejectedBecause: "原子转移与审计困难，故障时无法判断归属"},
		},
		Decision:       "匹配服务独占匹配票据，世界分片只通过命令和事件交互。",
		Consequences:   []string{"匹配服务成为有状态服务，发布需要排空", "世界分片多一次网络调用"},
		ExitConditions: []string{"匹配 p99 因服务跳转连续一周超过 2 秒", "跨地域匹配下线，单分片可独立完成匹配"},
	}
}

func TestValidateRejectsMissingExitConditions(t *testing.T) {
	cases := []struct {
		name string
		set  func(*ADR)
	}{
		{"nil", func(a *ADR) { a.ExitConditions = nil }},
		{"blank", func(a *ADR) { a.ExitConditions = []string{"  "} }},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			a := validADR()
			c.set(&a)
			err := a.Validate()
			if err == nil || !strings.Contains(err.Error(), "exit condition") {
				t.Fatalf("got %v, want missing exit conditions", err)
			}
		})
	}
}

func TestValidateRejectsWeakAlternatives(t *testing.T) {
	cases := []struct {
		name   string
		mutate func(*ADR)
		want   string
	}{
		{"single", func(a *ADR) { a.Alternatives = a.Alternatives[:1] }, "two alternatives"},
		{"no-reason", func(a *ADR) { a.Alternatives[0].RejectedBecause = "" }, "rejection reason"},
	}
	for _, c := range cases {
		a := validADR()
		c.mutate(&a)
		err := a.Validate()
		if err == nil || !strings.Contains(err.Error(), c.want) {
			t.Fatalf("%s: got %v, want %s", c.name, err, c.want)
		}
	}
}

func TestValidateRejectsBadStatusOrMissingConsequences(t *testing.T) {
	a := validADR()
	a.Status = "done"
	if err := a.Validate(); err == nil {
		t.Fatal("unknown status was accepted")
	}
	b := validADR()
	b.Consequences = nil
	err := b.Validate()
	if err == nil || !strings.Contains(err.Error(), "consequences") {
		t.Fatalf("got %v, want consequences error", err)
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l .
$ go vet ./...
$ go test ./internal/adr/ -count=1
ok  	gsarchlab/internal/adr	0.755s