3.1 惰性补充 vs 定时补充#

令牌补充有两种实现方式。一种是定时补充：启动一个后台定时器，每隔固定间隔往桶里加令牌。这种方式直观，但问题不少——定时器有精度开销，多一个 goroutine/线程需要管理，而且定时器频率和补充速率的匹配也不自然（rate=0.7 个/秒时，你很难用 1 秒的定时器精确补充 0.7 个令牌）。

另一种是惰性补充（Lazy Refill）：不跑定时器，只在请求到来时才计算”从上次到现在，应该补充多少令牌”。公式很简单：

1
新增令牌 = 经过秒数 × 补充速率
2
当前令牌 = min(容量, 当前令牌 + 新增令牌)

惰性补充的好处是零额外开销——没有后台线程，没有定时器，所有计算都在请求路径上完成，且只有 O(1) 的时间复杂度。Go 官方的 x/time/rate 和 Guava 的 RateLimiter 都采用这种方式。

3.2 令牌累积的数学#

令牌桶的长期平均速率严格等于 rate，这一点可以用简单的数学验证。假设桶初始为空，经过 T 秒后，最多补充 T × rate 个令牌。如果这段时间内持续有请求，最多也只能消耗 T × rate 个令牌（因为补充是上限）。所以长期来看，通过速率不会超过 rate。

短期的突发量则受 capacity 约束。桶最多存 capacity 个令牌，所以即使桶是满的，一次最多也只能放行 capacity 个请求。突发过后，令牌耗尽，后续请求只能等补充——速率回到 rate。这就是令牌桶”允许突发，但限制持续速率”的数学基础。

3.3 容量上限为什么重要#

min(容量, 当前令牌 + 新增令牌) 中的 min 不是可有可无的。如果没有容量上限，令牌会无限累积——系统空闲 1 小时后，桶里攒了 3600 × rate 个令牌，突然来一波流量时，瞬间全部放行，等于没有限流。容量上限确保了”攒额度”是有界的，突发量被控制在合理范围内。

选择 capacity 的值需要权衡：太小，正常的短时突发（比如页面加载时的并发请求）会被误杀；太大，突发保护形同虚设。通常 capacity 设为 rate 的 1-3 倍，或者根据业务场景的典型突发量来定。

4.1 固定窗口的边界问题详解#

固定窗口是最容易实现的限流算法——一个计数器加一个定时重置。但它的边界突发问题在实际中很致命。来看一个具体例子：

1
固定窗口：每分钟 100 个请求
2

3
时间线：
4
  11:00:00 ─────────── 11:00:59 ── 11:01:00 ─────────── 11:01:59
5
  [        窗口 1        ]          [        窗口 2        ]
6
                          ↑ 重置计数器
7

8
客户端行为：
9
  11:00:59 发送 100 个请求 → 全部通过（窗口 1 计数 = 100）
10
  11:01:01 发送 100 个请求 → 全部通过（窗口 2 计数 = 100）
11

12
结果：2 秒内通过 200 个请求，是限额的两倍

这个问题在窗口越短时越严重。如果用 1 秒的窗口，边界处的突发窗口只有几毫秒，但那几毫秒内的双倍流量仍然可能打挂下游。滑动窗口通过在窗口内做加权统计解决了这个问题，但实现复杂度更高。令牌桶则从根本上避免了这个问题——令牌是连续补充的，不存在”窗口重置”这个概念。

4.2 令牌桶 vs 漏桶#

令牌桶和漏桶经常被混淆，但它们的行为有本质区别。令牌桶允许突发：桶里有攒下的令牌时，请求可以瞬间通过。漏桶不允许突发：不管来了多少请求，输出速率始终恒定。

选择取决于下游的承受能力。如果下游是另一个 API，短时间的突发通常没问题——TCP 本身就有拥塞控制，HTTP 客户端也有连接池，用令牌桶就好。如果下游是一个不能承受任何突发的系统——比如数据库的写入速率有硬上限，或者消息队列的消费端需要严格匀速——那就用漏桶，把流量”抹平”后再输出。

4.3 滑动窗口的适用场景#

滑动窗口（尤其是滑动日志式）能精确统计时间窗口内的请求数，适合需要严格计数的场景，比如”每用户每天最多调用 1000 次”这种配额管理。但它的内存开销与窗口内的请求数成正比（需要记录每个请求的时间戳），高 QPS 场景下不太适用。滑动窗口计数器（Sliding Window Counter）是折中方案——用多个固定窗口做加权，精度接近滑动窗口，但内存开销是 O(窗口数) 而非 O(请求数)。

5.1 Go 实现#

1
package ratelimiter
2

3
import (
4
  "sync"
5
  "time"
6
)
7

8
// TokenBucket 令牌桶限流器
9
type TokenBucket struct {
10
  mu          sync.Mutex
11
  capacity    float64   // 桶容量（最大令牌数）
12
  refillRate  float64   // 每秒补充的令牌数
13
  tokens      float64   // 当前令牌数
14
  lastRefill  time.Time // 上次补充时间
15
}
16

17
func NewTokenBucket(capacity, refillRate float64) *TokenBucket {
18
  return &TokenBucket{
19
    capacity:   capacity,
20
    refillRate: refillRate,
21
    tokens:     capacity, // 初始满载
22
    lastRefill: time.Now(),
23
  }
24
}
25

26
func (tb *TokenBucket) TryAcquire(n float64) bool {
27
  tb.mu.Lock()
28
  defer tb.mu.Unlock()
29

30
  // 惰性补充：按经过时间计算应补充的令牌
31
  now := time.Now()
32
  elapsed := now.Sub(tb.lastRefill).Seconds()
33
  tb.tokens = min(tb.capacity, tb.tokens+elapsed*tb.refillRate)
34
  tb.lastRefill = now
35

36
  // 判断令牌是否足够
37
  if tb.tokens >= n {
38
    tb.tokens -= n
39
    return true
40
  }
41
  return false
42
}
43

44
func min(a, b float64) float64 {
45
  if a < b {
46
    return a
47
  }
48
  return b
49
}

Go 版本的关键在于”惰性补充”——不在后台跑定时器往桶里加令牌，而是在每次 TryAcquire 时才计算应该补充多少。这样实现简单，不需要额外的 goroutine，也不会有定时器的精度问题。

注意 sync.Mutex 的使用。令牌桶的状态（tokens 和 lastRefill）必须作为一个整体来读写，否则会出现竞态条件：两个 goroutine 同时读到相同的 lastRefill，各自计算补充量，导致令牌被重复补充。Mutex 保证了”补充 + 扣减”是一个原子操作。

TryAcquire 的参数 n 允许一次消耗多个令牌，这对”不同操作消耗不同配额”的场景很有用——比如读操作消耗 1 个令牌，写操作消耗 5 个令牌。

5.2 TypeScript 实现#

1
class TokenBucket {
2
  private tokens: number;
3
  private lastRefill: number;
4

5
  constructor(
6
    private capacity: number,    // 桶容量
7
    private refillRate: number,  // 每秒补充令牌数
8
  ) {
9
    this.tokens = capacity;      // 初始满载
10
    this.lastRefill = Date.now();
11
  }
12

13
  /** 惰性补充：计算从上次到现在应补充的令牌 */
14
  private refill(): void {
15
    const now = Date.now();
16
    const elapsed = (now - this.lastRefill) / 1000;
17
    this.tokens = Math.min(
18
      this.capacity,
19
      this.tokens + elapsed * this.refillRate,
20
    );
21
    this.lastRefill = now;
22
  }
23

24
  tryAcquire(tokens = 1): boolean {
25
    this.refill();
26
    if (this.tokens >= tokens) {
27
      this.tokens -= tokens;
28
      return true;
29
    }
30
    return false;
31
  }
32
}

TypeScript 版本逻辑完全一致。refill() 是私有方法，在每次 tryAcquire 前调用。浮点数精度在 JavaScript 里不是问题——限流器本身就是近似算法，不需要精确到小数点后 N 位。

JavaScript 的单线程模型意味着不需要显式加锁——tryAcquire 不会被两个”线程”同时执行。但要注意 async 场景：如果 tryAcquire 内部有 await，在等待期间其他代码可能修改 tokens 和 lastRefill。所以限流器的核心逻辑应该保持同步，不要在里面放异步操作。

5.3 分布式限流的挑战#

单机限流器只能保护单个节点。当你的服务部署了多台机器时，每台各自维护一个令牌桶，全局的实际限制变成了 rate × 节点数。要执行全局速率，必须引入共享存储。

Redis 是最常见的选择。基本思路是把令牌桶的状态存到 Redis 里，每次请求时用 Lua 脚本原子地执行”补充 + 判断 + 扣减”。Lua 脚本在 Redis 中是原子执行的，不会被打断，所以不会出现竞态条件。

但分布式限流引入了新的权衡。每次请求都要访问 Redis，延迟从纳秒级（内存操作）变成了毫秒级（网络往返）。如果 Redis 不可用，你要么放行所有请求（限流失效），要么拒绝所有请求（服务降级），没有中间选项。这是典型的 CAP 取舍——在”一致性”（精确的全局限流）和”可用性”（Redis 挂了仍能服务）之间，你只能选一个。

实践中常见的折中方案是”本地 + 全局”双层限流：每个节点维护一个本地令牌桶做粗粒度限流（比如全局限额的 1/N），同时用 Redis 做更精确的全局限流。本地限流作为第一道防线，即使 Redis 挂了也能提供基本保护。