《互联网产品的服务端架构·交易、增长与平台化》8.3 配置平台与开关治理

// file: internal/experiment/config.go
// tier: L1
// verify: go test ./internal/experiment/

package experiment

import (
	"errors"
	"fmt"
	"strings"
)

var (
	// ErrEmptyFlagName 表示开关没有名字，无法定位和审计。
	ErrEmptyFlagName = errors.New("experiment: empty flag name")
	// ErrInvalidPercent 表示放量比例不在 0..100。
	ErrInvalidPercent = errors.New("experiment: percent out of range")
)

// Flag 是一个运行时开关。Name 同时充当分流 salt，因此同名开关的用户命中
// 结果稳定；Percent 是启用的百分比，0 表示全关，100 表示全开。
type Flag struct {
	Name    string
	Enabled bool
	Percent int
}

// Validate 检查开关定义本身是否合法。它不关心某个用户是否命中，适合在
// 配置平台保存、发布前调用。Enabled=false 时 Percent 仍必须是 0..100，
// 避免关闭期间写入脏值，之后重新打开时突然全量。
func Validate(f Flag) error {
	if strings.TrimSpace(f.Name) == "" {
		return ErrEmptyFlagName
	}
	if f.Percent < 0 || f.Percent > 100 {
		return fmt.Errorf("%w: %d", ErrInvalidPercent, f.Percent)
	}
	return nil
}

// Evaluate 判断用户在某个开关下是否命中。Enabled=false 时直接返回 false，
// 不再看 Percent，也不要求 userID 非空，保证“关闭”是真正的兜底。
// 开启后先用 Validate 校验定义，再按 Name 作为 salt 稳定分流。
func Evaluate(f Flag, userID string) (bool, error) {
	if !f.Enabled {
		return false, nil
	}
	if err := Validate(f); err != nil {
		return false, err
	}
	if userID == "" {
		return false, ErrEmptyUserID
	}
	b, err := Bucket(userID, "flag:"+f.Name, 100)
	if err != nil {
		return false, err
	}
	return b < f.Percent, nil
}

// file: internal/experiment/config_test.go
// tier: L1
// verify: go test ./internal/experiment/

package experiment

import (
	"errors"
	"testing"
)

func TestValidate(t *testing.T) {
	if err := Validate(Flag{Name: "new-checkout", Percent: 50}); err != nil {
		t.Fatalf("valid flag = %v, want nil", err)
	}
	if err := Validate(Flag{Name: "  ", Percent: 10}); !errors.Is(err, ErrEmptyFlagName) {
		t.Fatalf("blank name = %v, want ErrEmptyFlagName", err)
	}
	for _, p := range []int{-1, 101} {
		if err := Validate(Flag{Name: "x", Percent: p}); !errors.Is(err, ErrInvalidPercent) {
			t.Fatalf("percent=%d = %v, want ErrInvalidPercent", p, err)
		}
	}
}

func TestEvaluateDisabled(t *testing.T) {
	for _, p := range []int{0, 50, 100, 200} {
		hit, err := Evaluate(Flag{Name: "x", Enabled: false, Percent: p}, "")
		if err != nil {
			t.Fatalf("disabled percent=%d = %v, want nil", p, err)
		}
		if hit {
			t.Fatalf("disabled percent=%d hit = true, want false", p)
		}
	}
}

func TestEvaluateBounds(t *testing.T) {
	for i := 0; i < 200; i++ {
		user := "bound-user-" + itoa(i)
		if hit, err := Evaluate(Flag{Name: "zero", Enabled: true, Percent: 0}, user); err != nil || hit {
			t.Fatalf("percent=0 user=%s = %v, %v; want false, nil", user, hit, err)
		}
		if hit, err := Evaluate(Flag{Name: "full", Enabled: true, Percent: 100}, user); err != nil || !hit {
			t.Fatalf("percent=100 user=%s = %v, %v; want true, nil", user, hit, err)
		}
	}
}

func TestEvaluateStable(t *testing.T) {
	f := Flag{Name: "new-search", Enabled: true, Percent: 37}
	first, err := Evaluate(f, "u-1")
	if err != nil {
		t.Fatalf("Evaluate = %v, want nil", err)
	}
	second, _ := Evaluate(f, "u-1")
	if first != second {
		t.Fatalf("Evaluate changed from %v to %v", first, second)
	}
}

func TestEvaluateRejectsBadInput(t *testing.T) {
	if _, err := Evaluate(Flag{Name: "", Enabled: true, Percent: 10}, "u-1"); !errors.Is(err, ErrEmptyFlagName) {
		t.Fatalf("empty name = %v, want ErrEmptyFlagName", err)
	}
	if _, err := Evaluate(Flag{Name: "x", Enabled: true, Percent: 101}, "u-1"); !errors.Is(err, ErrInvalidPercent) {
		t.Fatalf("percent=101 = %v, want ErrInvalidPercent", err)
	}
	if _, err := Evaluate(Flag{Name: "x", Enabled: true, Percent: 10}, ""); !errors.Is(err, ErrEmptyUserID) {
		t.Fatalf("empty user = %v, want ErrEmptyUserID", err)
	}
}

func TestEvaluateDistribution(t *testing.T) {
	const users = 10000
	f := Flag{Name: "rollout-30", Enabled: true, Percent: 30}
	hits := 0
	for i := 0; i < users; i++ {
		hit, err := Evaluate(f, "dist-user-"+itoa(i))
		if err != nil {
			t.Fatalf("Evaluate = %v, want nil", err)
		}
		if hit {
			hits++
		}
	}
	share := float64(hits) / users
	if share < 0.27 || share > 0.33 {
		t.Fatalf("hit share = %.3f, want 0.30 ±0.03", share)
	}
}

cd .local/checks/webapp-lab && go test ./internal/experiment/ -run 'TestValidate|TestEvaluate' -count=1 -v

=== RUN   TestValidate
--- PASS: TestValidate (0.00s)
=== RUN   TestEvaluateDisabled
--- PASS: TestEvaluateDisabled (0.00s)
=== RUN   TestEvaluateBounds
--- PASS: TestEvaluateBounds (0.00s)
=== RUN   TestEvaluateStable
--- PASS: TestEvaluateStable (0.00s)
=== RUN   TestEvaluateRejectsBadInput
--- PASS: TestEvaluateRejectsBadInput (0.00s)
=== RUN   TestEvaluateDistribution
--- PASS: TestEvaluateDistribution (0.00s)
PASS
ok  	webapp/internal/experiment	0.271s