如何为Guzzle 6客户端实现多主机故障切换的自定义Handler？

要实现内置故障切换逻辑的Guzzle 6客户端，核心是通过自定义Handler中间件拦截请求生命周期，在请求失败时自动切换到下一个主机重试。下面是完整的落地方案：

核心实现思路 #

我们会编写一个自定义中间件，把主机列表绑定到Client实例中，每次请求触发故障（连接失败、超时、服务端错误）时，按顺序尝试下一个主机，直到请求成功或所有主机尝试完毕。

1. 编写故障切换中间件 #

这个中间件负责维护主机列表的轮询状态，拦截失败请求并替换主机重试：

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use GuzzleHttp\Exception\RequestException;
use Psr\Http\Message\RequestInterface;

function createFailoverMiddleware(array $hosts) {
    $currentHostIndex = 0;
    $totalHosts = count($hosts);

    // 重试判定逻辑
    return Middleware::retry(function ($retries, RequestInterface $request, $response = null, $exception = null) use (&$currentHostIndex, $totalHosts) {
        // 判断是否需要重试：连接异常、超时、5xx服务端错误
        $needsRetry = false;
        if ($exception instanceof RequestException) {
            $needsRetry = true;
        } elseif ($response && $response->getStatusCode() >= 500) {
            $needsRetry = true;
        }

        // 重试次数不超过主机数量-1（保证每个主机只试一次）
        return $needsRetry && $retries < $totalHosts - 1;
    }, function ($retries) use (&$currentHostIndex, $hosts) {
        // 切换到下一个主机，更新请求的URI
        $currentHostIndex = ($currentHostIndex + 1) % $totalHosts;
        return function (RequestInterface $request) use ($hosts, $currentHostIndex) {
            $newUri = $request->getUri()->withHost($hosts[$currentHostIndex]);
            return $request->withUri($newUri);
        };
    });
}

2. 创建带故障切换的Client实例 #

把自定义中间件加入Handler栈，同时将初始主机设为列表第一个：

use GuzzleHttp\Client;

// 你的主机列表
$hosts = ['host1.example.com', 'host2.example.com', 'host3.example.com'];

// 构建Handler栈并添加故障切换中间件
$handlerStack = HandlerStack::create();
$handlerStack->push(createFailoverMiddleware($hosts));

// 初始化Client，内置故障切换逻辑
$client = new Client([
    'base_uri' => 'https://' . $hosts[0],
    'handler' => $handlerStack,
    // 设置超时，避免请求长时间阻塞
    'timeout' => 5,
    'connect_timeout' => 2
]);

3. 日常使用方式 #

和普通Guzzle Client完全一致，故障切换逻辑会自动触发：

try {
    $response = $client->get('/api/data');
    echo $response->getBody();
} catch (RequestException $e) {
    // 所有主机尝试失败时的兜底处理
    echo "所有主机均不可用: " . $e->getMessage();
}

可调整的细节 #

• 故障判定规则：可以根据业务需求修改重试触发条件，比如加入特定4xx状态码的重试逻辑。
• 主机轮询策略：当前是循环轮询（最后一个主机失败后回到第一个），也可以改成“用完即止”的策略（去掉取模操作，直接递增到列表末尾）。
• 重试间隔：如果需要添加重试等待时间，可以在重试回调中加入usleep()或类似逻辑。

内容的提问来源于stack exchange，提问作者marcv