《后端架构设计·演进与治理》2.1 同步调用与异步事件：组合而不是二选一

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

import (
	"fmt"
	"strings"
)

// Transport is how one interaction between two services is carried.
type Transport string

const (
	TransportSync   Transport = "sync"
	TransportAsync  Transport = "async"
	TransportHybrid Transport = "hybrid" // sync accept + async completion
)

// Requirement is the input to the decision. Every field must be answerable
// before code is written, not a matter of taste.
type Requirement struct {
	Name                 string
	NeedsImmediateResult bool
	StalenessMS          int // 0 means immediate
	LatencyBudgetMS      int
	ProviderP99MS        int
	FailFast             bool
	OpsMaturity          int // 1 (no DLQ/replay) .. 5 (routine)
}

// Weights are the relative importance of the four axes.
type Weights struct{ Consistency, Latency, Failure, Ops int }

// DefaultWeights is the weighting used by the chapter.
func DefaultWeights() Weights { return Weights{3, 2, 2, 1} }

// Recommendation keeps the per-axis scores so a reviewer can disagree with
// one input instead of rejecting the whole answer.
type Recommendation struct {
	Transport Transport
	Scores    map[Transport]int
	Reasons   []string
	Risks     []string
}

func (r Requirement) validate() error {
	switch {
	case strings.TrimSpace(r.Name) == "":
		return fmt.Errorf("contract: requirement name is empty")
	case r.LatencyBudgetMS <= 0:
		return fmt.Errorf("contract: latency budget must be positive, got %d", r.LatencyBudgetMS)
	case r.ProviderP99MS <= 0:
		return fmt.Errorf("contract: provider p99 must be positive, got %d", r.ProviderP99MS)
	case r.StalenessMS < 0:
		return fmt.Errorf("contract: staleness must not be negative, got %d", r.StalenessMS)
	case r.OpsMaturity < 1 || r.OpsMaturity > 5:
		return fmt.Errorf("contract: ops maturity must be 1..5, got %d", r.OpsMaturity)
	}
	return nil
}

// Recommend scores sync, async and hybrid on consistency, latency, failure
// propagation and operational cost. Ties prefer sync, then async, then
// hybrid: the cheaper model wins when the evidence does not separate them.
func Recommend(r Requirement, w Weights) (Recommendation, error) {
	if err := r.validate(); err != nil {
		return Recommendation{}, err
	}
	if w.Consistency < 0 || w.Latency < 0 || w.Failure < 0 || w.Ops < 0 {
		return Recommendation{}, fmt.Errorf("contract: weights must not be negative")
	}
	if w.Consistency+w.Latency+w.Failure+w.Ops == 0 {
		return Recommendation{}, fmt.Errorf("contract: all weights are zero")
	}

	scores := map[Transport]int{}
	var reasons []string
	add := func(axis string, weight, sync, async, hybrid int, why string) {
		if weight == 0 {
			return
		}
		scores[TransportSync] += sync * weight
		scores[TransportAsync] += async * weight
		scores[TransportHybrid] += hybrid * weight
		reasons = append(reasons, fmt.Sprintf("%s(w=%d) %s [s=%d a=%d h=%d]",
			axis, weight, why, sync, async, hybrid))
	}

	switch {
	case r.NeedsImmediateResult || r.StalenessMS == 0:
		add("consistency", w.Consistency, 3, 0, 3, "immediate result required")
	case r.StalenessMS < 1000:
		add("consistency", w.Consistency, 2, 1, 3, "staleness below 1s")
	default:
		add("consistency", w.Consistency, 1, 3, 2, "staleness tolerated")
	}

	switch {
	case r.LatencyBudgetMS < r.ProviderP99MS:
		add("latency", w.Latency, 0, 3, 2, "budget below provider p99")
	case r.LatencyBudgetMS < 2*r.ProviderP99MS:
		add("latency", w.Latency, 1, 3, 2, "budget below twice provider p99")
	default:
		add("latency", w.Latency, 3, 3, 3, "budget fits with headroom")
	}

	if r.FailFast {
		add("failure", w.Failure, 2, 3, 3, "failure must stop the caller")
	} else {
		add("failure", w.Failure, 0, 3, 2, "failure can be absorbed")
	}

	switch {
	case r.OpsMaturity <= 2:
		add("operations", w.Ops, 3, 1, 1, "no DLQ/replay/lag monitoring")
	case r.OpsMaturity == 3:
		add("operations", w.Ops, 3, 2, 2, "basic alerts, manual replay")
	default:
		add("operations", w.Ops, 2, 3, 3, "outbox, DLQ and replay are routine")
	}

	best := TransportSync
	for _, t := range []Transport{TransportAsync, TransportHybrid} {
		if scores[t] > scores[best] {
			best = t
		}
	}

	var risks []string
	switch best {
	case TransportAsync:
		if r.OpsMaturity <= 2 {
			risks = append(risks, "async with ops maturity <=2: expect silent loss")
		}
		if r.NeedsImmediateResult || r.StalenessMS == 0 {
			risks = append(risks, "async cannot satisfy immediate-result requirement")
		}
	case TransportSync:
		if r.LatencyBudgetMS < r.ProviderP99MS {
			risks = append(risks, "sync cannot meet budget even before retries")
		}
		if r.StalenessMS >= 1000 && !r.NeedsImmediateResult {
			risks = append(risks, "sync couples a staleness-tolerant flow")
		}
	case TransportHybrid:
		risks = append(risks, "hybrid needs idempotent consumer and sync fallback")
	}
	return Recommendation{Transport: best, Scores: scores, Reasons: reasons, Risks: risks}, nil
}

// String prints the score line used by tests and CI logs.
func (r Recommendation) String() string {
	return fmt.Sprintf("transport=%s sync=%d async=%d hybrid=%d",
		r.Transport, r.Scores[TransportSync], r.Scores[TransportAsync], r.Scores[TransportHybrid])
}

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

import "testing"

func TestRecommendOrderFlow(t *testing.T) {
	cases := []struct {
		name string
		req  Requirement
		want Transport
	}{
		{
			name: "payment authorization",
			req: Requirement{
				Name: "payment-authorize", NeedsImmediateResult: true,
				LatencyBudgetMS: 300, ProviderP99MS: 120,
				FailFast: true, OpsMaturity: 2,
			},
			want: TransportSync,
		},
		{
			name: "order confirmation email",
			req: Requirement{
				Name: "order-email", StalenessMS: 60000,
				LatencyBudgetMS: 200, ProviderP99MS: 400,
				OpsMaturity: 3,
			},
			want: TransportAsync,
		},
		{
			name: "checkout stock reservation",
			req: Requirement{
				Name: "reserve-stock", NeedsImmediateResult: true,
				LatencyBudgetMS: 500, ProviderP99MS: 80,
				FailFast: true, OpsMaturity: 4,
			},
			want: TransportHybrid,
		},
		{
			name: "search index update",
			req: Requirement{
				Name: "search-index", StalenessMS: 5000,
				LatencyBudgetMS: 100, ProviderP99MS: 50,
				OpsMaturity: 4,
			},
			want: TransportAsync,
		},
		{
			name: "coupon validation",
			req: Requirement{
				Name: "coupon-check", NeedsImmediateResult: true,
				LatencyBudgetMS: 150, ProviderP99MS: 100,
				OpsMaturity: 3,
			},
			want: TransportHybrid,
		},
	}
	for _, tc := range cases {
		rec, err := Recommend(tc.req, DefaultWeights())
		if err != nil {
			t.Fatalf("%s: unexpected error: %v", tc.name, err)
		}
		if rec.Transport != tc.want {
			t.Errorf("%s: got %s, want %s", tc.name, rec.Transport, tc.want)
		}
		t.Logf("%s: %s reasons=%d risks=%d", tc.name, rec, len(rec.Reasons), len(rec.Risks))
		for _, risk := range rec.Risks {
			t.Logf("  risk: %s", risk)
		}
	}
}

func TestRecommendRejectsInvalidInput(t *testing.T) {
	base := Requirement{Name: "valid", LatencyBudgetMS: 100, ProviderP99MS: 50, OpsMaturity: 3}
	cases := []struct {
		name string
		req  Requirement
		w    Weights
	}{
		{"empty name", Requirement{LatencyBudgetMS: 100, ProviderP99MS: 50, OpsMaturity: 3}, DefaultWeights()},
		{"zero budget", Requirement{Name: "x", ProviderP99MS: 50, OpsMaturity: 3}, DefaultWeights()},
		{"negative staleness", Requirement{Name: "x", StalenessMS: -1, LatencyBudgetMS: 100, ProviderP99MS: 50, OpsMaturity: 3}, DefaultWeights()},
		{"ops out of range", Requirement{Name: "x", LatencyBudgetMS: 100, ProviderP99MS: 50, OpsMaturity: 6}, DefaultWeights()},
		{"all weights zero", base, Weights{}},
	}
	for _, tc := range cases {
		if _, err := Recommend(tc.req, tc.w); err == nil {
			t.Errorf("%s: expected error, got nil", tc.name)
		} else {
			t.Logf("%s: rejected: %v", tc.name, err)
		}
	}
}

=== RUN   TestRecommendOrderFlow
    decision_test.go:68: payment authorization: transport=sync sync=22 async=13 hybrid=22 reasons=4 risks=0
    decision_test.go:68: order confirmation email: transport=async sync=6 async=23 hybrid=16 reasons=4 risks=0
    decision_test.go:68: checkout stock reservation: transport=hybrid sync=21 async=15 hybrid=24 reasons=4 risks=1
    decision_test.go:70:   risk: hybrid needs idempotent consumer and sync fallback
    decision_test.go:68: search index update: transport=async sync=11 async=24 hybrid=19 reasons=4 risks=0
    decision_test.go:68: coupon validation: transport=hybrid sync=14 async=14 hybrid=19 reasons=4 risks=1
    decision_test.go:70:   risk: hybrid needs idempotent consumer and sync fallback
--- PASS: TestRecommendOrderFlow (0.00s)
=== RUN   TestRecommendRejectsInvalidInput
    decision_test.go:92: empty name: rejected: contract: requirement name is empty
    decision_test.go:92: zero budget: rejected: contract: latency budget must be positive, got 0
    decision_test.go:92: negative staleness: rejected: contract: staleness must not be negative, got -1
    decision_test.go:92: ops out of range: rejected: contract: ops maturity must be 1..5, got 6
    decision_test.go:92: all weights zero: rejected: contract: all weights are zero
--- PASS: TestRecommendRejectsInvalidInput (0.00s)
PASS
ok  	archlab/internal/platform/contract	0.413s