《后端架构设计·分布式与数据一致性》1.3 远程调用的八个假设与端到端原则

调用方                     中间层                     服务端
  |-- req(orderID, seq) ----->|------------------------->|
  |                           |   (可重试、可丢、可重复)   |
  |<-- ack / timeout ---------|<-------------------------|
  |                                                      |
  |  端点责任：稳定幂等键 + 总超时预算 + 状态查询         |
  |  中间层责任：转发、限流、观测，不承诺业务语义         |

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

import (
	"errors"
	"fmt"
)

// Errors returned by the simulated terminal service.
var (
	ErrUnavailable = errors.New("edgecall: downstream unavailable")
	ErrTimeout     = errors.New("edgecall: acknowledgement lost")
)

// FailMode selects how the terminal service fails.
type FailMode int

const (
	FailNever FailMode = iota
	FailAlways
	FailAfterEffect
)

// Server is the terminal order service reached by every retry layer.
type Server struct {
	Idempotent bool
	Mode       FailMode
	Calls      int
	Effects    int
	seen       map[string]bool
	attempts   map[string]int
}

// NewServer creates a terminal service with an empty dedupe set.
func NewServer(idempotent bool, mode FailMode) *Server {
	return &Server{
		Idempotent: idempotent,
		Mode:       mode,
		seen:       make(map[string]bool),
		attempts:   make(map[string]int),
	}
}

// Call performs the order-side effect once and reports the transport result.
func (s *Server) Call(reqID string) error {
	s.Calls++
	s.attempts[reqID]++
	if s.Mode == FailAlways {
		return fmt.Errorf("call %s: %w", reqID, ErrUnavailable)
	}
	if s.Mode == FailAfterEffect && s.attempts[reqID] == 1 {
		s.apply(reqID)
		return fmt.Errorf("call %s: %w", reqID, ErrTimeout)
	}
	s.apply(reqID)
	return nil
}

func (s *Server) apply(reqID string) {
	if s.Idempotent && s.seen[reqID] {
		return
	}
	s.seen[reqID] = true
	s.Effects++
}

// Retry runs fn with at most retries+1 attempts per layer.
func Retry(layers, retries int, fn func() error) error {
	if layers == 0 {
		return fn()
	}
	var err error
	for i := 0; i <= retries; i++ {
		if err = Retry(layers-1, retries, fn); err == nil {
			return nil
		}
	}
	return err
}

// Attempts is the worst-case number of terminal calls.
func Attempts(layers, retries int) int {
	n := 1
	for i := 0; i < layers; i++ {
		n *= retries + 1
	}
	return n
}

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

import (
	"errors"
	"fmt"
	"testing"
)

func TestRetryAmplification(t *testing.T) {
	cases := []struct {
		name      string
		layers    int
		retries   int
		wantCalls int
	}{
		{"single layer", 1, 3, 4},
		{"two layers", 2, 3, 16},
		{"three layers", 3, 3, 64},
		{"four layers", 4, 3, 256},
		{"no retry", 3, 0, 1},
	}

	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			srv := NewServer(true, FailAlways)
			_ = Retry(tc.layers, tc.retries, func() error { return srv.Call("ord-1") })
			if srv.Calls != tc.wantCalls {
				t.Fatalf("calls = %d, want %d", srv.Calls, tc.wantCalls)
			}
			if got := Attempts(tc.layers, tc.retries); got != tc.wantCalls {
				t.Fatalf("Attempts = %d, want %d", got, tc.wantCalls)
			}
		})
	}
}

func TestLostAckDuplicatesEffectWithoutDedupe(t *testing.T) {
	cases := []struct {
		name       string
		idempotent bool
		wantCalls  int
		wantEffect int
	}{
		{"non-idempotent retry", false, 2, 2},
		{"idempotent retry", true, 2, 1},
	}

	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			srv := NewServer(tc.idempotent, FailAfterEffect)
			err := Retry(1, 1, func() error { return srv.Call("ord-1") })
			if err != nil {
				t.Fatalf("retry: %v", err)
			}
			if srv.Calls != tc.wantCalls {
				t.Fatalf("calls = %d, want %d", srv.Calls, tc.wantCalls)
			}
			if srv.Effects != tc.wantEffect {
				t.Fatalf("effects = %d, want %d", srv.Effects, tc.wantEffect)
			}
		})
	}
}

func TestEndToEndDedupeUnderRepeatedLostAcks(t *testing.T) {
	const requests = 50
	srv := NewServer(true, FailAfterEffect)
	for i := 0; i < requests; i++ {
		reqID := fmt.Sprintf("ord-%d", i)
		if err := Retry(2, 1, func() error { return srv.Call(reqID) }); err != nil {
			t.Fatalf("request %s: %v", reqID, err)
		}
	}
	if srv.Effects != requests {
		t.Fatalf("effects = %d, want %d", srv.Effects, requests)
	}
	if srv.Calls <= requests {
		t.Fatalf("calls = %d, want more than %d retries", srv.Calls, requests)
	}
}

func TestPermanentFailureIsReported(t *testing.T) {
	srv := NewServer(true, FailAlways)
	err := Retry(2, 2, func() error { return srv.Call("ord-9") })
	if !errors.Is(err, ErrUnavailable) {
		t.Fatalf("err = %v, want ErrUnavailable", err)
	}
	if srv.Effects != 0 {
		t.Fatalf("effects = %d, want 0", srv.Effects)
	}
}

=== RUN   TestRetryAmplification
=== RUN   TestRetryAmplification/single_layer
=== RUN   TestRetryAmplification/two_layers
=== RUN   TestRetryAmplification/three_layers
=== RUN   TestRetryAmplification/four_layers
=== RUN   TestRetryAmplification/no_retry
--- PASS: TestRetryAmplification (0.00s)
    --- PASS: TestRetryAmplification/single_layer (0.00s)
    --- PASS: TestRetryAmplification/two_layers (0.00s)
    --- PASS: TestRetryAmplification/three_layers (0.00s)
    --- PASS: TestRetryAmplification/four_layers (0.00s)
    --- PASS: TestRetryAmplification/no_retry (0.00s)
=== RUN   TestLostAckDuplicatesEffectWithoutDedupe
=== RUN   TestLostAckDuplicatesEffectWithoutDedupe/non-idempotent_retry
=== RUN   TestLostAckDuplicatesEffectWithoutDedupe/idempotent_retry
--- PASS: TestLostAckDuplicatesEffectWithoutDedupe (0.00s)
    --- PASS: TestLostAckDuplicatesEffectWithoutDedupe/non-idempotent_retry (0.00s)
    --- PASS: TestLostAckDuplicatesEffectWithoutDedupe/idempotent_retry (0.00s)
=== RUN   TestEndToEndDedupeUnderRepeatedLostAcks
--- PASS: TestEndToEndDedupeUnderRepeatedLostAcks (0.00s)
=== RUN   TestPermanentFailureIsReported
--- PASS: TestPermanentFailureIsReported (0.00s)
PASS
ok  	archlab/internal/platform/edgecall	0.509s