本文详解如何将传统 curl 请求完整、安全地迁移至 laravel 9.x 内置的 http 客户端，涵盖请求构造、头信息设置、超时控制、错误处理及查询参数编码等关键实践。
Laravel 9.x 的 Http 门面（基于 Guzzle 封装）提供了简洁、链式、类型友好的 HTTP 请求接口，完全可替代手动 cURL 操作。以下是你原有方法的现代化重构方案：
✅ 推荐迁移写法（安全、健壮、符合 Laravel 最佳实践）
use Illuminate\Support\Facades\Http;
static public function doExternalApiCall($endpoint = null, $params = [])
{
try {
// 构建完整 URL：API 基础地址 + 端点 + 查询参数（自动编码）
$url = self::API_URL . ltrim($endpoint, '/');
// 使用 Http::get() 自动处理查询参数（无需手动 http_build_query）
$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
->withOptions([
'http_errors' => true, // 对应 CURLOPT_FAILONERROR（默认已启用，显式声明更清晰）
'allow_redirects' => ['max' => 5], // 对应 CURLOPT_FOLLOWLOCATION + CURLOPT_MAXREDIRS
'curl' => [
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2_0,
],
])
->get($url, $params); // $params 会自动作为查询字符串拼接（已 URL 编码）
// 检查状态码是否为 2xx
if ($response->successful()) {
return $response->body();
}
// 可选：记录非 2xx 响应（如 404、500）
\Log::warning('API request failed', [
'url' => $response->effectiveUri(),
'status' => $response->status(),
'body' => $response->body(),
]);
return false;
} catch (\Illuminate\Http\Client\ConnectionException $e) {
\Log::error('HTTP connection failed', ['url' => $url, 'message' => $e->getMessage()]);
return false;
} catch (\Illuminate\Http\Client\RequestException $e) {
\Log::error('HTTP request failed', ['url' => $url, 'message' => $e->getMessage()]);
return false;
} catch (\Exception $e) {
\Log::error('Unexpected error in API call', ['url' => $url, 'exception' => $e]);
return false;
}
}? 关键迁移要点说明
- ✅ 查询参数自动编码：Http::get($url, $params) 内部自动调用 http_build_query() 并正确拼接到 URL，无需手动拼接；
- ✅ 头信息统一管理：使用 withHeaders() 设置 accept-language 和 User-Agent，语义清晰；
- ✅ 超时与重定向：timeout(10) 替代 CURLOPT_TIMEOUT；allow_redirects 控制跳转行为（需在 withOptions 中配置）；
- ✅ HTTP/2 支持：通过 curl 子选项启用 CURL_HTTP_VERSION_2_0（确保底层 cURL 版本 ≥ 7.47.0 且支持 HTTP/2）；
- ✅ 错误处理专业化：捕获 ConnectionException（网络层失败）、RequestException（HTTP 层失败，如 4xx/5xx），避免裸 try-catch \Exception 掩盖问题；
-
⚠️ 注意事项：
- Http::get() 默认启用 http_errors => true，即非 2xx 响应会抛出 RequestException —— 若需统一处理所有响应（包括 4xx/5xx），请改用 throw(false) 链式调用；
- 不建议在生产环境启用 'debug' => true（会输出详细 cURL 日志到 STDERR）；
- Referer 头若需添加，请直接加入 withHeaders()，无需额外封装逻辑。
? 补充：快速测试示例
// 在 Tinker 或测试中验证
$response = Http::withHeaders(['User-Agent' => 'TestBot'])->get('https://httpbin.org/get', ['q' => 'laravel']);
dd($response->json()); // 输出结构化 JSON 响应通过以上重构，你的代码将更简洁、可维护性更强，并天然受益于 Laravel HTTP 客户端的 Mock 测试支持（Http::fake()）、连接池复用、中间件扩展等高级能力。
