Guzzle可解决ThinkPHP 5.1中第三方接口调用的超时、连接复用与编码问题；需安装Guzzle、启用openssl/curl扩展、复用Client实例、正确处理GET/POST请求及错误捕获。
在 ThinkPHP 5.1 项目中调用外部支付网关、短信平台或第三方数据接口时，原生 curl 或 file_get_contents 常因超时不可控、连接复用缺失、编码处理粗糙导致请求失败或响应解析异常，Guzzle 能提供稳定连接池、精细超时控制与结构化响应处理能力。
安装 Guzzle 并验证环境依赖
进入 TP5.1 项目根目录，执行 Composer 安装命令：
composer require guzzlehttp/guzzle:^7.0
安装完成后，检查 vendor/guzzlehttp/ 目录是否生成完整文件结构；若报错提示 “Class 'GuzzleHttp\Client' not found”，说明自动加载未生效，需确认 vendor/autoload.php 是否被 index.php 正确引入。
【必须启用 openssl 和 curl 扩展】：打开 php.ini，取消注释 extension=openssl 和 extension=curl（Windows 下为 php_openssl.dll 和 php_curl.dll），重启 Web 服务或 CLI 环境后运行 php -m | grep -E 'openssl|curl' 验证生效。
在控制器中复用 Client 实例
避免每次请求都 new Client() —— 这会废弃连接池，造成 TCP 握手开销激增，高并发下易触发 TIME_WAIT 溢出。
方法一：在控制器方法内初始化并复用
use GuzzleHttp\Client;
public function apiCall()
{
$client = new Client([
'base_uri' => 'https://api.example.com/',
'timeout' => 8,
'connect_timeout' => 3,
'headers' => ['User-Agent' => 'TP5.1-Guzzle/7.x']
]);
// 后续所有 $client->get() / ->post() 都复用此实例
}
方法二：绑定到容器实现全局单例（推荐）
在 app/common.php 中追加：
Container::get('think\App')->bind('guzzle', function () {
return new Client(['timeout' => 8, 'connect_timeout' => 3]);
});
控制器中通过 $this->app->make('guzzle') 获取实例。
发送 GET 请求并安全解析响应
第一步：调用 get() 方法发起请求
$response = $client->get('/v1/user?uid=123');
第二步：校验 HTTP 状态码
if ($response->getStatusCode() !== 200) {
throw new Exception("API 返回 {$response->getStatusCode()}");
}
第三步：提取并转码响应体
$body = (string) $response->getBody();
若目标接口返回 GBK 编码（如某些老银行系统），直接 json_decode($body) 会失败，必须先转码：
$body = mb_convert_encoding($body, 'UTF-8', 'GBK');
第四步：解析 JSON 数据
$data = json_decode($body, true);
注意：$data 可能为 null，需用 is_array($data) 或 json_last_error() 进一步判断解析是否成功。
POST 表单与 JSON 提交的严格区分
表单提交（Content-Type: application/x-www-form-urlencoded）用 form_params：
$client->post('/login', [
'form_params' => [
'username' => 'admin',
'password' => '123456'
]
]);
JSON 提交（Content-Type: application/json）用 json：
$client->post('/order', [
'json' => [
'item_id' => 'P1001',
'amount' => 99.9
]
]);
【form_params 和 json 不可混用】：若误将数组塞进 form_params 而期望服务端收到 JSON，实际发送的是 URL 编码字符串，服务端 body 解析必然为空。
捕获并区分网络层与业务层错误
try {
$response = $client->get('/status');
} catch (\GuzzleHttp\Exception\RequestException $e) {
if ($e->hasResponse()) {
// 业务错误：HTTP 状态码非 2xx，但已收到响应
$code = $e->getResponse()->getStatusCode();
$body = (string) $e->getResponse()->getBody();
// 如 401 表示 token 过期，400 表示参数错误
} else {
// 网络错误：DNS 失败、连接超时、SSL 验证失败等
$request = $e->getRequest();
// 可记录 $request->getUri() 和 $e->getMessage() 用于排查
}
}
