4. 行情API客户端限流器设计

服务端的速率限制是外部约束，客户端限流器则是我们主动加在自己与交易所之间的一道闸门。它的价值不在于“重复实现服务端规则”，而在于把不可控的 429 响应转化为可控的本地排队与等待，从而减少无效请求、避免封禁、平滑突发流量。本节围绕令牌桶这一经典模型，讲清楚它在行情 API 客户端中的具体实现方式，包括每秒/每分钟双维度控制、突发容量设置，以及如何与重试机制衔接。

为什么行情客户端需要自己的限流器

行情 API 的调用有几个典型特征：一是频率高，订阅、快照、历史 K 线拉取往往在启动阶段集中爆发；二是权重不均，不同接口消耗的配额不同；三是失败代价高，一旦触发服务端封禁，整个行情链路会中断。如果客户端不做任何节流，多个协程或线程同时发起请求，很容易在几百毫秒内打满配额。限流器的作用就是把这些并发请求收敛到一个稳定的输出速率上，并在配额不足时让调用方等待而不是直接失败。

令牌桶模型之所以适合这一场景，是因为它同时具备两个能力：稳态速率控制和突发容量允许。桶以固定速率补充令牌，请求取走令牌才能发出；桶的容量决定了短时间内可以积攒多少令牌，也就决定了允许的突发量。这与交易所“每秒 N 次、允许一定突发”的配额模型天然吻合。

令牌桶的核心参数与双维度控制

一个实用的行情客户端限流器通常需要同时满足“每秒请求数”和“每分钟请求数”两个约束。单桶只能表达一个速率，因此常见做法是为每个维度各维护一个令牌桶，请求必须同时从两个桶中取到令牌才放行。例如配置每秒 10 次、每分钟 300 次：秒桶容量设为 10、补充速率 10/s；分钟桶容量设为 300、补充速率 5/s（300/60）。当秒级突发被允许时，分钟桶会同步扣减，从而防止“每秒都不超但一分钟累计超标”的情况。

参数选择上有几个经验点。秒桶容量不宜远大于每秒速率，否则启动瞬间会放出过多请求；分钟桶容量可以略大于每分钟速率，用于吸收短时集中拉取。补充速率必须严格按“配额/周期”换算，避免单位错误导致实际速率翻倍或减半。下面是一个可直接参考的参数配置示例：

# 限流器配置示例（示例参数，非实测值）
rate_per_second: 10        # 每秒允许请求数
burst_per_second: 10       # 秒桶容量
rate_per_minute: 300       # 每分钟允许请求数
burst_per_minute: 300      # 分钟桶容量
acquire_timeout_ms: 2000   # 单次取令牌最长等待
weighted_endpoints:        # 按接口权重扣减
  /market/ticker: 1
  /market/depth: 2
  /market/klines: 5

实现要点：惰性补充与阻塞等待

令牌桶不需要后台定时器持续“加令牌”，更常见的做法是惰性补充：每次取令牌时，根据当前时间与上次补充时间的差值，计算应补充的令牌数，并封顶到桶容量。这样实现简单、无额外线程，也便于测试。取令牌时若令牌不足，有两种策略：立即返回失败，或阻塞等待到下一个令牌可用。行情客户端通常选择带超时的阻塞等待，超时后再交由上层重试或降级。

下面给出一个简化的 Python 实现，体现双桶扣减与惰性补充逻辑：

import time, threading

class TokenBucket:
    def __init__(self, rate, capacity):
        self.rate = rate            # 每秒补充令牌数
        self.capacity = capacity
        self.tokens = capacity
        self.last = time.monotonic()
        self.lock = threading.Lock()

    def _refill(self):
        now = time.monotonic()
        delta = now - self.last
        self.tokens = min(self.capacity, self.tokens + delta * self.rate)
        self.last = now

    def try_acquire(self, n=1):
        with self.lock:
            self._refill()
            if self.tokens >= n:
                self.tokens -= n
                return True
            return False

class DualLimiter:
    def __init__(self, sec_rate, sec_burst, min_rate, min_burst):
        self.sec = TokenBucket(sec_rate, sec_burst)
        self.min = TokenBucket(min_rate, min_burst)

    def acquire(self, weight=1, timeout=2.0):
        deadline = time.monotonic() + timeout
        while time.monotonic() < deadline:
            if self.sec.try_acquire(weight) and self.min.try_acquire(weight):
                return True
            time.sleep(0.01)   # 轮询间隔，示例值
        return False

这段代码有两个值得注意的细节。第一，try_acquire 在锁内完成补充与扣减，保证多线程下计数一致；第二，双桶扣减存在“秒桶成功、分钟桶失败”的中间状态，示例中通过先秒后分并在失败时依赖下一次循环重新判断来简化处理，生产实现中更稳妥的方式是先预检两个桶的可用量，再统一扣减，避免令牌被单侧消耗。轮询间隔 10ms 是示例值，实际可根据请求密度调整，或改用条件变量唤醒以减少空转。

突发流量与重试的衔接

限流器解决的是“发得太快”，重试解决的是“发失败”。两者必须协同，否则重试会绕过限流直接冲击服务端。正确做法是：所有请求（包括重试）都必须经过限流器取令牌，重试前先等待退避时间，再进入限流队列。当收到 429 时，除了指数退避，还应考虑临时下调桶的补充速率或暂停取令牌一小段时间，形成对服务端信号的反馈。下图展示了请求从进入客户端到最终发出或失败的处理链路：

图中可以看到，重试并不是一条旁路，而是回到限流器重新排队。这一点在工程上非常关键：很多客户端在重试时直接发起新请求，结果限流器形同虚设，服务端看到的仍然是突发流量。把重试纳入限流链路后，退避时间与令牌等待叠加，整体请求节奏才真正可控。

结果观察与调优判断

限流器上线后，应重点观察三类指标：取令牌的平均等待时间、超时失败率、以及 429 响应占比。若平均等待时间持续偏高而 429 仍频繁出现，说明本地配额设置高于服务端实际配额，需要下调补充速率；若等待时间很短但 429 偶发，可能是突发容量过大导致瞬时超限，应适当减小桶容量。反之，若超时失败率偏高而 429 很少，说明限流过严，可适度提高速率或容量。这些判断都应基于一段时间的统计，而不是单次请求的表现。

最后需要强调，客户端限流器是保护措施而非性能优化手段。它会让部分请求变慢，但换来的是链路的稳定与可预期。把双桶扣减、惰性补充、带超时等待和重试回注这四件事做扎实，行情客户端就能在配额约束下平稳运行。