《后端架构设计·演进与治理》2.2 契约版本演进：向后兼容、弃用与消费者驱动

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

import (
	"fmt"
	"sort"
	"strings"
)

// ValueType mirrors JSON, not Go, because the contract crosses languages.
type ValueType string

const (
	TypeString ValueType = "string"
	TypeInt    ValueType = "int"
	TypeFloat  ValueType = "float"
	TypeBool   ValueType = "bool"
	TypeObject ValueType = "object"
	TypeArray  ValueType = "array"
)

func (t ValueType) valid() bool {
	switch t {
	case TypeString, TypeInt, TypeFloat, TypeBool, TypeObject, TypeArray:
		return true
	}
	return false
}

// FieldSpec is one field in one schema version. Required means the producer
// always sends it and the consumer may fail when it is absent.
type FieldSpec struct {
	Name     string
	Type     ValueType
	Required bool
}

// Schema is one version of a message contract.
type Schema struct {
	Name    string
	Version string
	Fields  []FieldSpec
}

// Validate rejects schemas that cannot be compared meaningfully.
func (s Schema) Validate() error {
	if strings.TrimSpace(s.Name) == "" {
		return fmt.Errorf("contract: schema name is empty")
	}
	if strings.TrimSpace(s.Version) == "" {
		return fmt.Errorf("contract: schema %q has no version", s.Name)
	}
	seen := make(map[string]bool, len(s.Fields))
	for _, f := range s.Fields {
		if strings.TrimSpace(f.Name) == "" {
			return fmt.Errorf("contract: schema %q has an empty field name", s.Name)
		}
		if seen[f.Name] {
			return fmt.Errorf("contract: schema %q has duplicate field %q", s.Name, f.Name)
		}
		seen[f.Name] = true
		if !f.Type.valid() {
			return fmt.Errorf("contract: schema %q field %q has invalid type %q", s.Name, f.Name, f.Type)
		}
	}
	return nil
}

// CompatVerdict is the strongest statement the checker can make.
type CompatVerdict string

const (
	VerdictFull     CompatVerdict = "full"     // both directions safe
	VerdictBackward CompatVerdict = "backward" // new reader reads old data
	VerdictForward  CompatVerdict = "forward"  // old reader reads new data
	VerdictBreaking CompatVerdict = "breaking" // neither direction safe
)

// FieldChange records one difference and its effect on each direction.
// Readers ignore unknown fields and reject missing required fields.
type FieldChange struct {
	Field    string
	Kind     string
	Backward bool
	Forward  bool
}

// CompatReport is the machine-readable result a CI job can gate on.
type CompatReport struct {
	From     string
	To       string
	Backward bool
	Forward  bool
	Verdict  CompatVerdict
	Changes  []FieldChange
}

// CheckCompatibility compares two versions of the same schema. It does not
// guess intent: adding an optional field is full-compatible, adding a
// required field is forward-only, and a type change is breaking unless the
// field is introduced under a new name.
func CheckCompatibility(old, new Schema) (CompatReport, error) {
	if err := old.Validate(); err != nil {
		return CompatReport{}, fmt.Errorf("old: %w", err)
	}
	if err := new.Validate(); err != nil {
		return CompatReport{}, fmt.Errorf("new: %w", err)
	}
	if old.Name != new.Name {
		return CompatReport{}, fmt.Errorf("contract: cannot compare %q with %q", old.Name, new.Name)
	}

	index := func(fields []FieldSpec) map[string]FieldSpec {
		m := make(map[string]FieldSpec, len(fields))
		for _, f := range fields {
			m[f.Name] = f
		}
		return m
	}
	oldFields, newFields := index(old.Fields), index(new.Fields)
	names := make([]string, 0, len(oldFields)+len(newFields))
	for name := range oldFields {
		names = append(names, name)
	}
	for name := range newFields {
		if _, ok := oldFields[name]; !ok {
			names = append(names, name)
		}
	}
	sort.Strings(names)

	report := CompatReport{From: old.Version, To: new.Version, Backward: true, Forward: true}
	record := func(c FieldChange) {
		report.Changes = append(report.Changes, c)
		report.Backward = report.Backward && c.Backward
		report.Forward = report.Forward && c.Forward
	}

	for _, name := range names {
		before, inOld := oldFields[name]
		after, inNew := newFields[name]
		switch {
		case !inNew:
			kind := "removed_optional"
			if before.Required {
				kind = "removed_required"
			}
			record(FieldChange{name, kind, true, !before.Required})
		case !inOld:
			kind := "added_optional"
			if after.Required {
				kind = "added_required"
			}
			record(FieldChange{name, kind, !after.Required, true})
		case before.Type != after.Type:
			record(FieldChange{name, "type_changed", false, false})
		case before.Required != after.Required:
			kind := "made_required"
			if !after.Required {
				kind = "made_optional"
			}
			record(FieldChange{name, kind, !after.Required, after.Required})
		}
	}

	switch {
	case report.Backward && report.Forward:
		report.Verdict = VerdictFull
	case report.Backward:
		report.Verdict = VerdictBackward
	case report.Forward:
		report.Verdict = VerdictForward
	default:
		report.Verdict = VerdictBreaking
	}
	return report, nil
}

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

import "testing"

func baseOrderFields() []FieldSpec {
	return []FieldSpec{
		{Name: "id", Type: TypeString, Required: true},
		{Name: "amount", Type: TypeInt, Required: true},
		{Name: "customer", Type: TypeObject, Required: true},
		{Name: "note", Type: TypeString},
	}
}

func withField(fields []FieldSpec, f FieldSpec) []FieldSpec {
	out := append([]FieldSpec(nil), fields...)
	return append(out, f)
}

func withoutField(fields []FieldSpec, name string) []FieldSpec {
	out := make([]FieldSpec, 0, len(fields))
	for _, f := range fields {
		if f.Name != name {
			out = append(out, f)
		}
	}
	return out
}

func replaceField(fields []FieldSpec, f FieldSpec) []FieldSpec {
	out := make([]FieldSpec, 0, len(fields))
	for _, old := range fields {
		if old.Name == f.Name {
			out = append(out, f)
			continue
		}
		out = append(out, old)
	}
	return out
}

func orderSchema(version string, fields []FieldSpec) Schema {
	return Schema{Name: "order.created", Version: version, Fields: fields}
}

func TestCheckCompatibilityVerdicts(t *testing.T) {
	base := orderSchema("v1", baseOrderFields())
	cases := []struct {
		name    string
		next    Schema
		verdict CompatVerdict
		kind    string
	}{
		{"add optional", orderSchema("v2", withField(baseOrderFields(), FieldSpec{Name: "currency", Type: TypeString})), VerdictFull, "added_optional"},
		{"add required", orderSchema("v2", withField(baseOrderFields(), FieldSpec{Name: "currency", Type: TypeString, Required: true})), VerdictForward, "added_required"},
		{"remove required", orderSchema("v2", withoutField(baseOrderFields(), "amount")), VerdictBackward, "removed_required"},
		{"remove optional", orderSchema("v2", withoutField(baseOrderFields(), "note")), VerdictFull, "removed_optional"},
		{"type change", orderSchema("v2", replaceField(baseOrderFields(), FieldSpec{Name: "amount", Type: TypeString, Required: true})), VerdictBreaking, "type_changed"},
		{"optional to required", orderSchema("v2", replaceField(baseOrderFields(), FieldSpec{Name: "note", Type: TypeString, Required: true})), VerdictForward, "made_required"},
		{"required to optional", orderSchema("v2", replaceField(baseOrderFields(), FieldSpec{Name: "amount", Type: TypeInt})), VerdictBackward, "made_optional"},
	}
	for _, tc := range cases {
		report, err := CheckCompatibility(base, tc.next)
		if err != nil {
			t.Fatalf("%s: unexpected error: %v", tc.name, err)
		}
		if report.Verdict != tc.verdict {
			t.Errorf("%s: verdict=%s want=%s", tc.name, report.Verdict, tc.verdict)
		}
		if len(report.Changes) != 1 || report.Changes[0].Kind != tc.kind {
			t.Errorf("%s: changes=%+v want one %s", tc.name, report.Changes, tc.kind)
		}
		t.Logf("%s: %s -> %s verdict=%s backward=%t forward=%t",
			tc.name, report.From, report.To, report.Verdict, report.Backward, report.Forward)
	}
}

func TestCheckCompatibilityNoChange(t *testing.T) {
	base := orderSchema("v1", baseOrderFields())
	report, err := CheckCompatibility(base, orderSchema("v1", baseOrderFields()))
	if err != nil {
		t.Fatal(err)
	}
	if report.Verdict != VerdictFull || len(report.Changes) != 0 {
		t.Fatalf("identical schema must be full, got %s with %d changes", report.Verdict, len(report.Changes))
	}
	t.Logf("identical: verdict=%s changes=%d", report.Verdict, len(report.Changes))
}

func TestCheckCompatibilityRejectsBadInput(t *testing.T) {
	base := orderSchema("v1", baseOrderFields())
	cases := []struct {
		name     string
		old, new Schema
	}{
		{"duplicate field", base, Schema{Name: "order.created", Version: "v2", Fields: []FieldSpec{
			{Name: "id", Type: TypeString}, {Name: "id", Type: TypeString},
		}}},
		{"invalid type", base, orderSchema("v2", withField(baseOrderFields(), FieldSpec{Name: "x", Type: "decimal"}))},
		{"different name", base, Schema{Name: "payment.captured", Version: "v2", Fields: baseOrderFields()}},
	}
	for _, tc := range cases {
		if _, err := CheckCompatibility(tc.old, tc.new); err == nil {
			t.Errorf("%s: expected error, got nil", tc.name)
		} else {
			t.Logf("%s: rejected: %v", tc.name, err)
		}
	}
}

=== RUN   TestCheckCompatibilityVerdicts
    schema_test.go:75: add optional: v1 -> v2 verdict=full backward=true forward=true
    schema_test.go:75: add required: v1 -> v2 verdict=forward backward=false forward=true
    schema_test.go:75: remove required: v1 -> v2 verdict=backward backward=true forward=false
    schema_test.go:75: remove optional: v1 -> v2 verdict=full backward=true forward=true
    schema_test.go:75: type change: v1 -> v2 verdict=breaking backward=false forward=false
    schema_test.go:75: optional to required: v1 -> v2 verdict=forward backward=false forward=true
    schema_test.go:75: required to optional: v1 -> v2 verdict=backward backward=true forward=false
--- PASS: TestCheckCompatibilityVerdicts (0.00s)
=== RUN   TestCheckCompatibilityNoChange
    schema_test.go:89: identical: verdict=full changes=0
--- PASS: TestCheckCompatibilityNoChange (0.00s)
=== RUN   TestCheckCompatibilityRejectsBadInput
    schema_test.go:108: duplicate field: rejected: new: contract: schema "order.created" has duplicate field "id"
    schema_test.go:108: invalid type: rejected: new: contract: schema "order.created" field "x" has invalid type "decimal"
    schema_test.go:108: different name: rejected: contract: cannot compare "order.created" with "payment.captured"
--- PASS: TestCheckCompatibilityRejectsBadInput (0.00s)
PASS
ok  	archlab/internal/platform/contract	0.413s