🎤 Laravel HTTP 客户端：拦截请求与转换响应的魔法讲座

大家好！👋 欢迎来到今天的讲座。今天我们要聊的是 Laravel 的 HTTP 客户端（Laravel HTTP Client），特别是它的 客户端请求拦截 和 响应结果转换机制。如果你对 Laravel 的 HTTP 客户端还不熟悉，那也没关系！我们从头开始，一步一步带你了解这个强大的工具。

---

🌟 什么是 Laravel HTTP Client？

Laravel HTTP 客户端是一个基于 Guzzle 的封装工具，它让开发者可以更方便地发送 HTTP 请求，并处理返回的响应数据。它的设计非常简洁，同时提供了强大的功能扩展能力。比如，你可以轻松地拦截请求、修改请求参数，或者在响应返回时进行自定义处理。

简单来说，Laravel HTTP 客户端就像是一个“快递小哥”，帮你把请求送到目标服务器，然后再把响应带回来。但和普通快递不同的是，这位“快递小哥”还可以在出发前检查包裹（请求）是否符合要求，以及在回来后帮你拆开包裹（响应）并整理内容。

---

🔍 请求拦截：如何在请求发出前做手脚？

假设你有一个需求：每次发送请求时，都需要在请求头中添加一个特定的 Authorization 字段。手动添加当然可以，但如果有很多地方都需要用到，岂不是麻烦死了？😱 别担心！Laravel 提供了优雅的解决方案——宏（Macros） 和 事件监听器（Event Listeners）。

方法一：使用宏（Macros）

宏是 Laravel 提供的一种扩展机制，允许你在不修改核心代码的情况下，为 HTTP 客户端添加自定义功能。比如，我们可以创建一个宏，在每次请求发出前自动添加 Authorization 头部。

use IlluminateSupportFacadesHttp;

Http::macro('withCustomAuth', function ($token) {
    return Http::withHeaders([
        'Authorization' => 'Bearer ' . $token,
    ]);
});

// 使用示例
$response = Http::withCustomAuth('your-token-here')->get('https://api.example.com/data');

通过这种方式，你可以在全局范围内复用这段逻辑，而不需要每次都手动添加头部。

---

方法二：使用事件监听器

Laravel 的 HTTP 客户端会触发一些内置事件，比如 IlluminateHttpClientEventsSending。这个事件会在请求即将发送时触发，允许你对请求进行最后的调整。

以下是一个简单的例子，展示如何通过事件监听器动态修改请求：

use IlluminateHttpClientEventsSending;
use IlluminateSupportFacadesEvent;

Event::listen(Sending::class, function (Sending $event) {
    // 动态修改请求头
    $event->request->headers['X-Custom-Header'] = 'Custom Value';

    // 或者修改请求体
    if ($event->request->method === 'POST') {
        $event->request->options['form_params']['custom_field'] = 'Custom Value';
    }
});

在这个例子中，我们在请求发出前添加了一个自定义头部 X-Custom-Header，并且如果请求方法是 POST，还会在表单参数中插入一个额外的字段。

💡 小贴士：事件监听器非常适合需要动态调整请求的场景，比如根据用户角色或上下文环境来决定是否添加某些头部或参数。

---

🔄 响应转换：如何让返回的数据更适合你的需求？

发送请求只是第一步，更重要的是如何处理返回的响应数据。Laravel 的 HTTP 客户端默认会将响应解析为字符串或 JSON 对象，但有时候这还不够。比如，你可能希望直接将 JSON 转换为 PHP 对象，或者对错误状态码进行统一处理。

方法一：使用 throw() 方法捕获错误

默认情况下，Laravel 不会对错误状态码（如 400、500 等）抛出异常。如果你希望在遇到错误时立即中断程序执行，可以使用 throw() 方法。

try {
    $response = Http::get('https://api.example.com/data')->throw();
} catch (IlluminateHttpClientRequestException $e) {
    // 处理错误
    $statusCode = $e->getResponse()->status();
    $errorMessage = $e->getResponse()->body();
    echo "Error: $statusCode - $errorMessage";
}

---

方法二：自定义响应转换逻辑

如果你想对响应数据进行更复杂的处理，可以通过 map() 方法实现。map() 允许你对响应对象进行任意操作，比如提取特定字段、格式化数据等。

以下是一个例子，展示如何将 JSON 响应转换为一个自定义的 PHP 对象：

namespace AppModels;

class ApiResponse {
    public $data;
    public $message;

    public function __construct($data, $message) {
        $this->data = $data;
        $this->message = $message;
    }
}

$response = Http::get('https://api.example.com/data')
    ->map(function ($response) {
        $json = $response->json();
        return new ApiResponse($json['data'], $json['message']);
    });

echo $response->data; // 输出 API 返回的数据部分
echo $response->message; // 输出 API 返回的消息部分

在这个例子中，我们将 JSON 响应转换为一个自定义的 ApiResponse 对象，方便后续使用。

---

📊 表格总结：请求拦截与响应转换的关键点

功能	描述	示例代码片段
请求拦截（宏）	在全局范围内复用请求修改逻辑	Http::macro('withCustomAuth', ...)
请求拦截（事件）	动态调整请求头部或参数	Event::listen(Sending::class, ...)
响应错误捕获	自动抛出异常以简化错误处理	$response->throw()
响应数据转换	将原始响应数据转换为更易用的格式	$response->map(...)

---

🚀 总结

Laravel 的 HTTP 客户端不仅仅是一个简单的 HTTP 请求工具，它还提供了丰富的扩展机制，让你可以根据实际需求灵活定制请求和响应的行为。无论是通过宏还是事件监听器拦截请求，还是通过 map() 和 throw() 转换响应，都能让你的代码更加优雅和高效。

希望今天的讲座对你有所帮助！如果有任何疑问，欢迎在评论区留言。😊 下次见！