Guzzle HTTP 客户端全解析及 PHP 使用与优化

一、介绍

Guzzle 是 PHP 世界中最流行的 HTTP 客户端库之一，用于发送 HTTP/HTTPS 请求并处理响应。

它支持：

  • 同步和异步请求

  • HTTP/2

  • 中间件机制（类似 Laravel / Hyperf 的管道）

  • 并发请求

  • 请求重试、超时、连接池

Guzzle 常被用于调用第三方 API、微服务接口或爬取网页数据。

官方文档：https://docs.guzzlephp.org

二 、安装

composer require guzzlehttp/guzzle

三、基本使用

3.1 同步 GET 请求

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.example.com',
    'timeout'  => 5.0, // 超时时间
]);

$response = $client->get('/users/1');

echo $response->getStatusCode(); // 200
echo $response->getBody();       // JSON 或 HTML

3.2 POST 请求与 JSON 数据

$response = $client->post('/users', [
    'json' => [
        'name' => 'John',
        'email' => 'john@example.com',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

3.3 添加请求头

$response = $client->get('/users', [
    'headers' => [
        'Authorization' => 'Bearer ' . $token,
        'Accept'        => 'application/json',
    ],
]);

四、异步请求与并发

Guzzle 支持异步请求，通过 Promises 机制提高并发性能。

use GuzzleHttp\Promise;

$promises = [
    $client->getAsync('/users/1'),
    $client->getAsync('/users/2'),
    $client->getAsync('/users/3'),
];

$results = Promise\Utils::unwrap($promises);

foreach ($results as $response) {
    echo $response->getBody() . PHP_EOL;
}

异步请求适合批量调用接口或爬虫场景。

unwrap() 会等待所有请求完成。

五、Guzzle 中间件

Guzzle 的 HandlerStack 支持中间件，用于统一处理日志、重试、限流等。

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$stack = HandlerStack::create();
$logger = new Logger('guzzle');
$logger->pushHandler(new StreamHandler(__DIR__ . '/guzzle.log'));

$stack->push(Middleware::log($logger, new \GuzzleHttp\MessageFormatter('{uri} - {code}')));

$client = new Client(['handler' => $stack]);

六、Guzzle 使用优化

6.1 使用连接池

$client = new Client([
    'base_uri' => 'https://api.example.com',
    'connect_timeout' => 2,
    'timeout' => 5,
    'http_errors' => false, // 避免抛异常
]);

  • connect_timeout：建立 TCP 连接超时

  • timeout：整个请求超时

  • http_errors=false：避免 HTTP 错误抛异常，提高稳定性

6.2 重试机制

use GuzzleHttp\RetryMiddleware;

$retryMiddleware = Middleware::retry(function ($retries, $request, $response = null, $exception = null) {
    return $retries < 3 && ($exception || $response->getStatusCode() >= 500);
}, function ($retries) {
    return 1000 * $retries; // 毫秒延迟
});

$stack = HandlerStack::create();
$stack->push($retryMiddleware);

$client = new Client(['handler' => $stack]);

6.3 并发请求优化

  • 限制并发量：避免同时请求过多接口

  • 异步请求 + Promise Pool：

use GuzzleHttp\Promise\Utils;

$pool = Utils::each_limit($promises, 5); // 同时最多 5 个请求
$pool->wait();