《游戏服务端编程实践》14.1 心跳与健康检查

// file: ch14/heartbeat/heartbeat.go
// tier: L1
// verify: go test ./ch14/heartbeat/

package heartbeat

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

// State 是检测器对单个节点的判定结果。
type State uint8

const (
	// Unknown 表示还没有收到过心跳，此时既不能判活也不能判死。
	Unknown State = iota
	// Healthy 表示最近一次扫描时，距离上次心跳仍在超时窗口内。
	Healthy
	// Suspect 表示已经超出超时窗口，但连续丢失次数还没达到摘除阈值。
	Suspect
	// Evicted 表示连续丢失达到阈值，节点应从可用列表中摘除。
	Evicted
)

// String 让状态在日志与指标里保持可读。
func (s State) String() string {
	switch s {
	case Unknown:
		return "unknown"
	case Healthy:
		return "healthy"
	case Suspect:
		return "suspect"
	case Evicted:
		return "evicted"
	default:
		return fmt.Sprintf("state(%d)", uint8(s))
	}
}

var (
	// ErrInvalidInterval 表示心跳间隔没有配置成正数。
	ErrInvalidInterval = errors.New("heartbeat: interval must be positive")
	// ErrTimeoutTooSmall 表示超时窗口没有明显大于心跳间隔。
	ErrTimeoutTooSmall = errors.New("heartbeat: timeout must be greater than interval")
	// ErrInvalidMisses 表示摘除阈值没有配置成正数。
	ErrInvalidMisses = errors.New("heartbeat: misses before evict must be positive")
	// ErrInvalidRecovery 表示重新加入所需的连续心跳数没有配置成正数。
	ErrInvalidRecovery = errors.New("heartbeat: beats before ready must be positive")
)

// Config 描述一个节点的检测参数。
//
// Interval 是发送方承诺的心跳周期。Timeout 是一次心跳可以被容忍的
// 最大静默时间，必须严格大于 Interval：如果两者相等，任何一个网络
// 抖动都会被当成丢包。MissesBeforeEvict 是连续超出 Timeout 的扫描
// 次数，BeatsBeforeReady 是节点被摘除后重新加入所需的连续心跳数。
type Config struct {
	Interval          time.Duration
	Timeout           time.Duration
	MissesBeforeEvict int
	BeatsBeforeReady  int
}

func (c Config) validate() error {
	if c.Interval <= 0 {
		return ErrInvalidInterval
	}
	if c.Timeout <= c.Interval {
		return ErrTimeoutTooSmall
	}
	if c.MissesBeforeEvict <= 0 {
		return ErrInvalidMisses
	}
	if c.BeatsBeforeReady <= 0 {
		return ErrInvalidRecovery
	}
	return nil
}

// Snapshot 是某一时刻的只读观测结果。
type Snapshot struct {
	State    State
	Misses   int
	LastSeen time.Time
}

// Detector 维护单个节点的心跳状态。
//
// 检测完全由调用方注入的时间驱动：Observe 在收到心跳时调用，
// Sweep 由扫描循环按 Interval 周期调用。把时间作为参数传入，
// 既避免了测试里 sleep 的不确定性，也让跨机房时钟问题在调用层
// 显式暴露，而不是藏在 time.Now 里。
type Detector struct {
	mu       sync.Mutex
	cfg      Config
	lastSeen time.Time
	misses   int
	beats    int
	state    State
}

// NewDetector 校验配置并创建一个未收到任何心跳的检测器。
func NewDetector(cfg Config) (*Detector, error) {
	if err := cfg.validate(); err != nil {
		return nil, err
	}
	return &Detector{cfg: cfg, state: Unknown}, nil
}

// Observe 记录一次心跳到达，并返回记录后的状态。
//
// 健康节点的任何一次心跳都会把丢失计数清零。被摘除的节点不会
// 因为一次心跳立刻复活，而要连续收到 BeatsBeforeReady 次心跳，
// 防止抖动中的单个包把故障节点重新塞回流量。
func (d *Detector) Observe(now time.Time) State {
	d.mu.Lock()
	defer d.mu.Unlock()

	d.lastSeen = now
	if d.state == Evicted {
		d.beats++
		if d.beats < d.cfg.BeatsBeforeReady {
			return d.state
		}
		d.misses = 0
		d.beats = 0
		d.state = Healthy
		return d.state
	}
	d.misses = 0
	d.beats = 0
	d.state = Healthy
	return d.state
}

// Sweep 执行一次周期扫描，调用方应大约每 Interval 调用一次。
//
// 扫描不会推进 lastSeen；只有 Observe 能刷新它。距离上次心跳
// 不超过 Timeout 时视为健康，超过则累计一次连续丢失。累计值
// 达到 MissesBeforeEvict 后节点进入 Evicted，直到 Observe 把它
// 拉回。已摘除的节点不会被扫描自动复活，因此时钟回拨最多造成
// 一次误判，不会让摘除状态来回翻转。
func (d *Detector) Sweep(now time.Time) State {
	d.mu.Lock()
	defer d.mu.Unlock()

	if d.state == Unknown || d.state == Evicted {
		return d.state
	}
	if now.Sub(d.lastSeen) <= d.cfg.Timeout {
		d.misses = 0
		d.state = Healthy
		return d.state
	}
	d.misses++
	if d.misses >= d.cfg.MissesBeforeEvict {
		d.beats = 0
		d.state = Evicted
		return d.state
	}
	d.state = Suspect
	return d.state
}

// Snapshot 返回状态、连续丢失次数和上次心跳时间。
func (d *Detector) Snapshot() Snapshot {
	d.mu.Lock()
	defer d.mu.Unlock()
	return Snapshot{State: d.state, Misses: d.misses, LastSeen: d.lastSeen}
}

// Config 返回创建时校验过的配置副本。
func (d *Detector) Config() Config {
	return d.cfg
}

cd .local/checks/gs-practice-lab
gofmt -l ch14/heartbeat
go vet ./ch14/heartbeat/
go test ./ch14/heartbeat/ -count=1