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()），但那属于另一层复杂度了。
