1 基本概念
1.1 定义
令牌桶是一种用于流量控制和速率限制的算法。其基本做法是以固定或近似固定的速率向一个逻辑“桶”中放入令牌，而请求在通过系统前需要先获取令牌；获取成功则允许继续执行，获取失败则说明当前可用额度不足，需要被限制、延后或丢弃。
这种机制既可以用于约束单位时间内的平均通过量，也能够在桶内有充足余量时放行一段短时高峰，因此常被视为兼顾平稳控制与突发承载能力的通用方案。
1.2 核心思想
令牌桶的核心思想是“先积累、后消耗”。系统在空闲或负载较低时持续积攒令牌，当请求集中到来时，已经预存的令牌可以被快速消耗，从而允许一定程度的瞬时放量。
与直接按时间窗口统计请求数的方式不同，令牌桶更强调资源额度的连续积累与使用，因而在面对不均匀流量时通常更具弹性。它并不要求每一秒都严格等量放行，而是通过总量约束来维持长期平均速率。
1.3 适用场景
令牌桶适用于需要控制访问频率、限制带宽占用、保护后端资源或平衡系统负载的场合。它尤其适合存在明显峰谷变化的业务，因为算法允许把平时积累的额度用于应对短时集中请求。
1.3.1 接口限流
在接口限流中，令牌桶常用于限制单位时间内的调用次数，防止某个客户端、某个接口或某类任务过度占用服务能力。对于高峰时段偶发的正常请求集中情况，它也能保持一定容忍度，避免过于生硬地拒绝全部流量。
1.3.2 网络带宽控制
在网络传输中，令牌桶可以用来约束发送速率。例如，系统可按设定速率发放表示字节数或包数的令牌，发送数据时按实际长度扣减对应额度，以此控制带宽占用并减少拥塞风险。
1.3.3 资源访问节流
对于数据库、缓存、文件系统或其他共享资源，令牌桶可用于限制访问频率，避免瞬时并发把后端推入高延迟或过载状态。它常作为保护性机制，与重试、排队和熔断等手段配合使用。
2 工作机制
2.1 令牌生成
令牌生成通常由时间驱动。系统按照预设速率定期或按需计算新增令牌数量，并将其加入桶中。若桶已满，则多余令牌一般不再继续累积，以免突破容量上限。
这种生成方式使令牌的积累与时间直接对应，便于将“允许通过的平均速度”映射为一个可配置的参数。
2.2 令牌存储
桶是令牌的逻辑存储结构，可以理解为一个具有容量限制的缓存。其作用不是保存业务数据，而是记录当前可用额度。
实现上，桶中的状态通常只需记录当前令牌数以及最后一次更新的时间点。对于分布式系统，还可能需要借助外部存储来统一维护这一状态。
2.3 令牌消耗
请求到达时，系统会先判断是否拥有足够数量的令牌。若请求的消耗量小于或等于当前余额，则扣减相应令牌并继续处理；若不足，则进入受限状态。
消耗粒度可以按“一个请求一个令牌”计算，也可以按请求大小、执行成本或优先级折算为不同的令牌数量，从而更灵活地表达资源占用。
2.4 请求处理策略
当令牌不足时，系统并不只有一种处理方式。具体动作通常由业务目标决定，可以是立即拒绝、等待补充后再执行，或者进入排队流程。
2.4.1 直接放行
在某些场景中，若令牌充足则直接执行请求，处理路径最为简洁。此方式适合实时性要求较高、逻辑清晰的限流点，例如入口网关或轻量接口。
2.4.2 拒绝请求
当桶中没有足够令牌时，请求可以被直接拒绝，并返回明确的失败信息。这种策略有利于快速止损，减少系统继续消耗资源，也便于上游尽快感知限流状态。
2.4.3 延迟执行
另一种做法是暂不丢弃请求，而是等待下一批令牌生成后再处理。此方式适合允许短暂等待的任务，但需要额外考虑队列长度、超时和堆积风险。
3 关键参数
3.1 令牌生成速率
令牌生成速率决定系统的长期平均放行能力。速率过高会削弱限流效果，过低则可能压制正常业务。它通常是整个算法中最重要的配置项之一。
3.2 桶容量
桶容量表示可积累的最大令牌数，直接影响系统可承受的突发强度。容量越大，短时间内可放行的请求越多；但若设置过大，也可能导致峰值放量过猛。
3.3 初始令牌数
初始令牌数决定系统启动时的可用额度。若初始值较高，服务刚上线时便能立即承接一定流量；若设置为零，则需要等待令牌逐步积累后才能放行请求。
3.4 请求消耗粒度
请求消耗粒度用于描述每次请求应扣减多少令牌。简单场景下可以固定为 1；复杂场景中则可按请求大小、耗时预估或资源权重动态计算，以更准确地反映真实负载。
4 算法特性
4.1 限制平均速率
令牌桶能够在长期维度上约束请求通过的平均速率。只要令牌补充速率保持稳定，系统整体的处理量就会被控制在可预期范围内。
4.2 支持突发流量
由于令牌可以提前积累，算法天然支持短时突发。只要桶内有余额，瞬间涌来的请求便可被快速处理，这使其在峰值波动明显的业务中表现较好。
4.3 公平性与稳定性
令牌桶在一定程度上有助于维持系统稳定，避免流量剧烈冲击后端。不过，公平性表现会受到调度方式、请求排队策略以及多客户端竞争情况的影响，并非自动保证绝对均衡。
4.4 与业务峰值的匹配
该算法适合与业务节律相匹配的场景，例如周期性活动、批量提交或工作日高峰。通过合理设置容量与速率，可以让系统在正常高峰期间保持可用，同时避免长时间超载。
5 与其他算法的比较
5.1 与漏桶算法比较
漏桶算法更强调输出平滑，通常会把进入系统的流量以相对恒定的节奏“漏出”。相比之下，令牌桶更宽容突发流量，允许在令牌积累充足时短时间内集中通过请求，因此更适合峰值波动较大的业务。
5.2 与固定窗口限流比较
固定窗口限流按预设时间片统计请求数，配置简单，但窗口边界附近可能出现短时间内的放量重叠。令牌桶则通过连续补充与动态消耗来判断额度，通常能减少这种边界效应。
5.3 与滑动窗口限流比较
滑动窗口限流会更精细地统计一段连续时间内的请求情况，控制效果较平滑，但实现和计算成本通常更高。令牌桶的优势在于逻辑直观、成本较低，同时仍能兼顾一定突发承载。
5.4 与计数器限流比较
计数器限流往往以简单计数方式判断是否超限，适合实现轻量化策略，但表达能力有限。令牌桶则能够把“平均速率”和“瞬时余量”同时纳入控制，更适合需要弹性调度的场景。
6 实现方式
6.1 单机实现
单机环境下，令牌桶通常可通过内存变量直接维护，配合当前时间戳计算令牌补充量。实现结构较简单，性能也较好，适合单实例服务或局部限流。
6.1.1 基于时间戳的计算
这种方式不会真正为每个时间片都创建补充任务，而是在请求到来时根据“当前时间减去上次更新时间”计算应新增的令牌数。该方法节省资源，且便于在请求驱动下完成懒更新。
6.1.2 基于定时器的补充
另一种实现是在后台使用定时器周期性填充令牌。它便于理解和观测，但需要处理定时精度、线程调度和空闲时的额外开销，适合节奏较稳定的系统。
6.2 分布式实现
分布式场景中，多台实例可能同时访问同一限流规则，因此需要统一管理令牌状态。常见做法是借助共享存储或协调组件，以保证各节点对额度的判断一致。
6.2.1 共享令牌存储
共享存储通常用于保存当前令牌数、最后更新时间和相关配置。这样，不同服务实例在消费令牌时读取的是同一份状态，从而避免各自独立计数导致的超发。
6.2.2 原子性控制
为了防止并发请求同时扣减导致重复使用令牌，更新操作需要具备原子性。常见方案包括乐观锁、原子脚本或事务机制，以确保“检查余额”和“扣减额度”之间不会被打断。
6.2.3 一致性与并发处理
分布式限流往往还要兼顾一致性和性能。若一致性要求较高，系统可能牺牲部分吞吐；若更偏向高性能，则可能接受轻微误差。具体选择通常取决于业务对超限容忍度的高低。
7 应用实践
7.1 API 网关限流
在 API 网关中，令牌桶常用于统一控制入口流量，按用户、应用、接口或来源维度设置配额。这样可在请求进入内部系统之前先完成过滤，减轻后端压力。
7.2 微服务保护
在微服务体系内，某个下游服务出现延迟升高时，可通过令牌桶限制上游调用频率，避免级联拥塞。它常与超时、重试退避和熔断配合使用，以提升整体韧性。
7.3 数据库访问控制
数据库查询、写入或批处理任务都可能因并发过高而产生性能抖动。通过令牌桶限制访问节奏，可以减少瞬时竞争，帮助系统维持更平稳的响应时间。
7.4 消息队列消费限速
当消费者处理能力有限时，令牌桶可以用于控制消费速率，避免拉取过快造成堆积扩散或本地资源耗尽。它也适合在不同优先级队列之间分配处理节奏。
7.5 爬虫与抓取节流
在网页抓取或数据采集任务中，令牌桶常被用来限制访问频率，使请求更符合预定节奏。这样既有助于降低目标站点压力，也能让自身任务运行更加稳定。
8 优缺点分析
8.1 优点
令牌桶之所以广泛使用，主要在于它兼顾了实现成本、控制效果和配置灵活性。对于多数工程系统而言，这种平衡非常实用。
8.1.1 实现简单
该算法的核心逻辑清晰，只需维护令牌数量和补充规则即可。相比一些需要复杂时间窗统计的方法，工程落地门槛更低。
8.1.2 支持突发
令牌桶能自然容纳短时高峰，不会像过于严格的匀速控制那样把所有峰值都压平。这使其更适合真实业务中常见的不规则流量。
8.1.3 易于调参
令牌生成速率和桶容量是两个主要参数，通常可直接对应业务目标进行配置。对于需要快速试错和持续优化的系统，这一点尤其便利。
8.2 缺点
尽管实用，令牌桶也并非没有局限。若参数或实现不当，仍可能引发短时过载或控制失真。
8.2.1 短时放量风险
由于允许积累令牌，系统在突发时可能一次性放行较多请求。如果后端承载能力不足，这种放量反而会带来瞬时压力。
8.2.2 参数设置敏感
速率、容量和初始值如果设置不合理，轻则影响用户体验，重则导致系统过松或过严。因此，参数往往需要结合真实流量反复验证。
8.2.3 分布式实现复杂
在多实例环境中，要同时保证一致性、原子性和高并发性能并不容易。实现复杂度提升后，维护成本和故障排查难度也会随之增加。
9 设计与调优
9.1 业务需求建模
设计令牌桶之前，通常需要先明确业务侧的目标：是限制平均请求量，还是保护后端资源，或是给突发流量留出缓冲空间。不同目标对应不同的速率与容量配置思路。
9.2 参数选择原则
参数选择一般应从实际能力出发，先估算系统可承受的稳态吞吐，再根据可接受的峰值幅度设置桶容量。若业务存在固定节奏，可让补充速率与常态负载相匹配。
9.3 高并发场景优化
在高并发环境中，应尽量减少锁竞争和重复计算，并优先采用轻量化的原子更新方式。对热点资源还可结合分片、分级限流或本地缓存，降低单点压力。
9.4 监控与告警指标
常见监控指标包括当前令牌余额、限流次数、请求通过率、排队时长和拒绝比例等。通过这些数据可以判断限流是否过紧或过松，并及时调整配置。
10 相关扩展
10.1 漏桶变体
漏桶变体是在基础思想上进行调整的限流方案，往往更强调输出节奏的均匀性。它可作为令牌桶的对照模型，也可在特定场景中替代使用。
10.2 多级令牌桶
多级令牌桶通常用于分层控制流量，例如先按全局总量限制，再按用户、租户或接口细分额度。这样的结构能更细致地表达不同层次的资源约束。
10.3 动态令牌桶
动态令牌桶会根据实时负载、时间段或系统健康状况调整补充速率和容量。与固定参数方案相比，它更灵活，但也更依赖准确的状态感知。
10.4 基于权重的令牌分配
在基于权重的方案中，不同请求会按优先级或成本消耗不同数量的令牌。这样可以让高价值或低成本任务获得更多通过机会，从而实现更精细的资源分配。