本文详解如何将传统 curl 请求完整、健壮地转换为 laravel 9.x 推荐的 http 客户端调用，涵盖请求构造、头信息设置、超时控制、错误处理及参数传递等关键环节。
Laravel 9.x 内置的 Http 门面（基于 Guzzle）提供了简洁、可读性强且功能完备的 HTTP 客户端接口，完全替代手动管理 cURL 句柄。相比原始 cURL 实现，它自动处理连接复用、JSON 解析、异常抛出、重定向跟随等细节，并支持链式配置与测试模拟。
以下是等效迁移后的推荐写法：
use Illuminate\Support\Facades\Http;
static public function doExternalApiCall($endpoint = null, $params = [])
{
try {
// ✅ 自动拼接查询参数（无需手动 http_build_query）
$url = self::API_URL . ($endpoint ?? '');
$response = Http::withHeaders([
'accept-language' => 'en-US,en;q=0.9,pt-BR;q=0.8,pt;q=0.7',
'User-Agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Safari/537.36',
])
->timeout(10) // ✅ 替代 CURLOPT_TIMEOUT
->followRedirects() // ✅ 替代 CURLOPT_FOLLOWLOCATION
->throw() // ✅ 抛出异常（替代 CURLOPT_FAILONERROR + 手动检查）
->get($url, $params); // ✅ 自动编码并附加查询参数（GET）
return $response->body(); // 或 $response->json()（若响应为 JSON）
} catch (\Illuminate\Http\Client\ConnectionException $e) {
\Log::error('HTTP connection failed', ['url' => $url, 'error' => $e->getMessage()]);
return false;
} catch (\Illuminate\Http\Client\RequestException $e) {
\Log::error('HTTP request failed', [
'url' => $url,
'status' => $e->response?->status(),
'body' => $e->response?->body()
]);
return false;
} catch (\Exception $e) {
\Log::error('Unexpected error in API call', ['error' => $e->getMessage()]);
return false;
}
}? 关键改进说明：
- 参数传递更安全：->get($url, $params) 会自动使用 http_build_query 编码并追加到 URL，避免手拼导致的编码错误或注入风险；
- 错误处理标准化：->throw() 在非 2xx 响应时自动抛出 RequestException，配合 try/catch 可精准捕获网络、超时、服务端错误；
- Header 与选项解耦清晰：withHeaders() 设置请求头，timeout()、followRedirects() 等语义化方法替代底层 cURL option 魔数；
- 无需手动释放资源：HTTP 客户端自动管理连接与句柄，杜绝 curl_close() 遗漏风险；
- 调试友好：开发期可临时添加 ->withOptions(['debug' => true]) 查看详细请求/响应日志。
⚠️ 注意事项：
- 若需强制使用 HTTP/2，请确保底层 Guzzle 版本 ≥ 7.5 且 PHP 启用了 curl 扩展的 HTTP/2 支持（Laravel 默认不显式指定协议版本，由 Guzzle 自动协商）；
- accept-language 等非标准头建议确认目标 API 是否真正依赖；生产环境应避免固定 UA，必要时可动态生成或使用通用标识；
- 对于 POST/PUT 等请求，改用 ->post($url, $data) 即可，表单数据自动序列化，JSON 数据则用 ->asJson()->post(...)。
通过以上改造，代码更符合 Laravel 生态规范，可维护性、可测试性与健壮性显著提升。
