3. 接口契约定义：Go中如何定义限流与延迟的接口契约（Interface Contract）

在分布式系统中，限流与尾延迟治理不能仅依赖运维层面的“事后”监控，而必须在代码层面建立明确的接口契约。Go 语言的 interface 类型天然适合定义这种行为约束——它规定了“调用方可以期待什么”以及“实现方必须承诺什么”。本章将围绕限流与延迟两个核心维度，给出标准化的接口定义、参数约定与错误语义。

3.1 限流接口契约：RateLimiter

一个通用的限流器接口需要同时支持同步阻塞与异步非阻塞两种调用模式，并能够暴露当前的限流状态。以下是在生产环境中经过验证的接口定义：

// RateLimiter 定义限流器的核心契约
type RateLimiter interface {
    // Allow 非阻塞判断：是否允许当前请求通过
    // 返回 true 表示允许，false 表示被限流
    Allow() bool

    // Wait 阻塞等待，直到令牌可用或上下文取消
    // 返回 error 表示等待过程中被中断（ctx 取消/超时）
    Wait(ctx context.Context) error

    // Tokens 返回当前可用令牌数（用于监控与自适应算法）
    Tokens() int64

    // Rate 返回当前配置的速率（每秒请求数）
    Rate() float64
}

3.2 延迟接口契约：LatencyObserver

尾延迟治理的前提是能够观测延迟分布。接口契约不应只暴露平均值，而应提供分位数（p50/p90/p99）与滑动窗口内的延迟样本：

// LatencyObserver 定义延迟观测器的核心契约
type LatencyObserver interface {
    // Record 记录一次请求的延迟（单位：毫秒）
    Record(latencyMs float64)

    // Percentile 返回指定分位数的延迟值
    // p 取值范围 [0.0, 1.0]，例如 0.99 表示 p99
    Percentile(p float64) float64

    // WindowStats 返回当前滑动窗口内的统计摘要
    WindowStats() LatencyStats
}

// LatencyStats 延迟统计快照
type LatencyStats struct {
    Min     float64   // 最小延迟
    Max     float64   // 最大延迟
    Avg     float64   // 平均延迟
    P50     float64   // 中位数延迟
    P90     float64   // 90% 延迟
    P99     float64   // 99% 延迟
    Count   int64     // 窗口内请求总数
}

3.3 限流与延迟的联合契约：AdaptiveController

在自适应保护场景中，限流器需要根据延迟反馈动态调整速率。此时需要一个组合接口，将限流与观测能力绑定在一起：

// AdaptiveController 自适应限流控制器
type AdaptiveController interface {
    RateLimiter
    LatencyObserver

    // Update 根据当前延迟指标调整限流参数
    // 返回调整后的速率
    Update(ctx context.Context) float64

    // State 返回当前控制器的运行状态
    State() ControllerState
}

type ControllerState struct {
    CurrentRate  float64 // 当前速率
    TargetLatency float64 // 目标延迟（p99）
    ActualP99    float64 // 实际 p99 延迟
    DroppedCount int64   // 被限流丢弃的请求数
}

3.4 接口契约对比

3.5 接口契约的依赖关系

下图展示了限流与延迟接口在微服务调用链中的位置关系，以及它们如何共同作用于请求路径：

3.6 错误语义与零值约定

接口契约的健壮性还体现在对边界情况的明确约定上。以下是限流与延迟接口的常见错误语义表：

3.7 接口契约的测试与文档化

定义接口之后，还需要通过契约测试来保证所有实现都遵守相同的行为。Go 中可以使用 go:generate 配合 counterfeiter 或 mockgen 生成 mock，但更推荐直接编写接口一致性测试套件：

// RateLimiterContractTest 验证 RateLimiter 接口契约
func RateLimiterContractTest(t *testing.T, limiter RateLimiter) {
    // 1. 初始状态应该有令牌
    if limiter.Tokens() <= 0 {
        t.Error("初始令牌数应大于 0")
    }

    // 2. Allow 在未耗尽时返回 true
    for i := 0; i < int(limiter.Tokens()); i++ {
        if !limiter.Allow() {
            t.Errorf("第 %d 次 Allow 应返回 true", i)
        }
    }

    // 3. 耗尽后 Allow 返回 false
    if limiter.Allow() {
        t.Error("令牌耗尽后 Allow 应返回 false")
    }

    // 4. Wait 在上下文取消时返回 error
    ctx, cancel := context.WithCancel(context.Background())
    cancel()
    if err := limiter.Wait(ctx); err == nil {
        t.Error("已取消的上下文应返回 error")
    }
}