如何限制API请求速度，bandwidth-throttle/token-bucket助你构建健壮服务-composer-PHP中文网

如何限制API请求速度，bandwidth-throttle/token-bucket助你构建健壮服务

WBOY

发布： 2025-07-20 12:24:14

原创

657人浏览过

最近在开发一个处理用户提交数据的程序时，遇到了一个棘手的问题：用户输入的文本中包含各种非ASCII字符，例如中文、日文、特殊符号等等。这些字符导致程序在处理字符串时效率低下，甚至出现错误。为了解决这个问题，我尝试了多种方法，最终找到了voku/portable-ascii这个库。 Composer在线学习地址：学习地址

想象一下，你的API正在“裸奔”

在一个风和日丽的日子，你的新api上线了。起初一切顺利，但随着用户量的增长，一些“不速之客”开始频繁地调用你的接口。他们可能是爬虫，可能是恶意攻击者，也可能是无意中触发了高频请求的用户。

很快，服务器CPU飙升，内存告警，数据库连接池耗尽，你的服务开始变得缓慢，甚至直接崩溃。用户怨声载道，而你却手足无措。你尝试过简单的IP限制，但很快发现这治标不治本，因为IP可以轻易更换，而且会误伤正常用户。你意识到，你需要一个更智能、更灵活的限流机制。

手动实现一个健壮的限流系统绝非易事。你可能需要考虑：

并发问题： 多个请求同时到达时，如何保证限流逻辑的原子性？
状态存储： 限流状态（例如某个用户已发起了多少请求）需要持久化，是存文件、Redis还是数据库？
限流算法： 漏桶、令牌桶，哪种更适合我的场景？如何实现？
灵活性： 不同的接口需要不同的限流策略，如何配置和管理？

这些问题让开发者头疼不已，如果自己从零开始造轮子，不仅耗时耗力，还容易引入新的bug。

引入救星：`bandwidth-throttle/token-bucket`

正当我为此苦恼时，我发现了bandwidth-throttle/token-bucket这个Composer库。它是一个基于令牌桶（Token Bucket）算法的PHP实现，专门用于解决资源使用率限制的问题。无论是限制API调用频率、控制文件下载带宽，还是防止表单重复提交，它都能轻松应对。

什么是令牌桶算法？ 简单来说，你可以把令牌桶想象成一个固定容量的桶，里面不断地以恒定速率生成“令牌”。每次请求想要访问资源时，必须先从桶里取走一个令牌。如果桶里没有令牌了，请求就必须等待，直到有新的令牌生成，或者直接被拒绝。这样，即使短时间内有大量请求涌入，桶里令牌的数量也限制了实际处理的速率，从而保护了你的服务。

bandwidth-throttle/token-bucket库的亮点在于：

线程安全： 在多进程/高并发环境下也能稳定工作，避免了常见的竞态条件。
灵活的存储机制： 支持文件、会话、全局等多种存储方式，满足不同粒度的限流需求。
易于集成： 通过Composer安装，API设计直观，几行代码即可实现限流。

如何使用Composer和`bandwidth-throttle/token-bucket`实现API限流

首先，使用Composer安装这个库：

<code class="bash">composer require bandwidth-throttle/token-bucket</code>

登录后复制

安装完成后，你就可以在你的项目中引入并使用了。下面我们以一个常见的API限流场景为例：限制所有请求每秒最多10次。

<code class="php"><?php

require 'vendor/autoload.php'; // 引入Composer自动加载文件

use bandwidthThrottle\tokenBucket\Rate;
use bandwidthThrottle\tokenBucket\TokenBucket;
use bandwidthThrottle\tokenBucket\storage\FileStorage; // 使用文件存储，简单易用

// 1. 定义存储：这里我们使用文件存储，将令牌桶的状态保存在一个文件中。
// 注意：在生产环境中，更推荐使用RedisStorage或MemcachedStorage以获得更好的性能和并发支持。
$storage = new FileStorage(__DIR__ . "/api.bucket");

// 2. 定义速率：每秒生成10个令牌。
$rate = new Rate(10, Rate::SECOND);

// 3. 创建令牌桶实例：
// 第一个参数是桶的容量（burst capacity），这里设置为10，意味着桶里最多可以积攒10个令牌。
// 第二个参数是令牌的生成速率。
// 第三个参数是存储实例。
$bucket = new TokenBucket(10, $rate, $storage);

// 4. 初始化令牌桶：
// 这一步非常重要，它会初始化令牌桶的状态。
// 建议在应用启动时（例如框架的bootstrap文件或部署脚本中）执行一次，而不是每次请求都执行，
// 否则会增加不必要的存储通信开销。
// $bucket->bootstrap(10); // 首次运行时取消注释，之后可以注释掉

// 在实际的API处理逻辑前进行限流检查
if (!$bucket->consume(1, $seconds)) { // 尝试消耗1个令牌
    // 如果令牌不足，则返回429 Too Many Requests状态码，并告知客户端多久后可以重试。
    http_response_code(429);
    header(sprintf("Retry-After: %d", floor($seconds)));
    echo "Too Many Requests. Please try again in " . floor($seconds) . " seconds.";
    exit();
}

// 如果成功消耗了令牌，则继续处理API请求
echo "API response: Data fetched successfully!";

?></code>

登录后复制

代码解析：

百度GBI

百度GBI-你的大模型商业分析助手

104

查看详情

FileStorage(__DIR__ . "/api.bucket"): 创建一个文件存储实例。api.bucket是用于保存令牌桶状态的文件名。在生产环境中，你可能更倾向于使用RedisStorage或MemcachedStorage来支持更高效的并发访问和分布式部署。
Rate(10, Rate::SECOND): 定义了令牌的生成速率为每秒10个。你也可以设置为Rate::MINUTE、Rate::HOUR等。
TokenBucket(10, $rate, $storage): 创建一个令牌桶实例。10是桶的容量，意味着即使在短时间内，你最多也只能处理10个突发请求。
$bucket->bootstrap(10): 初始化令牌桶，并填充初始令牌数量（这里是10个）。请注意，这个方法应该在应用部署或启动时执行一次，而不是在每个请求中执行，以避免不必要的I/O操作。
$bucket->consume(1, $seconds): 尝试从桶中消耗1个令牌。
- 如果成功消耗，consume()返回true，你可以继续处理请求。
- 如果令牌不足，consume()返回false，并通过引用将需要等待的秒数赋值给$seconds变量。此时，你可以向客户端返回HTTP 429状态码，并附带Retry-After头，告知客户端何时可以重试。

阻塞式消费（BlockingConsumer）

在某些场景下，你可能不希望直接拒绝请求，而是让请求等待直到有令牌可用。bandwidth-throttle/token-bucket也提供了BlockingConsumer来实现这一功能：

<code class="php"><?php

require 'vendor/autoload.php';

use bandwidthThrottle\tokenBucket\Rate;
use bandwidthThrottle\tokenBucket\TokenBucket;
use bandwidthThrottle\tokenBucket\BlockingConsumer;
use bandwidthThrottle\tokenBucket\storage\FileStorage;

$storage  = new FileStorage(__DIR__ . "/api.bucket");
$rate     = new Rate(10, Rate::SECOND);
$bucket   = new TokenBucket(10, $rate, $storage);

// $bucket->bootstrap(10); // 同样，在应用启动时执行一次

$consumer = new BlockingConsumer($bucket);

echo "Attempting to consume token...\n";
// 这行代码会阻塞，直到有1个令牌可用。
// 如果桶中没有令牌，它会暂停脚本执行，直到令牌被补充。
$consumer->consume(1); 

echo "API response: Data fetched successfully after waiting (if needed)!";

?></code>

登录后复制

BlockingConsumer在令牌不足时会暂停脚本执行，直到令牌被补充。这对于需要保证所有请求最终都能被处理的场景非常有用，例如后台任务队列处理、消息消费等，但对于Web API来说，直接返回429通常是更好的选择，因为它不会长时间占用服务器资源。

不同范围的存储（Scope of the storage）

这个库最棒的特性之一是它对限流范围的灵活支持：

RequestScope： 仅在当前请求生命周期内限流。例如，限制一个文件下载过程中每秒的最大带宽。每个请求都有独立的限流。
SessionScope： 基于用户会话限流。例如，限制每个登录用户每分钟的API调用次数。
GlobalScope： 全局限流。所有进程/请求共享同一个令牌桶。这正是我们上面API限流示例所使用的场景，它通过文件锁或Redis/Memcached的原子操作保证了线程安全。

根据你的具体需求，选择合适的存储实现是构建高效限流系统的关键。