《后端架构设计·演进与治理》5.1 配置分层、版本与灰度发布

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

import (
	"errors"
	"fmt"
	"hash/fnv"
	"sort"
	"strings"
)

// LayerKind orders sources from weakest to strongest.
type LayerKind string

const (
	Default     LayerKind = "default"
	Environment LayerKind = "environment"
	Instance    LayerKind = "instance"
)

func (k LayerKind) rank() int {
	switch k {
	case Default:
		return 0
	case Environment:
		return 1
	case Instance:
		return 2
	}
	return -1
}

// Layer is one source of key/value pairs. At most one layer of each kind is
// accepted, so a double overlay cannot win by argument order.
type Layer struct {
	Kind   LayerKind
	Values map[string]string
}

// Effective is the merged view plus the layer that supplied each key.
type Effective struct {
	Values map[string]string
	Source map[string]LayerKind
}

// Merge overlays layers by precedence: instance > environment > default.
func Merge(layers ...Layer) (Effective, error) {
	seen := make(map[LayerKind]bool, len(layers))
	for _, l := range layers {
		if l.Kind.rank() < 0 {
			return Effective{}, fmt.Errorf("config: unknown layer %q", l.Kind)
		}
		if seen[l.Kind] {
			return Effective{}, fmt.Errorf("config: duplicate layer %q", l.Kind)
		}
		seen[l.Kind] = true
		for k := range l.Values {
			if strings.TrimSpace(k) == "" {
				return Effective{}, fmt.Errorf("config: empty key in %s", l.Kind)
			}
		}
	}
	out := Effective{Values: map[string]string{}, Source: map[string]LayerKind{}}
	ordered := append([]Layer(nil), layers...)
	sort.Slice(ordered, func(i, j int) bool {
		return ordered[i].Kind.rank() < ordered[j].Kind.rank()
	})
	for _, l := range ordered {
		for k, v := range l.Values {
			out.Values[k], out.Source[k] = v, l.Kind
		}
	}
	return out, nil
}

// Bundle is one immutable configuration version.
type Bundle struct {
	Version uint64
	Values  map[string]string
}

// Validate rejects a bundle that cannot be versioned or published.
func (b Bundle) Validate() error {
	if b.Version == 0 {
		return errors.New("config: bundle version must be positive")
	}
	for k := range b.Values {
		if strings.TrimSpace(k) == "" {
			return errors.New("config: bundle has an empty key")
		}
	}
	return nil
}

// Clone detaches the bundle from the caller's map.
func (b Bundle) Clone() Bundle {
	return Bundle{Version: b.Version, Values: cloneValues(b.Values)}
}

// GrayPlan routes a deterministic share of instances to the candidate.
type GrayPlan struct {
	Percent int    // 0..100
	Salt    string // change it to reshuffle without editing configuration
}

// Selects reports whether an instance should read the candidate version.
func (p GrayPlan) Selects(instanceID string) bool {
	if p.Percent <= 0 {
		return false
	}
	if p.Percent >= 100 {
		return true
	}
	return bucketOf(p.Salt, instanceID) < p.Percent
}

// Release couples a stable bundle with an optional candidate bundle.
type Release struct {
	Stable    Bundle
	Candidate *Bundle
	Plan      GrayPlan
}

// For returns the bundle one instance must load.
func (r Release) For(instanceID string) (Bundle, error) {
	if err := r.Stable.Validate(); err != nil {
		return Bundle{}, err
	}
	if r.Candidate == nil {
		return r.Stable.Clone(), nil
	}
	if err := r.Candidate.Validate(); err != nil {
		return Bundle{}, err
	}
	if r.Candidate.Version <= r.Stable.Version {
		return Bundle{}, fmt.Errorf("config: candidate %d must exceed stable %d",
			r.Candidate.Version, r.Stable.Version)
	}
	if r.Plan.Percent < 0 || r.Plan.Percent > 100 {
		return Bundle{}, fmt.Errorf("config: gray percent %d outside 0..100", r.Plan.Percent)
	}
	if strings.TrimSpace(instanceID) == "" {
		return Bundle{}, errors.New("config: empty instance id")
	}
	if r.Plan.Selects(instanceID) {
		return r.Candidate.Clone(), nil
	}
	return r.Stable.Clone(), nil
}

// bucketOf hashes NUL-joined parts into 0..99.
func bucketOf(parts ...string) int {
	h := fnv.New32a()
	for i, p := range parts {
		if i > 0 {
			h.Write([]byte{0})
		}
		h.Write([]byte(p))
	}
	return int(h.Sum32() % 100)
}

func cloneValues(in map[string]string) map[string]string {
	out := make(map[string]string, len(in))
	for k, v := range in {
		out[k] = v
	}
	return out
}

$ go version
go version go1.26.0 darwin/arm64
$ gofmt -l .
$ go vet ./...
$ go test ./internal/platform/config/ -count=1 -v -run 'TestMerge|TestGrayPlan|TestRelease'
=== RUN   TestMergePrecedence
    config_test.go:39: values=map[db:orders-canary retries:3 timeout_ms:500] source=map[db:instance retries:environment timeout_ms:default]
--- PASS: TestMergePrecedence (0.00s)
=== RUN   TestGrayPlanDeterministic
    config_test.go:59: instances=10000 selected=990 rate=0.0990
--- PASS: TestGrayPlanDeterministic (0.01s)
=== RUN   TestReleaseRouting
    config_test.go:91: stable=506 candidate=494
--- PASS: TestReleaseRouting (0.00s)
PASS
ok  	archlab/internal/platform/config	0.260s

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

import (
	"fmt"
	"reflect"
	"testing"
)

func TestMergePrecedence(t *testing.T) {
	def := Layer{Kind: Default, Values: map[string]string{"timeout_ms": "500", "retries": "2"}}
	env := Layer{Kind: Environment, Values: map[string]string{"retries": "3", "db": "orders"}}
	inst := Layer{Kind: Instance, Values: map[string]string{"db": "orders-canary"}}
	eff, err := Merge(def, env, inst)
	if err != nil {
		t.Fatalf("Merge: %v", err)
	}
	if eff.Values["timeout_ms"] != "500" || eff.Values["retries"] != "3" || eff.Values["db"] != "orders-canary" {
		t.Fatalf("values = %v", eff.Values)
	}
	if eff.Source["timeout_ms"] != Default || eff.Source["retries"] != Environment || eff.Source["db"] != Instance {
		t.Fatalf("source = %v", eff.Source)
	}
	shuffled, err := Merge(inst, def, env)
	if err != nil {
		t.Fatalf("shuffled: %v", err)
	}
	if !reflect.DeepEqual(eff, shuffled) {
		t.Fatalf("merge depends on order: %v vs %v", eff, shuffled)
	}
	if _, err := Merge(def, def); err == nil {
		t.Fatal("duplicate layer accepted")
	}
	if _, err := Merge(Layer{Kind: "instance-override"}); err == nil {
		t.Fatal("unknown layer accepted")
	}
	t.Logf("values=%v source=%v", eff.Values, eff.Source)
}

func TestGrayPlanDeterministic(t *testing.T) {
	plan := GrayPlan{Percent: 10, Salt: "orders-2026-11"}
	selected := 0
	const instances = 10000
	for i := 0; i < instances; i++ {
		id := fmt.Sprintf("order-pod-%05d", i)
		if plan.Selects(id) != plan.Selects(id) {
			t.Fatalf("%s selection is not deterministic", id)
		}
		if plan.Selects(id) {
			selected++
		}
	}
	rate := float64(selected) / instances
	if rate < 0.07 || rate > 0.13 {
		t.Fatalf("selection rate %.4f outside 7%%..13%%", rate)
	}
	t.Logf("instances=%d selected=%d rate=%.4f", instances, selected, rate)
}

func TestReleaseRouting(t *testing.T) {
	stable := Bundle{Version: 41, Values: map[string]string{"retry": "2"}}
	candidate := Bundle{Version: 42, Values: map[string]string{"retry": "4"}}
	for _, tc := range []struct {
		percent int
		want    uint64
	}{{0, 41}, {100, 42}} {
		r := Release{Stable: stable, Candidate: &candidate, Plan: GrayPlan{Percent: tc.percent, Salt: "s"}}
		got, err := r.For("pod-1")
		if err != nil || got.Version != tc.want {
			t.Fatalf("%d%%: %+v, %v", tc.percent, got, err)
		}
	}
	half := Release{Stable: stable, Candidate: &candidate, Plan: GrayPlan{Percent: 50, Salt: "s"}}
	versions := map[uint64]int{}
	for i := 0; i < 1000; i++ {
		b, err := half.For(fmt.Sprintf("pod-%03d", i))
		if err != nil {
			t.Fatalf("50%%: %v", err)
		}
		versions[b.Version]++
	}
	if versions[41] == 0 || versions[42] == 0 {
		t.Fatalf("50%% did not split: %v", versions)
	}
	older := Bundle{Version: 41, Values: map[string]string{"retry": "4"}}
	if _, err := (Release{Stable: stable, Candidate: &older, Plan: GrayPlan{Percent: 50}}).For("pod-1"); err == nil {
		t.Fatal("expected candidate version error")
	}
	t.Logf("stable=%d candidate=%d", versions[41], versions[42])
}