2. Go 标准库限流：golang.org/x/time/rate 库介绍、基于令牌桶的实现原理、基本使用方法

2.1 为什么选择标准库限流

在 Go 生态中，golang.org/x/time/rate 是官方扩展库提供的限流组件，也是生产环境中最广泛使用的限流实现之一。它基于经典的 令牌桶（Token Bucket） 算法，提供了简洁、高效、线程安全的限流能力。

2.2 令牌桶算法原理

令牌桶算法是限流领域最经典的算法之一，其核心思想是：系统以恒定速率向桶中放入令牌，每个请求需要消耗一个令牌才能被处理。桶有最大容量，超过容量的令牌被丢弃。

2.3 核心数据结构

rate.Limiter 是限流器的核心结构体，其内部维护了三个关键参数：

2.4 基本使用方法

使用 rate.NewLimiter 创建限流器，然后通过 Allow()、Reserve() 或 Wait() 三种方式控制流量。

2.4.1 创建限流器

import "golang.org/x/time/rate"

// 每秒生成 10 个令牌，桶容量为 20（允许突发 20 个请求）
limiter := rate.NewLimiter(10, 20)

2.4.2 三种消费方式对比

2.4.3 完整示例代码

package main

import (
    "context"
    "fmt"
    "golang.org/x/time/rate"
    "time"
)

func main() {
    // 每秒 5 个请求，突发 10 个
    limiter := rate.NewLimiter(5, 10)

    // 方式一：Allow（非阻塞）
    if limiter.Allow() {
        fmt.Println("请求通过")
    } else {
        fmt.Println("请求被限流")
    }

    // 方式二：Reserve（非阻塞，可查询等待时间）
    r := limiter.Reserve()
    if r.OK() {
        delay := r.Delay()
        if delay > 0 {
            fmt.Printf("需要等待 %v\n", delay)
            time.Sleep(delay)
        }
        fmt.Println("请求通过")
    }

    // 方式三：Wait（阻塞）
    ctx := context.Background()
    if err := limiter.Wait(ctx); err != nil {
        fmt.Println("等待被取消:", err)
    } else {
        fmt.Println("请求通过")
    }
}

2.5 令牌桶的数学特性

理解令牌桶的数学行为有助于合理配置参数：

• 长期平均速率：等于 limit 值，即每秒 r 个请求。
• 突发能力：桶初始满时，可一次性消费 burst 个令牌，实现突发流量。
• 恢复时间：桶空后，需要 burst / r 秒才能重新填满。
• 空闲积累：桶最多积累 burst 个令牌，不会无限增长。

2.6 常见配置模式

2.7 性能基准

在压测场景下，rate.Limiter 的单次 Allow() 调用性能表现如下：