《互联网产品的服务端架构·内容、社交与实时互动》6.2 计数一致性：精确、近似与对账

// file: internal/counter/reconcile.go
// tier: L1
// verify: go test ./internal/counter/

package counter

import (
	"fmt"
	"math"
)

// Snapshot 是一次对账输入：同一 key 在缓存中的值与存储中的值。
type Snapshot struct {
	Key    Key
	Cached int64
	Stored int64
}

// Drift 返回缓存相对存储的漂移（cached - stored）和漂移率。
// 漂移率 = |drift| / max(stored, 1)：stored 为 0 时分母取 1，
// 即退化为漂移绝对值，避免除零，也让“从 0 涨到 100”有一个明确的比率。
func Drift(cached, stored int64) (int64, float64) {
	drift := cached - stored
	denom := stored
	if denom < 1 {
		denom = 1
	}
	return drift, math.Abs(float64(drift)) / float64(denom)
}

// Evaluate 判断快照是否需要重建，并校验 tolerance。
// tolerance 是允许的漂移率上限，必须在 [0, 1] 内；NaN 和无穷大视为越界。
// 漂移率严格大于 tolerance 时返回 true。
func Evaluate(s Snapshot, tolerance float64) (bool, error) {
	if math.IsNaN(tolerance) || math.IsInf(tolerance, 0) || tolerance < 0 || tolerance > 1 {
		return false, fmt.Errorf("counter: tolerance %v out of range [0,1]", tolerance)
	}
	_, ratio := Drift(s.Cached, s.Stored)
	return ratio > tolerance, nil
}

// NeedsRebuild 是 Evaluate 的便捷版本。为了不在调用侧吞掉错误，
// tolerance 非法时它选择保守重建（返回 true）；需要区分错误时请用 Evaluate。
func NeedsRebuild(s Snapshot, tolerance float64) bool {
	need, err := Evaluate(s, tolerance)
	if err != nil {
		return true
	}
	return need
}

// file: internal/counter/reconcile_test.go
// tier: L1
// verify: go test ./internal/counter/

package counter

import (
	"math"
	"testing"
)

func TestDriftUsesStoredAsDenominator(t *testing.T) {
	cases := []struct {
		name      string
		cached    int64
		stored    int64
		wantDrift int64
		wantRatio float64
	}{
		{"cached-ahead", 105, 100, 5, 0.05},
		{"cached-behind", 95, 100, -5, 0.05},
		{"stored-zero", 7, 0, 7, 7},
		{"both-zero", 0, 0, 0, 0},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			drift, ratio := Drift(c.cached, c.stored)
			if drift != c.wantDrift || ratio != c.wantRatio {
				t.Fatalf("Drift(%d, %d) = %d, %v; want %d, %v",
					c.cached, c.stored, drift, ratio, c.wantDrift, c.wantRatio)
			}
		})
	}
}

func TestEvaluateToleranceIsStrictUpperBound(t *testing.T) {
	s := Snapshot{Key: Key{Counter: Like, TargetID: "post-1"}, Cached: 105, Stored: 100}

	need, err := Evaluate(s, 0.05)
	if err != nil {
		t.Fatalf("Evaluate = %v, want nil", err)
	}
	if need {
		t.Fatal("ratio equal to tolerance must not rebuild")
	}

	need, err = Evaluate(s, 0.049)
	if err != nil {
		t.Fatalf("Evaluate = %v, want nil", err)
	}
	if !need {
		t.Fatal("ratio above tolerance must rebuild")
	}
}

func TestEvaluateRejectsInvalidTolerance(t *testing.T) {
	s := Snapshot{Cached: 1, Stored: 1}
	for _, tolerance := range []float64{-0.1, 1.1, math.NaN(), math.Inf(1), math.Inf(-1)} {
		if _, err := Evaluate(s, tolerance); err == nil {
			t.Fatalf("Evaluate tolerance %v = nil, want error", tolerance)
		}
		if !NeedsRebuild(s, tolerance) {
			t.Fatalf("NeedsRebuild tolerance %v = false, want conservative true", tolerance)
		}
	}
}

func TestNeedsRebuildZeroStored(t *testing.T) {
	if !NeedsRebuild(Snapshot{Cached: 3, Stored: 0}, 0) {
		t.Fatal("any drift from zero stored must rebuild at tolerance 0")
	}
	if NeedsRebuild(Snapshot{Cached: 0, Stored: 0}, 0) {
		t.Fatal("zero drift must not rebuild")
	}
}

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

=== RUN   TestDriftUsesStoredAsDenominator
=== RUN   TestDriftUsesStoredAsDenominator/cached-ahead
=== RUN   TestDriftUsesStoredAsDenominator/cached-behind
=== RUN   TestDriftUsesStoredAsDenominator/stored-zero
=== RUN   TestDriftUsesStoredAsDenominator/both-zero
--- PASS: TestDriftUsesStoredAsDenominator (0.00s)
    --- PASS: TestDriftUsesStoredAsDenominator/cached-ahead (0.00s)
    --- PASS: TestDriftUsesStoredAsDenominator/cached-behind (0.00s)
    --- PASS: TestDriftUsesStoredAsDenominator/stored-zero (0.00s)
    --- PASS: TestDriftUsesStoredAsDenominator/both-zero (0.00s)
=== RUN   TestEvaluateToleranceIsStrictUpperBound
--- PASS: TestEvaluateToleranceIsStrictUpperBound (0.00s)
=== RUN   TestEvaluateRejectsInvalidTolerance
--- PASS: TestEvaluateRejectsInvalidTolerance (0.00s)
=== RUN   TestNeedsRebuildZeroStored
--- PASS: TestNeedsRebuildZeroStored (0.00s)
PASS
ok  	webapp/internal/counter	0.766s