README

使用可自定义的重试策略重试失败的HTTP请求。

以下是一个简单的使用示例

use GuzzleHttp\Subscriber\Retry\RetrySubscriber;

// Retry 500 and 503 responses
$retry = new RetrySubscriber([
    'filter' => RetrySubscriber::createStatusFilter()
]);

$client = new GuzzleHttp\Client();
$client->getEmitter()->attach($retry);

安装

将以下内容添加到您的 composer.json 文件中

{
    "require": {
        "guzzlehttp/retry-subscriber": "~2.0"
    }
}

创建一个 RetrySubscriber

RetrySubscriber 的构造函数接受一个配置选项的关联数组

filter

(callable)（必需）用于确定是否重试请求的过滤器。该过滤器必须是一个可调用函数，它接受当前重试次数作为第一个参数和一个 GuzzleHttp\Event\AbstractTransferEvent 对象作为第二个参数。过滤器必须返回 true 或 false 来表示请求是否需要重试。

delay

一个可调用函数，它接受重试次数作为第一个参数和一个 GuzzleHttp\Event\AbstractTransferEvent 作为第二个参数。该可调用函数必须返回延迟的时间（以毫秒为单位）。

如果没有提供 delay 配置值，则使用默认的指数退避实现。

max

一个整数，表示在放弃之前允许的最大重试次数。

如果没有提供 max 配置值，则请求将重试5次。

确定应该重试什么

RetrySubscriber 构造函数的必需 filter 选项是一个可调用函数，用于确定请求是否应该重试。

当调用过滤器时，它提供了请求的当前重试次数和 GuzzleHttp\Event\CompleteEvent 或 GuzzleHttp\Event\ErrorEvent（这两个事件都扩展了 GuzzleHttp\Event\AbstractTransferEvent，因此你应该对它进行类型提示）。然后，过滤器必须返回 true 表示请求应该重试，或者返回 false 表示不应该重试。

以下是一个示例，演示了如何重试发送到 /foo 端点的失败 500 响应

use GuzzleHttp\Event\AbstractTransferEvent;
use GuzzleHttp\Subscriber\Retry\RetrySubscriber;

$retry = new RetrySubscriber([
    'filter' => function ($retries, AbstractTransferEvent $event) {
        $resource = $event->getRequest()->getResource();
        // A response is not always received (e.g., for timeouts)
        $code = $event->getResponse()
            ? $event->getResponse()->getStatusCode()
            : null;

        return $resource == '/foo' && $code == 500;
    }
]);

$client = new GuzzleHttp\Client();
$client->getEmitter()->attach($retry);

过滤器链

您可以使用过滤器链创建更多可自定义的重试逻辑，该链通过静态 RetrySubscriber::createChainFilter() 方法创建。此方法接受一个可调用过滤器数组，每个过滤器按顺序调用。链中的过滤器应返回以下值之一，这会影响链的其余部分如何执行。

• RetrySubscriber::RETRY（即 true）- 重试请求。
• RetrySubscriber::DEFER（即 false）- 转到链中的下一个过滤器。
• RetrySubscriber::BREAK_CHAIN（即 -1）- 停止过滤器链，并且不重试请求。

以下是一个示例，演示了如何使用过滤器链重试仅针对幂等或“安全”请求的失败 500 和 503 响应，如RFC 7231 中定义。

use GuzzleHttp\Event\AbstractTransferEvent;
use GuzzleHttp\Subscriber\Retry\RetrySubscriber;

// Retry 500 and 503 responses that were sent as GET and HEAD requests.
$filter = RetrySubscriber::createChainFilter([
    // Does early filter to force non-idempotent methods to NOT be retried.
    RetrySubscriber::createIdempotentFilter(),
    // Performs the last check, returning ``true`` or ``false`` based on
    // if the response received a 500 or 503 status code.
    RetrySubscriber::createStatusFilter([500, 503])
]);

$retry = new RetrySubscriber(['filter' => $filter]);
$client = new GuzzleHttp\Client();
$client->getEmitter()->attach($retry);

自定义延迟时间

delay 是 RetrySubscriber 构造函数中的一个可选配置选项，它是一个用于确定在重试标记为需要重试的请求之前延迟时间的可调用函数。该可调用函数接受当前重试次数以及一个 GuzzleHttp\Event\CompleteEvent 或一个 GuzzleHttp\Event\ErrorEvent。然后该函数必须返回一个整数或浮点数，表示休眠的毫秒数。

注意

省略此参数将使用默认的指数退避策略。

以下是一个创建自定义延迟的示例，总是延迟 1 毫秒

use GuzzleHttp\Subscriber\Retry\RetrySubscriber;

$retry = new RetrySubscriber([
    'filter' => RetrySubscriber::createStatusFilter(),
    'delay'  => function ($number, $event) { return 1; }
]);

更改最大重试次数

您还可以在 RetrySubscriber 构造函数的 max 配置选项中指定一个可选的最大重试次数。如果没有指定，请求可以重试最多 5 次后才会允许失败。

use GuzzleHttp\Subscriber\Retry\RetrySubscriber;

$retry = new RetrySubscriber([
    'filter' => RetrySubscriber::createStatusFilter(),
    'max'    => 3
]);