《后端架构设计·演进与治理》2.3 契约变更门禁：schema 校验与跨服务兼容测试

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

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

// Expectation is one thing a consumer relies on. Path uses dotted object
// keys ("order.id"); array indexes are not supported on purpose.
type Expectation struct {
	Path     string
	Type     ValueType
	Required bool
}

// ConsumerContract is the expectation recorded in the consumer repository
// and replayed against the provider in CI.
type ConsumerContract struct {
	Consumer     string
	Provider     string
	Version      string
	Expectations []Expectation
}

// Validate rejects contracts that would make the gate silently weaker.
func (c ConsumerContract) Validate() error {
	if strings.TrimSpace(c.Consumer) == "" {
		return fmt.Errorf("contract: consumer name is empty")
	}
	if strings.TrimSpace(c.Provider) == "" {
		return fmt.Errorf("contract: consumer %q has no provider", c.Consumer)
	}
	if strings.TrimSpace(c.Version) == "" {
		return fmt.Errorf("contract: consumer %q has no contract version", c.Consumer)
	}
	if len(c.Expectations) == 0 {
		return fmt.Errorf("contract: consumer %q has no expectations", c.Consumer)
	}
	seen := make(map[string]bool, len(c.Expectations))
	for _, e := range c.Expectations {
		if strings.TrimSpace(e.Path) == "" {
			return fmt.Errorf("contract: consumer %q has an empty path", c.Consumer)
		}
		if seen[e.Path] {
			return fmt.Errorf("contract: consumer %q repeats path %q", c.Consumer, e.Path)
		}
		seen[e.Path] = true
		if !e.Type.valid() {
			return fmt.Errorf("contract: consumer %q path %q has invalid type %q", c.Consumer, e.Path, e.Type)
		}
	}
	return nil
}

// Sample is one message captured from the provider's current build.
type Sample struct {
	Provider string
	Version  string
	Payload  map[string]any
}

// Violation is one concrete reason a consumer would break.
type Violation struct {
	Consumer string
	Path     string
	Reason   string
}

// GateResult is what CI prints and what the merge queue blocks on.
type GateResult struct {
	Passed     bool
	Checked    int
	Violations []Violation
}

// VerifyContract checks one consumer against one provider sample. Missing
// optional paths are ignored; missing required paths and type mismatches
// are violations.
func VerifyContract(c ConsumerContract, s Sample) []Violation {
	expectations := append([]Expectation(nil), c.Expectations...)
	sort.Slice(expectations, func(i, j int) bool { return expectations[i].Path < expectations[j].Path })

	var out []Violation
	for _, e := range expectations {
		value, ok := lookupPath(s.Payload, e.Path)
		if !ok {
			if e.Required {
				out = append(out, Violation{c.Consumer, e.Path,
					fmt.Sprintf("required path missing in %s@%s", s.Provider, s.Version)})
			}
			continue
		}
		if got := typeOf(value); got != e.Type {
			out = append(out, Violation{c.Consumer, e.Path,
				fmt.Sprintf("type changed: want %s, got %s in %s@%s", e.Type, got, s.Provider, s.Version)})
		}
	}
	return out
}

// lookupPath walks dotted object keys. A non-object intermediate counts as
// absent instead of panicking.
func lookupPath(payload map[string]any, path string) (any, bool) {
	var current any = payload
	for _, part := range strings.Split(path, ".") {
		obj, ok := current.(map[string]any)
		if !ok {
			return nil, false
		}
		value, ok := obj[part]
		if !ok {
			return nil, false
		}
		current = value
	}
	return current, true
}

// typeOf maps a decoded JSON value to its wire type. Plain Go ints are
// accepted in tests; a real JSON decoder yields float64 for every number.
func typeOf(v any) ValueType {
	switch v.(type) {
	case string:
		return TypeString
	case int, int32, int64:
		return TypeInt
	case float32, float64:
		return TypeFloat
	case bool:
		return TypeBool
	case map[string]any:
		return TypeObject
	case []any:
		return TypeArray
	default:
		return ValueType(fmt.Sprintf("%T", v))
	}
}

// RunGate verifies every contract against the sample with the same provider
// name. Malformed input is an error (a broken gate must fail loudly); real
// contract violations set Passed=false.
func RunGate(contracts []ConsumerContract, samples []Sample) (GateResult, error) {
	byProvider := make(map[string]Sample, len(samples))
	for _, s := range samples {
		if strings.TrimSpace(s.Provider) == "" {
			return GateResult{}, fmt.Errorf("contract: sample has no provider name")
		}
		if _, dup := byProvider[s.Provider]; dup {
			return GateResult{}, fmt.Errorf("contract: duplicate sample for provider %q", s.Provider)
		}
		byProvider[s.Provider] = s
	}

	seen := make(map[string]bool, len(contracts))
	result := GateResult{Passed: true}
	for _, c := range contracts {
		if err := c.Validate(); err != nil {
			return GateResult{}, err
		}
		key := c.Consumer + "\x00" + c.Provider
		if seen[key] {
			return GateResult{}, fmt.Errorf("contract: duplicate contract %s -> %s", c.Consumer, c.Provider)
		}
		seen[key] = true

		s, ok := byProvider[c.Provider]
		if !ok {
			result.Violations = append(result.Violations, Violation{c.Consumer, "",
				fmt.Sprintf("no provider sample for %q", c.Provider)})
			continue
		}
		result.Checked++
		result.Violations = append(result.Violations, VerifyContract(c, s)...)
	}
	if len(result.Violations) > 0 {
		result.Passed = false
	}
	return result, nil
}

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

import "testing"

func orderPaidSample() Sample {
	return Sample{Provider: "order-service", Version: "v3", Payload: map[string]any{
		"event_id": "evt-1",
		"paid":     true,
		"order": map[string]any{
			"id":       "ord-1",
			"amount":   12800,
			"currency": "CNY",
		},
		"items": []any{"sku-1", "sku-2"},
	}}
}

func cc(consumer string, exp ...Expectation) ConsumerContract {
	return ConsumerContract{Consumer: consumer, Provider: "order-service", Version: "1", Expectations: exp}
}

func TestVerifyContractMissingAndType(t *testing.T) {
	sample := orderPaidSample()
	cases := []struct {
		name string
		c    ConsumerContract
		want int
	}{
		{"optional missing ignored", cc("crm",
			Expectation{Path: "order.id", Type: TypeString, Required: true},
			Expectation{Path: "order.note", Type: TypeString}), 0},
		{"required nested missing", cc("audit",
			Expectation{Path: "order.seller.id", Type: TypeString, Required: true}), 1},
		{"type changed", cc("ledger",
			Expectation{Path: "order.amount", Type: TypeFloat, Required: true}), 1},
	}
	for _, tc := range cases {
		if err := tc.c.Validate(); err != nil {
			t.Fatalf("%s: invalid fixture: %v", tc.name, err)
		}
		got := VerifyContract(tc.c, sample)
		if len(got) != tc.want {
			t.Errorf("%s: violations=%d want=%d (%+v)", tc.name, len(got), tc.want, got)
		}
		for _, v := range got {
			t.Logf("%s: path=%s reason=%s", tc.name, v.Path, v.Reason)
		}
	}
}

func TestRunGatePassesWhenAllConsumersMatch(t *testing.T) {
	contracts := []ConsumerContract{
		cc("billing", Expectation{Path: "order.id", Type: TypeString, Required: true},
			Expectation{Path: "order.amount", Type: TypeInt, Required: true}),
		cc("shipping", Expectation{Path: "order.id", Type: TypeString, Required: true},
			Expectation{Path: "items", Type: TypeArray, Required: true}),
	}
	res, err := RunGate(contracts, []Sample{orderPaidSample()})
	if err != nil {
		t.Fatal(err)
	}
	t.Logf("pass case: passed=%t checked=%d violations=%d", res.Passed, res.Checked, len(res.Violations))
	if !res.Passed || res.Checked != 2 || len(res.Violations) != 0 {
		t.Fatalf("expected gate pass, got %+v", res)
	}
}

func TestRunGateBlocksBreakingChange(t *testing.T) {
	missing := cc("notification", Expectation{Path: "payment.id", Type: TypeString, Required: true})
	missing.Provider = "payment-service"
	contracts := []ConsumerContract{
		cc("billing", Expectation{Path: "order.id", Type: TypeString, Required: true}),
		cc("ledger", Expectation{Path: "order.amount", Type: TypeFloat, Required: true}),
		cc("audit", Expectation{Path: "order.seller.id", Type: TypeString, Required: true}),
		missing,
	}
	res, err := RunGate(contracts, []Sample{orderPaidSample()})
	if err != nil {
		t.Fatal(err)
	}
	t.Logf("fail case: passed=%t checked=%d violations=%d", res.Passed, res.Checked, len(res.Violations))
	if res.Passed || res.Checked != 3 || len(res.Violations) != 3 {
		t.Fatalf("expected three violations and a block, got %+v", res)
	}
	for _, v := range res.Violations {
		t.Logf("violation: consumer=%s path=%s reason=%s", v.Consumer, v.Path, v.Reason)
	}
}

func TestRunGateRejectsBrokenInput(t *testing.T) {
	valid := cc("billing", Expectation{Path: "order.id", Type: TypeString, Required: true})
	cases := []struct {
		name      string
		contracts []ConsumerContract
		samples   []Sample
	}{
		{"no expectations", []ConsumerContract{{Consumer: "x", Provider: "order-service", Version: "1"}}, []Sample{orderPaidSample()}},
		{"duplicate contract", []ConsumerContract{valid, valid}, []Sample{orderPaidSample()}},
		{"duplicate sample", []ConsumerContract{valid}, []Sample{orderPaidSample(), orderPaidSample()}},
	}
	for _, tc := range cases {
		if _, err := RunGate(tc.contracts, tc.samples); err == nil {
			t.Errorf("%s: expected error, got nil", tc.name)
		} else {
			t.Logf("%s: rejected: %v", tc.name, err)
		}
	}
}

=== RUN   TestVerifyContractMissingAndType
    gate_test.go:49: required nested missing: path=order.seller.id reason=required path missing in order-service@v3
    gate_test.go:49: type changed: path=order.amount reason=type changed: want float, got int in order-service@v3
--- PASS: TestVerifyContractMissingAndType (0.00s)
=== RUN   TestRunGatePassesWhenAllConsumersMatch
    gate_test.go:65: pass case: passed=true checked=2 violations=0
--- PASS: TestRunGatePassesWhenAllConsumersMatch (0.00s)
=== RUN   TestRunGateBlocksBreakingChange
    gate_test.go:84: fail case: passed=false checked=3 violations=3
    gate_test.go:89: violation: consumer=ledger path=order.amount reason=type changed: want float, got int in order-service@v3
    gate_test.go:89: violation: consumer=audit path=order.seller.id reason=required path missing in order-service@v3
    gate_test.go:89: violation: consumer=notification path= reason=no provider sample for "payment-service"
--- PASS: TestRunGateBlocksBreakingChange (0.00s)
=== RUN   TestRunGateRejectsBrokenInput
    gate_test.go:108: no expectations: rejected: contract: consumer "x" has no expectations
    gate_test.go:108: duplicate contract: rejected: contract: duplicate contract billing -> order-service
    gate_test.go:108: duplicate sample: rejected: contract: duplicate sample for provider "order-service"
--- PASS: TestRunGateRejectsBrokenInput (0.00s)
PASS
ok  	archlab/internal/platform/contract	0.413s