必须显式设置timeout和connect_timeout，且值须为float（如10.0而非10），否则CakePHP静默忽略；timeout控制DNS+连接+传输全程，connect_timeout仅限TCP建立阶段，二者缺一不可。
HTTP 客户端超时设置必须显式指定 timeout 和 connect_timeout
CakePHP 的 Http\Adapter\CurlAdapter（或 4.4+ 默认的 Http\Adapter\StreamAdapter）不会自动设超时，不配置就可能卡死几十秒甚至更久。默认行为是无限等待响应体，不是“等几秒没回就报错”。
实操建议：
-
timeout控制整个请求（DNS + 连接 + 发送 + 接收）的总耗时，单位秒，推荐设为10.0或更低，视接口 SLA 调整 -
connect_timeout单独控制 TCP 连接建立阶段，应明显小于timeout（如3.0），避免 DNS 慢或目标宕机时干等 - 两者都得设，只设一个没用；值必须是 float（
10不行，得写10.0），否则 CakePHP 会静默忽略
示例配置：
$client = new Client([
'timeout' => 10.0,
'connect_timeout' => 3.0,
]);重试逻辑不能依赖内置 retry 配置，得手写循环 + 异常捕获
CakePHP 4.x 的 Client 虽有 retry 选项，但它只重试极少数底层网络错误（如 curl error 7），对 HTTP 状态码（如 502、504）、JSON 解析失败、空响应等完全不触发重试。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
- 用
try/catch包裹$client->get()或->post()，捕获NetworkException（连接/超时）、BadResponseException（非 2xx）、JsonException（解析失败） - 按需判断重试条件：比如只对
502、503、504和NetworkException重试，跳过400、401等客户端错误 - 加指数退避（如
sleep(1 * $attempt)），避免雪崩；最多重试 2–3 次，再失败就该让上游处理了
简短示例：
$attempts = 0;
$maxRetries = 2;
do {
try {
$response = $client->get('https://api.example.com/data');
if ($response->getStatusCode() >= 500 && $response->getStatusCode() < 600) {
throw new BadResponseException('Server error', $response);
}
return $response->getJson();
} catch (NetworkException | BadResponseException $e) {
$attempts++;
if ($attempts > $maxRetries) {
throw $e;
}
usleep(1000000 * $attempts); // 1s, 2s
}
} while ($attempts <= $maxRetries);
BadResponseException 的 getResponse() 返回的是原始响应对象，不是数组
很多人以为 $e->getResponse()->getJson() 总能拿到数据，但实际如果响应体不是合法 JSON、或为空、或 Content-Type 不是 application/json，getJson() 会直接抛 JsonException —— 这个异常不会被外层 BadResponseException 的 catch 捕获，导致重试逻辑中断。
实操建议：
- 不要在
catch块里直接调getJson()，先用getBody()->getContents()拿原始字符串，再用json_decode($body, true)并检查json_last_error() - 记录原始响应体和状态码，方便排查是服务端返回了 HTML 错误页还是空响应
- 注意
getBody()是流对象，读一次就空了，调试时别重复读
关键片段：
} catch (BadResponseException $e) {
$body = (string)$e->getResponse()->getBody();
$statusCode = $e->getResponse()->getStatusCode();
$data = json_decode($body, true);
if (json_last_error() !== JSON_ERROR_NONE) {
error_log("Invalid JSON from {$statusCode}: {$body}");
}
// ... 再决定是否重试
}StreamAdapter 下 ssl_verify_host 和 ssl_verify_peer 默认为 true，内网自签名证书要关
本地开发或调用内网 HTTPS 服务时，若证书是自签的，不关校验就会报 SSL operation failed 或 unable to verify the first certificate，且这个错误属于 NetworkException，会被误判为网络问题而重试，浪费资源。
实操建议：
- 仅限可信内网环境关闭：设
'ssl_verify_host' => false, 'ssl_verify_peer' => false - 生产环境绝对不要关；如需对接自签证书服务，应把 CA 证书路径传给
ssl_cafile - 注意
ssl_verify_host关闭后，仍会校验证书有效期，所以过期证书还是会失败
配置示例（仅测试用）：
$client = new Client([
'timeout' => 10.0,
'ssl_verify_host' => false,
'ssl_verify_peer' => false,
]);超时和重试看着简单，但 CakePHP 的异常分类细、默认行为保守，不深挖 NetworkException 和 BadResponseException 的继承关系，很容易漏掉某类失败场景。最常被忽略的是空响应体触发的 JsonException —— 它不在重试 catch 范围里，一出就崩。
