README

这是PHP中令牌桶算法的线程安全实现。您可以使用令牌桶来限制资源的使用率（例如，流带宽或API使用）。

令牌桶是一个抽象的隐喻，它没有资源消耗的方向。也就是说，您可以限制消耗或生产的速率。例如，您可以限制第三方API服务的消耗速率，或者您也可以限制您自己的API服务的使用速率。

安装

使用Composer

composer require bandwidth-throttle/token-bucket

用法

该包位于命名空间bandwidthThrottle\tokenBucket。

示例

此示例将限制全局资源的速率，对所有请求而言，每秒10个请求。

use bandwidthThrottle\tokenBucket\Rate;
use bandwidthThrottle\tokenBucket\TokenBucket;
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);

if (!$bucket->consume(1, $seconds)) {
    http_response_code(429);
    header(sprintf("Retry-After: %d", floor($seconds)));
    exit();
}

echo "API response";

注意：在此示例中，TokenBucket::bootstrap()是代码的一部分。这不建议在生产环境中使用，因为这会产生不必要的存储通信。 TokenBucket::bootstrap()应作为应用程序的启动或部署过程的一部分。

存储范围

首先，您需要决定资源的范围。也就是说，您想按请求、按用户还是对所有请求进行限制？您可以通过选择所需范围的Storage实现来完成此操作

• RequestScope仅在一请求内限制速率。例如，限制下载带宽。每个请求都将有相同的带宽限制。

• SessionScope限制会话中资源的使用速率。速率控制在一个会话的所有请求上。例如，限制用户级别的API使用。

• GlobalScope限制所有进程（即请求）中资源的使用速率。例如，限制所有进程的下载带宽总和。此范围允许进程间的竞争条件。因此，令牌桶在共享互斥锁上进行了同步。

令牌桶

当您有了存储后，您可以最终实例化一个TokenBucket。第一个参数是桶的容量。也就是说，将不会有更多的令牌可用。这也意味着，消耗超过容量的令牌是无效的。

第二个参数是令牌添加Rate。它决定了填充桶的令牌的速度。速率是每单位添加的令牌数量，例如new Rate(100, Rate::SECOND)将每秒添加100个令牌。

第三个参数是存储，用于持久化桶的令牌数量。存储决定了桶的范围。

启动

需要初始化一个令牌桶。虽然方法 TokenBucket::bootstrap() 对已初始化的桶没有副作用，但并不建议在每次请求时都调用它。更好的做法是在应用程序的初始化或部署过程中将其包含在内。

消费

现在您已经初始化了令牌桶，可以开始消费令牌。方法 TokenBucket::consume() 将返回 true 如果令牌被消费，否则返回 false。如果令牌被消费，则应用程序可以继续提供服务。

否则，如果令牌没有被消费，则不应该提供服务。在这种情况下，consume() 方法会将其第二个参数（通过引用传递）写入秒数，这是直到足够令牌可用的时间。

BlockingConsumer

在第一个例子中，我们要么提供服务，要么以HTTP状态码429失败。这实际上是一种非常高效的API请求节流方式，因为它不会在您的服务器上预留资源。

然而，有时我们希望不失败，而是稍微等待一下然后继续提供服务。您可以通过使用 BlockingConsumer 来消费令牌桶来实现这一点。

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);
$consumer = new BlockingConsumer($bucket);
$bucket->bootstrap(10);

// This will block until one token is available.
$consumer->consume(1);

echo "API response";

这将有效地将速率限制为每秒10个请求。但在这种情况下，客户端不需要担心429错误。相反，连接将被延迟到期望的速率。

许可证和作者

本项目免费且受WTFPL许可。此项目的负责人是Markus Malkusch，邮箱为 [email protected]。

捐赠

如果您喜欢这个项目并且愿意慷慨捐赠，请在这里捐赠一些比特币：1335STSwu9hST4vcMRppEPgENMHD2r1REK