《后端架构设计·演进与治理》3.1 服务注册、健康检查与实例生命周期

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

import "errors"
import "fmt"
import "sort"
import "sync"
import "time"

// State is the traffic state of one registered instance. The recovery
// observation period is folded into Ejected plus a success counter, so there
// is no third state that a caller could mistakenly route traffic to.
type State string

const (
	// Ready means the instance receives traffic.
	Ready State = "ready"
	// Ejected means the instance is removed from the traffic snapshot.
	Ejected State = "ejected"
)

// Instance is one registered endpoint plus its health counters.
type Instance struct {
	ID, Addr, Zone      string
	Weight              int
	TTL                 time.Duration
	State               State
	Failures, Successes int
	LastSeen, EjectedAt time.Time
}

// Endpoint is the traffic-facing view of a Ready instance.
type Endpoint struct {
	InstanceID, Addr, Zone string
	Weight                 int
}

// Snapshot is an immutable set of Ready endpoints and its version.
type Snapshot struct {
	Version   uint64
	Endpoints []Endpoint
}

// RegistryConfig controls ejection and recovery hysteresis.
type RegistryConfig struct {
	EjectAfter, RecoverAfter   int
	RecoveryWindow, DefaultTTL time.Duration
}

type Registry struct {
	mu        sync.Mutex
	cfg       RegistryConfig
	now       func() time.Time
	instances map[string]Instance
	version   uint64
}

// NewRegistry builds a registry. Pass nil now to use time.Now.
func NewRegistry(cfg RegistryConfig, now func() time.Time) (*Registry, error) {
	if cfg.EjectAfter < 1 || cfg.RecoverAfter < 1 ||
		cfg.RecoveryWindow <= 0 || cfg.DefaultTTL <= 0 {
		return nil, errors.New("discovery: invalid registry config")
	}
	if now == nil {
		now = time.Now
	}
	return &Registry{cfg: cfg, now: now, instances: make(map[string]Instance)}, nil
}

// Register adds an instance as Ready, or refreshes the lease of the same
// ID/address pair. A different address for an existing ID is rejected.
func (r *Registry) Register(in Instance) error {
	if in.ID == "" || in.Addr == "" {
		return errors.New("discovery: instance ID and address are required")
	}
	if in.Weight <= 0 {
		in.Weight = 1
	}
	if in.TTL <= 0 {
		in.TTL = r.cfg.DefaultTTL
	}
	r.mu.Lock()
	defer r.mu.Unlock()
	if old, exists := r.instances[in.ID]; exists {
		if old.Addr != in.Addr {
			return fmt.Errorf("discovery: instance %q changed address", in.ID)
		}
		old.LastSeen = r.now()
		r.instances[in.ID] = old
		return nil
	}
	in.State, in.Failures, in.Successes, in.LastSeen = Ready, 0, 0, r.now()
	r.instances[in.ID] = in
	r.version++
	return nil
}

// Fail records one failed health check.
func (r *Registry) Fail(id string) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	in, ok := r.instances[id]
	if !ok {
		return fmt.Errorf("discovery: unknown instance %q", id)
	}
	in.Failures++
	in.Successes = 0
	if in.State == Ready && in.Failures >= r.cfg.EjectAfter {
		in.State, in.EjectedAt = Ejected, r.now()
		r.version++
	}
	if in.State == Ejected {
		// A failed probe restarts the recovery observation window.
		in.EjectedAt = r.now()
	}
	r.instances[id] = in
	return nil
}

// Succeed records one successful health check.
func (r *Registry) Succeed(id string) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	in, ok := r.instances[id]
	if !ok {
		return fmt.Errorf("discovery: unknown instance %q", id)
	}
	in.Failures = 0
	switch in.State {
	case Ready:
		in.Successes = 0
	case Ejected:
		in.Successes++
		if in.Successes >= r.cfg.RecoverAfter && r.now().Sub(in.EjectedAt) >= r.cfg.RecoveryWindow {
			in.State, in.Successes, in.EjectedAt = Ready, 0, time.Time{}
			r.version++
		}
	}
	r.instances[id] = in
	return nil
}

// Expire drops instances whose lease is older than their TTL.
func (r *Registry) Expire() int {
	now := r.now()
	r.mu.Lock()
	defer r.mu.Unlock()
	removed := 0
	for id, in := range r.instances {
		if now.Sub(in.LastSeen) > in.TTL {
			delete(r.instances, id)
			removed++
		}
	}
	if removed > 0 {
		r.version++
	}
	return removed
}

// Get returns a copy of one instance.
func (r *Registry) Get(id string) (Instance, bool) {
	r.mu.Lock()
	defer r.mu.Unlock()
	in, ok := r.instances[id]
	return in, ok
}

// Snapshot returns only Ready endpoints, sorted by instance ID.
func (r *Registry) Snapshot() Snapshot {
	r.mu.Lock()
	defer r.mu.Unlock()
	eps := make([]Endpoint, 0, len(r.instances))
	for _, in := range r.instances {
		if in.State == Ready {
			eps = append(eps, Endpoint{in.ID, in.Addr, in.Zone, in.Weight})
		}
	}
	sort.Slice(eps, func(i, j int) bool { return eps[i].InstanceID < eps[j].InstanceID })
	return Snapshot{Version: r.version, Endpoints: eps}
}

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

import "testing"
import "time"

// fakeClock is shared by the registry and balancer tests.
type fakeClock struct{ t time.Time }

func (c *fakeClock) Now() time.Time          { return c.t }
func (c *fakeClock) Advance(d time.Duration) { c.t = c.t.Add(d) }

func newRegistry(t *testing.T, cfg RegistryConfig) (*Registry, *fakeClock) {
	t.Helper()
	clock := &fakeClock{time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)}
	reg, err := NewRegistry(cfg, clock.Now)
	if err != nil {
		t.Fatalf("NewRegistry: %v", err)
	}
	return reg, clock
}

func TestRegistryLifecycle(t *testing.T) {
	reg, clock := newRegistry(t, RegistryConfig{
		EjectAfter: 3, RecoverAfter: 2,
		RecoveryWindow: 10 * time.Second, DefaultTTL: 30 * time.Second,
	})
	if err := reg.Register(Instance{ID: "order-1", Addr: "10.0.0.1:8080", Zone: "az-a"}); err != nil {
		t.Fatalf("Register: %v", err)
	}

	// One bad check followed by a good one is flapping, not failure.
	_ = reg.Fail("order-1")
	_ = reg.Succeed("order-1")
	if got, _ := reg.Get("order-1"); got.State != Ready {
		t.Fatalf("single flap state=%s, want ready", got.State)
	}

	for i := 0; i < 2; i++ {
		_ = reg.Fail("order-1")
	}
	if got, _ := reg.Get("order-1"); got.State != Ready {
		t.Fatalf("after 2 failures state=%s, want ready", got.State)
	}
	if n := len(reg.Snapshot().Endpoints); n != 1 {
		t.Fatalf("ready snapshot size=%d, want 1", n)
	}

	_ = reg.Fail("order-1")
	if got, _ := reg.Get("order-1"); got.State != Ejected {
		t.Fatalf("after 3 failures state=%s, want ejected", got.State)
	}
	if n := len(reg.Snapshot().Endpoints); n != 0 {
		t.Fatalf("ejected snapshot size=%d, want 0", n)
	}

	_ = reg.Succeed("order-1")
	if got, _ := reg.Get("order-1"); got.State != Ejected {
		t.Fatalf("after 1 success state=%s, want ejected", got.State)
	}
	clock.Advance(5 * time.Second)
	_ = reg.Succeed("order-1")
	if got, _ := reg.Get("order-1"); got.State != Ejected {
		t.Fatalf("before recovery window state=%s, want ejected", got.State)
	}
	clock.Advance(6 * time.Second)
	_ = reg.Succeed("order-1")
	if got, _ := reg.Get("order-1"); got.State != Ready {
		t.Fatalf("after recovery state=%s, want ready", got.State)
	}
	if n := len(reg.Snapshot().Endpoints); n != 1 {
		t.Fatalf("recovered snapshot size=%d, want 1", n)
	}
}

func TestRegistryTTLExpiryAndRenew(t *testing.T) {
	reg, clock := newRegistry(t, RegistryConfig{
		EjectAfter: 2, RecoverAfter: 1,
		RecoveryWindow: time.Second, DefaultTTL: 30 * time.Second,
	})
	for _, id := range []string{"payment-1", "payment-2"} {
		_ = reg.Register(Instance{ID: id, Addr: "10.0.0.3:8080"})
	}
	clock.Advance(20 * time.Second)
	_ = reg.Register(Instance{ID: "payment-1", Addr: "10.0.0.3:8080"})
	clock.Advance(11 * time.Second)
	if removed := reg.Expire(); removed != 1 {
		t.Fatalf("Expire removed=%d, want 1", removed)
	}
	if _, ok := reg.Get("payment-1"); !ok {
		t.Fatal("renewed instance was expired")
	}
	if _, ok := reg.Get("payment-2"); ok {
		t.Fatal("stale instance survived expiry")
	}
}

$ cd .local/checks/be-arch-gov-ch03
$ gofmt -l . && go vet ./... && go test ./internal/platform/discovery/ -count=1 -v -run '^TestRegistry'
=== RUN   TestRegistryLifecycle
--- PASS: TestRegistryLifecycle (0.00s)
=== RUN   TestRegistryTTLExpiryAndRenew
--- PASS: TestRegistryTTLExpiryAndRenew (0.00s)
PASS
ok  	archlab/internal/platform/discovery	0.231s