Laravel 官方推荐直接使用 GuzzleHttp\Client，无需额外封装；Laravel 9+ 默认含 Guzzle v7.x，低版本需手动安装并注意 PHP 版本兼容性；发起请求时应复用 Client 实例、显式读取响应体、校验状态码并合理捕获异常。

直接用 GuzzleHttp\Client 发起请求即可，Laravel 本身不内置 HTTP 客户端，但官方推荐并兼容 Guzzle —— 不需要额外封装类，也不必改配置就能用。

安装 Guzzle 并确认版本兼容性

Laravel 9+ 默认已包含 guzzlehttp/guzzle（v7.x），但如果你用的是 Laravel 8 或更早版本，或执行过 composer remove guzzlehttp/guzzle，需手动安装：

composer require guzzlehttp/guzzle:^7.5

注意：Guzzle v8 不完全兼容 PHP 7.4，若项目还跑在 PHP 7.4 上，务必锁死 v7.5–v7.9；Laravel 10 支持 Guzzle v8，但需 PHP 8.1+。检查当前版本：

composer show guzzlehttp/guzzle

常见错误现象：Class 'GuzzleHttp\Client' not found，基本就是没装、装错版本，或 autoloader 没刷新（可试 composer dump-autoload）。

在控制器中发起 GET 请求并解析 JSON 响应

最常用场景：调用第三方 API 获取数据，比如天气接口。直接 new Client，用 get() 方法，响应体默认是 GuzzleHttp\Psr7\Response 对象，需显式调用 getBody()->getContents() 或 json_decode() 解析：

$client = new \GuzzleHttp\Client();
try {
    $response = $client->get('https://api.example.com/data', [
        'headers' => ['Authorization' => 'Bearer abc123'],
        'timeout' => 5,
    ]);
    
    $body = $response->getBody()->getContents();
    $data = json_decode($body, true);
    
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new \Exception('Invalid JSON response');
    }
} catch (\GuzzleHttp\Exception\RequestException $e) {
    // 网络失败、超时、DNS 错误等
    \Log::error('HTTP request failed: ' . $e->getMessage());
    $data = null;
} catch (\Exception $e) {
    // JSON 解析失败等
    \Log::error('Response parse failed: ' . $e->getMessage());
    $data = null;
}

关键点：

• getContents() 是必须的，getBody() 返回 StreamInterface，不读取就拿不到字符串
• json_decode(..., true) 第二个参数设为 true 才返回数组，否则是 stdClass 对象，Laravel 集合操作会出问题
• 不要依赖 $response->json() —— 这是 Laravel 的 Illuminate\Http\Client\Response 方法，不是 Guzzle 原生方法

POST 提交 JSON 数据并处理状态码与错误响应

调用登录、支付等接口时，常需 POST JSON 并校验 200 或 201 状态码。Guzzle 默认不会因非 2xx 状态码抛异常，得手动判断：

$client = new \GuzzleHttp\Client();
try {
    $response = $client->post('https://api.example.com/login', [
        'json' => ['email' => 'user@example.com', 'password' => 'secret'],
        'timeout' => 8,
    ]);

    // 显式检查状态码
    if ($response->getStatusCode() >= 400) {
        throw new \Exception("API error: {$response->getStatusCode()}");
    }

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

} catch (\GuzzleHttp\Exception\ConnectException $e) {
    // DNS 失败、连接被拒、网络不通
    \Log::error('Connection failed: ' . $e->getMessage());
} catch (\GuzzleHttp\Exception\RequestException $e) {
    // HTTP 层错误（如 404、500、超时），但不包括连接失败
    \Log::error('Request failed: ' . $e->getMessage());
} catch (\Exception $e) {
    \Log::error('Unexpected error: ' . $e->getMessage());
}

注意：

• 'json' 选项会自动设置 Content-Type: application/json 并序列化数组，比手写 'body' => json_encode(...) 更安全
• getStatusCode() 必须在 try 块里调用，否则异常时无法访问 $response
• 别把 4xx/5xx 全部丢给 RequestException 捕获 —— Guzzle 只对网络层异常抛 RequestException，业务级错误码（如 401）仍会进 if 判断分支

避免内存泄漏与连接复用问题

高频调用外部接口时，反复 new Client 会导致 TCP 连接无法复用、FD 耗尽、内存缓慢增长。正确做法是复用同一个 Client 实例：

在 App\Services\ApiClient.php 中定义单例：

namespace App\Services;

use GuzzleHttp\Client;

class ApiClient
{
    private static ?Client $instance = null;

    public static function getInstance(): Client
    {
        if (self::$instance === null) {
            self::$instance = new Client([
                'timeout' => 10,
                'connect_timeout' => 5,
                'http_errors' => false, // 不因 4xx/5xx 自动抛异常
                'headers' => ['User-Agent' => 'Laravel-App/1.0'],
            ]);
        }
        return self::$instance;
    }
}

然后在控制器里用 ApiClient::getInstance()，而不是每次 new。另外，http_errors => false 是关键开关：它让 Guzzle 把 4xx/5xx 当作正常响应返回，便于统一处理业务逻辑，而不是混在异常堆栈里。

真正容易被忽略的是：Guzzle 的默认连接池大小是 10，如果并发请求远超这个数（比如队列中同时跑 50 个 API 调用），会排队等待空闲连接 —— 此时应调大 pool_size 或改用异步请求（sendAsync()），但那属于另一层复杂度了。