Guzzle 异常捕获与错误字符串返回方法

本文详解如何正确捕获 Guzzle HTTP 客户端抛出的各类异常（如 ClientException、RequestException），提取错误信息并统一返回结构化字符串或数组，避免直接返回异常对象导致调用方无法解析。

在使用 Guzzle 调用 Twitter API（或其他 RESTful 服务）时，$lists->get($list_id, $params) 等方法内部发起 HTTP 请求，一旦失败（如网络超时、404、401、500 等），Guzzle 不会静默失败，而是抛出继承自 \GuzzleHttp\Exception\TransferException 的具体异常类。常见误区是仅 catch (\GuzzleHttp\Exception\ClientException $e) ——该异常仅覆盖 HTTP 4xx 状态码（如 400、401、404），而忽略 5xx 服务器错误（由 ServerException 抛出）和网络层问题（如 DNS 失败、连接超时，由 RequestException 或 ConnectException 抛出）。

因此，要真正“捕获所有 Guzzle 异常并返回可用错误信息”，需按异常继承层级合理捕获：

• ✅ ClientException：处理 4xx 错误（客户端请求问题）
• ✅ ServerException：处理 5xx 错误（服务端内部错误）
• ✅ RequestException：兜底捕获所有传输层异常（含超时、DNS、SSL、无响应等）
• ⚠️ 避免只 catch ClientException ——这会导致 500 或超时仍向上冒泡，触发未捕获异常中断流程。

以下是推荐的健壮写法（已优化可读性与实用性）：

public static function get_list($list_id)
{
    $lists = self::get_lists();
    $params = [
        'list.fields' => 'created_at,follower_count,member_count,private,description,owner_id',
        'user.fields' => 'created_at,description,entities,id,location,name,pinned_tweet_id,profile_image_url,protected,public_metrics,url,username,verified,withheld'
    ];

    try {
        $response = $lists->get($list_id, $params);

        // 确保响应为 200 OK 并成功解析 JSON
        if ($response->getStatusCode() === 200) {
            return json_decode($response->getBody()->getContents(), true);
        }

        // 非 200 但未被异常捕获的情况（极少见，取决于客户端配置）
        return [
            'error' => 'Unexpected HTTP status code',
            'status_code' => $response->getStatusCode(),
            'body' => (string) $response->getBody()
        ];

    } catch (\GuzzleHttp\Exception\ClientException $e) {
        return self::formatGuzzleError($e, 'Client error');
    } catch (\GuzzleHttp\Exception\ServerException $e) {
        return self::formatGuzzleError($e, 'Server error');
    } catch (\GuzzleHttp\Exception\RequestException $e) {
        return self::formatGuzzleError($e, 'Network or request error');
    } catch (\Exception $e) {
        // 捕获其他非-Guzzle 异常（如 JSON 解析失败、空响应等）
        return [
            'error' => 'Unexpected application error',
            'message' => $e->getMessage(),
            'code' => $e->getCode()
        ];
    }
}

// 提取共用逻辑，便于维护与日志扩展
private static function formatGuzzleError(\GuzzleHttp\Exception\RequestException $e, string $type): array
{
    $error = [
        'error' => $type,
        'message' => $e->getMessage(),
        'request_url' => (string) $e->getRequest()->getUri(),
        'request_method' => $e->getRequest()->getMethod(),
    ];

    if ($e->hasResponse()) {
        $response = $e->getResponse();
        $error['response_status'] = $response->getStatusCode();
        $error['response_body'] = (string) $response->getBody();
    } else {
        $error['response_status'] = null;
        $error['response_body'] = 'No response received (e.g., timeout, connection refused)';
    }

    return $error;
}

✅ 关键改进说明：

• 使用 getStatusCode() 和 getBody()->getContents() 显式解析响应，避免依赖 $response 对象隐式行为；
• 将错误格式化逻辑抽离为私有方法 formatGuzzleError()，提升复用性与可测试性；
• 明确区分 ClientException（4xx）、ServerException（5xx）、RequestException（网络层），覆盖全部 Guzzle 异常场景；
• 始终返回 关联数组（array） 而非原始异常对象或裸字符串，确保调用方能安全 isset($result['error']) 判断失败；
• 补充 catch (\Exception $e) 兜底，防止因 json_decode() 等后续操作引发新异常被遗漏。

⚠️ 注意事项：

• 不要 return $e —— 异常对象不可直接 JSON 序列化，前端/调用方无法消费；
• 避免在 catch 块中 echo 或 var_dump，应统一返回结构化数据供上层处理（如记录日志、返回 API 错误响应）；
• 生产环境建议将敏感信息（如完整请求头、令牌）从错误响应中过滤，防止泄露。

通过以上方式，你不仅能稳定捕获所有 Guzzle 异常，还能输出清晰、一致、可编程解析的错误结构，大幅提升 API 客户端的健壮性与可观测性。