yii2 本身无内置 http 客户端，但可通过 yii\httpclient\client 扩展实现标准请求；其基于 guzzle 或 curl，支持超时控制（connectiontimeout/timeout）、手动重试封装、事件监听等，需注意配置隔离、重定向、jwt 刷新等常见陷阱。
Yii2 本身没有内置的 HTTP 客户端（如 Guzzle 或 Symfony HttpClient 那样的独立组件），但可通过 yii\httpclient\Client 扩展实现标准、可配置的 HTTP 请求。该扩展基于 Guzzle（默认）或 cURL，支持超时控制、重试策略、中间件拦截等能力。关键在于正确配置 Client 实例，并结合事件或自定义行为实现健壮的容错逻辑。
设置请求超时参数
超时需区分连接超时（connection timeout）和读取超时（read timeout），两者不可混用：
- connectionTimeout：建立 TCP 连接的最大等待时间（单位：秒），默认 30。设为 0 表示无限等待（不推荐）
- timeout：从连接建立后，等待响应数据返回的总时间（含响应头+响应体），默认 30
- 若使用 Guzzle 作为底层驱动，还可通过
transportOptions指定更细粒度选项，例如['curl' => [CURLOPT_CONNECTTIMEOUT_MS => 2000]]
示例配置：
```php$client = new \yii\httpclient\Client([
'transport' => 'yii\httpclient\CurlTransport',
'connectionTimeout' => 5,
'timeout' => 10,
]);
启用自动重试机制
Yii2 的 Client 原生不提供声明式重试（如 retry(3)），但可通过 request() 的 options 参数传入 Guzzle 兼容的重试配置（仅当使用 Guzzle transport 时生效）：
- Guzzle 7+ 支持
http_errors => false+ 自定义retry中间件，但 Yii2 封装层未暴露该能力 - 推荐做法：在调用
send()前手动封装重试逻辑，利用try/catch捕获\yii\httpclient\Exception和网络类异常（如RequestException） - 对幂等请求（GET/HEAD/PUT），可安全重试；非幂等操作（POST/DELETE）需评估业务语义是否允许重复提交
简易重试封装示例：
```phpfunction sendWithRetry($client, $request, $maxRetries = 3) {
$attempt = 0;
do {
try {
$response = $request->send();
if ($response->isOk) {
return $response;
}
} catch (\yii\httpclient\Exception $e) {
// 网络失败、连接拒绝、超时等
}
$attempt++;
if ($attempt usleep(500000); // 500ms 指数退避可自行增强
}
} while ($attempt throw new \RuntimeException("Request failed after $maxRetries attempts");
}
```
结合事件监听做失败兜底
Yii2 Client 支持事件机制，可在请求失败时统一处理日志、告警或降级：
- 监听
Client::EVENT_BEFORE_SEND可动态修改请求头、添加 trace ID - 监听
Client::EVENT_AFTER_SEND可检查响应状态码，对 5xx 或超时响应触发重试或熔断 - 建议配合
yii\log\Logger记录失败详情，包括 URL、方法、耗时、错误类型
示例：
```php$client->on(\yii\httpclient\Client::EVENT_AFTER_SEND, function ($event) {
$response = $event->response;
if (!$response || !$response->isOk) {
\Yii::error([
'url' => $event->request->getUrl(),
'status' => $response ? $response->getStatusCode() : 'no response',
'error' => $event->error ?? 'unknown'
], 'http-client-fail');
}
});
避免常见陷阱
实际开发中容易忽略的细节：
- 不要在
Client配置中设置过长的timeout（如 60s），会拖慢整个 Web 请求生命周期；应按接口 SLA 设置合理值（如第三方 API 通常要求 ≤5s） - 禁用
followLocation（重定向）除非明确需要，否则可能绕过你设置的超时和重试逻辑 - 若使用
CurlTransport，注意curl_setopt的全局影响；多个 Client 实例共享 curl handler 时需确保隔离 - JWT 接口调用务必携带
Authorization: Bearer xxx，且 token 过期时重试无意义，应先刷新 token 再重试
