《后端架构设计·演进与治理》7.1 SLI 定义：指标、窗口与用户视角

// file: internal/platform/slo/sli.go
// tier: L1
// verify: go test ./internal/platform/slo/ -count=1 -run 'TestSLI|TestWindow|TestNoData|TestDefinition'
package slo

import (
	"errors"
	"fmt"
	"time"
)

// Event is one outcome observed as close to the user as possible.
type Event struct {
	At            time.Time
	Route         string
	UserInitiated bool
	Good          bool
	Latency       time.Duration
}

// SLI is a ratio of good events to valid events.
type SLI struct {
	Name              string
	LatencyThreshold  time.Duration // zero means availability
	IncludeBackground bool
}

func (s SLI) Validate() error {
	if s.Name == "" {
		return errors.New("slo: SLI name is required")
	}
	if s.LatencyThreshold < 0 {
		return fmt.Errorf("slo: negative latency threshold %s", s.LatencyThreshold)
	}
	return nil
}

func (s SLI) inScope(e Event) bool { return s.IncludeBackground || e.UserInitiated }

// Valid reports whether e belongs in the denominator.
func (s SLI) Valid(e Event) bool { return s.inScope(e) }

// Good reports whether e belongs in the numerator.
func (s SLI) Good(e Event) bool {
	if !s.inScope(e) || !e.Good {
		return false
	}
	return s.LatencyThreshold == 0 || e.Latency <= s.LatencyThreshold
}

// Window is a half-open interval [Start, End).
type Window struct{ Start, End time.Time }

func (w Window) Contains(t time.Time) bool { return !t.Before(w.Start) && t.Before(w.End) }

func (w Window) Validate() error {
	if !w.End.After(w.Start) {
		return fmt.Errorf("slo: window end %s not after start %s", w.End, w.Start)
	}
	return nil
}

// Measurement is one SLI evaluated over one window.
type Measurement struct {
	SLI      string
	Window   Window
	Good     int
	Valid    int
	Excluded int
	MinValid int
}

// Ratio returns 1 with no valid events while Sufficient is false: a dashboard
// must show "no data", not 100%.
func (m Measurement) Ratio() float64 {
	if m.Valid == 0 {
		return 1
	}
	return float64(m.Good) / float64(m.Valid)
}

func (m Measurement) Sufficient() bool { return m.Valid >= m.MinValid }

// Coverage is the share of observed events that entered the denominator.
func (m Measurement) Coverage() float64 {
	if m.Valid+m.Excluded == 0 {
		return 0
	}
	return float64(m.Valid) / float64(m.Valid+m.Excluded)
}

// Measure evaluates s over w; excluded events never enter the numerator.
func Measure(events []Event, s SLI, w Window, minValid int) (Measurement, error) {
	if err := s.Validate(); err != nil {
		return Measurement{}, err
	}
	if err := w.Validate(); err != nil {
		return Measurement{}, err
	}
	if minValid < 0 {
		return Measurement{}, fmt.Errorf("slo: negative minimum sample %d", minValid)
	}
	m := Measurement{SLI: s.Name, Window: w, MinValid: minValid}
	for _, e := range events {
		switch {
		case !w.Contains(e.At):
		case !s.Valid(e):
			m.Excluded++
		default:
			m.Valid++
			if s.Good(e) {
				m.Good++
			}
		}
	}
	return m, nil
}

// Rolling returns the trailing window [end-d, end).
func Rolling(end time.Time, d time.Duration) Window { return Window{end.Add(-d), end} }

// CalendarDay returns the UTC day containing at.
func CalendarDay(at time.Time) Window {
	t := at.UTC()
	start := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, time.UTC)
	return Window{start, start.AddDate(0, 0, 1)}
}

=== RUN   TestSLIMeasure
    sli_test.go:52: availability good=7040 valid=7200 excluded=720 ratio=0.977778 coverage=0.9091
    sli_test.go:60: with-background good=7040 valid=7920 ratio=0.888889
    sli_test.go:67: latency good=4224 valid=7200 ratio=0.586667
--- PASS: TestSLIMeasure (0.00s)
=== RUN   TestWindowBoundaries
    sli_test.go:80: at=2026-10-31T12:00:00Z rolling[10-30T12,10-31T12) good=2360 valid=2400 ratio=0.983333
    sli_test.go:82: at=2026-10-31T12:00:00Z calendar[10-31T00,11-01T00) good=2340 valid=2400 ratio=0.975000
--- PASS: TestWindowBoundaries (0.00s)
=== RUN   TestNoDataIsNotHealthy
    sli_test.go:95: empty window ratio=1.00 sufficient=false coverage=0.00
--- PASS: TestNoDataIsNotHealthy (0.00s)
=== RUN   TestDefinitionValidation
    sli_test.go:116: missing name rejected: slo: SLI name is required
    sli_test.go:116: negative latency rejected: slo: negative latency threshold -1s
    sli_test.go:116: inverted window rejected: slo: window end 2026-10-29 00:00:00 +0000 UTC not after start 2026-11-01 00:00:00 +0000 UTC
    sli_test.go:116: negative minimum rejected: slo: negative minimum sample -1
--- PASS: TestDefinitionValidation (0.00s)
PASS
ok  	archlab/internal/platform/slo	0.319s

// file: internal/platform/slo/sli_test.go
// tier: L1
// verify: go test ./internal/platform/slo/ -count=1 -run 'TestSLI|TestWindow|TestNoData|TestDefinition'
package slo

import (
	"testing"
	"time"
)

var t0 = time.Date(2026, 10, 29, 0, 0, 0, 0, time.UTC)

// sampleEvents builds 72 hours of traffic: 100 user requests and 10 background
// jobs per hour, with a 20% user-visible failure every tenth hour.
func sampleEvents() []Event {
	var out []Event
	for h := 0; h < 72; h++ {
		at := t0.Add(time.Duration(h) * time.Hour)
		for i := 0; i < 100; i++ {
			out = append(out, Event{
				At:            at.Add(time.Duration(i) * time.Second),
				Route:         "/orders",
				UserInitiated: true,
				Good:          !(h%10 == 0 && i < 20),
				Latency:       time.Duration(40+i%5) * time.Millisecond,
			})
		}
		for i := 0; i < 10; i++ {
			out = append(out, Event{
				At:            at.Add(time.Duration(i) * time.Second),
				Route:         "/orders/reconcile",
				UserInitiated: false,
				Good:          false,
				Latency:       2 * time.Second,
			})
		}
	}
	return out
}

func TestSLIMeasure(t *testing.T) {
	events := sampleEvents()
	full := Window{Start: t0, End: t0.Add(72 * time.Hour)}

	m, err := Measure(events, SLI{Name: "orders-availability"}, full, 1000)
	if err != nil {
		t.Fatalf("Measure: %v", err)
	}
	if m.Good != 7040 || m.Valid != 7200 || m.Excluded != 720 {
		t.Fatalf("good=%d valid=%d excluded=%d", m.Good, m.Valid, m.Excluded)
	}
	t.Logf("availability good=%d valid=%d excluded=%d ratio=%.6f coverage=%.4f",
		m.Good, m.Valid, m.Excluded, m.Ratio(), m.Coverage())

	withBackground := SLI{Name: "orders-availability", IncludeBackground: true}
	mb, _ := Measure(events, withBackground, full, 1000)
	if mb.Ratio() >= m.Ratio() {
		t.Fatalf("background traffic raised the SLI: %.6f", mb.Ratio())
	}
	t.Logf("with-background good=%d valid=%d ratio=%.6f", mb.Good, mb.Valid, mb.Ratio())

	latency := SLI{Name: "orders-latency", LatencyThreshold: 42 * time.Millisecond}
	ml, _ := Measure(events, latency, full, 1000)
	if ml.Good != 4224 || ml.Valid != 7200 {
		t.Fatalf("latency good=%d valid=%d", ml.Good, ml.Valid)
	}
	t.Logf("latency good=%d valid=%d ratio=%.6f", ml.Good, ml.Valid, ml.Ratio())
}

func TestWindowBoundaries(t *testing.T) {
	events := sampleEvents()
	avail := SLI{Name: "orders-availability"}
	at := t0.Add(60 * time.Hour)

	roll, _ := Measure(events, avail, Rolling(at, 24*time.Hour), 100)
	cal, _ := Measure(events, avail, CalendarDay(at), 100)
	if roll.Ratio() == cal.Ratio() {
		t.Fatalf("rolling and calendar windows should differ at %s", at)
	}
	t.Logf("at=%s rolling[%s,%s) good=%d valid=%d ratio=%.6f", at.Format(time.RFC3339),
		roll.Window.Start.Format("01-02T15"), roll.Window.End.Format("01-02T15"), roll.Good, roll.Valid, roll.Ratio())
	t.Logf("at=%s calendar[%s,%s) good=%d valid=%d ratio=%.6f", at.Format(time.RFC3339),
		cal.Window.Start.Format("01-02T15"), cal.Window.End.Format("01-02T15"), cal.Good, cal.Valid, cal.Ratio())
}

func TestNoDataIsNotHealthy(t *testing.T) {
	empty := Window{Start: t0.Add(-time.Hour), End: t0}
	m, err := Measure(sampleEvents(), SLI{Name: "orders-availability"}, empty, 10)
	if err != nil {
		t.Fatalf("Measure: %v", err)
	}
	if m.Sufficient() || m.Ratio() != 1 || m.Coverage() != 0 {
		t.Fatalf("empty window ratio=%.2f sufficient=%v coverage=%.2f", m.Ratio(), m.Sufficient(), m.Coverage())
	}
	t.Logf("empty window ratio=%.2f sufficient=%v coverage=%.2f", m.Ratio(), m.Sufficient(), m.Coverage())
}

func TestDefinitionValidation(t *testing.T) {
	events := sampleEvents()
	full := Window{Start: t0, End: t0.Add(72 * time.Hour)}
	cases := []struct {
		name string
		sli  SLI
		w    Window
		min  int
	}{
		{"missing name", SLI{}, full, 100},
		{"negative latency", SLI{Name: "x", LatencyThreshold: -time.Second}, full, 100},
		{"inverted window", SLI{Name: "x"}, Window{full.End, full.Start}, 100},
		{"negative minimum", SLI{Name: "x"}, full, -1},
	}
	for _, c := range cases {
		if _, err := Measure(events, c.sli, c.w, c.min); err == nil {
			t.Fatalf("%s: expected an error", c.name)
		} else {
			t.Logf("%s rejected: %v", c.name, err)
		}
	}
}