Laravel的throttle中间件默认在请求超限时抛出ThrottleRequestsException并返回429响应。本文将探讨如何在不直接修改框架核心代码的情况下，通过全局异常处理器、命名限流器或自定义中间件，实现对限流行为的定制，包括返回自定义响应或将限流状态传递给路由闭包，以满足更灵活的业务需求。
引言：Laravel 限流机制概述
Laravel 框架通过 throttle 中间件提供了强大的请求限流功能，旨在保护应用程序免受滥用和拒绝服务攻击。当一个路由组或路由应用了 throttle 中间件，并且请求频率超过了设定的阈值时，Laravel 默认会抛出一个 Illuminate\Http\Exceptions\ThrottleRequestsException 异常。这个异常最终会被框架的异常处理器捕获，并通常转换为一个 HTTP 429 "Too Many Requests" 响应返回给客户端。
例如，以下代码会限制 /test/throttle 路由每分钟最多访问 10 次：
use Illuminate\Support\Facades\Route;
Route::middleware('throttle:10,1')->group(function () {
Route::get('/test/throttle', function() {
return response('OK', 200)->header('Content-Type', 'text/html');
});
});当请求超出限制时，用户将看到默认的 429 错误页面。然而，在某些业务场景中，我们可能需要更精细地控制限流后的行为，例如返回一个定制化的页面、JSON 响应，甚至在路由闭包中根据限流状态执行不同的逻辑。用户期望的用法是能够将一个布尔值（如 $tooManyAttempts）传递给路由闭包：
Route::middleware('customthrottle:10,1')->group(function ($tooManyAttempts) {
Route::get('/test/throttle', function() {
if ($tooManyAttempts) {
return response("My custom 'Too many attempts' page only for this route", 200)->header('Content-Type', 'text/html');
} else {
return response('You are good to go yet, he-he', 200)->header('Content-Type', 'text/html');
}
});
});直接将自定义参数传递给路由闭包并非 Laravel 中间件的常规设计模式。中间件通常通过 $next($request) 将请求传递给下一个处理程序，或者直接返回响应来终止请求。下面我们将探讨几种实现定制限流行为的方法。
方法一：全局异常处理器接管限流响应
这是最直接且影响范围最广的定制方式。通过在全局异常处理器 App\Exceptions\Handler.php 中捕获 ThrottleRequestsException 异常，我们可以统一处理所有因限流而产生的错误响应。
实现步骤：
-
保持默认限流中间件或使用自定义中间件抛出相同异常。 继续使用 Laravel 内置的 throttle 中间件即可，它在超限时会自动抛出 ThrottleRequestsException。
// routes/web.php use Illuminate\Support\Facades\Route; Route::middleware('throttle:10,1')->group(function () { Route::get('/test/throttle', function() { return response('You are good to go yet, he-he', 200)->header('Content-Type', 'text/html'); }); }); -
修改 App\Exceptions\Handler.php。 在 render 方法中添加对 ThrottleRequestsException 的检查，并返回自定义响应。
// app/Exceptions/Handler.php header('Content-Type', 'text/html'); } return parent::render($request, $exception); } }
优点：
- 实现简单，只需修改一处代码即可影响所有限流路由。
- 适用于全局统一的限流响应，例如显示一个通用的“请求过于频繁”页面。
缺点：
- 这种方法是“事后处理”，即异常已经抛出，请求流程已被中断。它无法将限流状态传递给路由闭包，让路由闭包自行决定响应内容。
方法二：使用命名限流器（Named Limiter）定制响应
Laravel 允许我们定义命名限流器，并在其中指定一个 responseCallback。这个回调函数会在限流被触发时执行，允许我们直接返回一个自定义响应，从而避免抛出异常。
实现步骤：
-
在 App\Providers\RouteServiceProvider.php 中定义命名限流器。 在 configureRateLimiting 方法中，使用 RateLimiter::for 定义一个名为 custom_throttle 的限流器，并为其提供一个 response 回调函数。
// app/Providers/RouteServiceProvider.php by($request->user()?->id ?: $request->ip()) ->response(function (Request $request, array $headers) { // 当限流被触发时，此回调函数将被执行 return response("我的自定义 '请求过多' 页面，直接来自命名限流器", 200) ->withHeaders($headers); }); }); } } -
在路由中使用定义的命名限流器。 将 throttle 中间件的参数设置为命名限流器的名称。
// routes/web.php use Illuminate\Support\Facades\Route; Route::middleware('throttle:custom_throttle')->group(function () { Route::get('/test/throttle', function() { return response('You are good to go yet, he-he', 200)->header('Content-Type', 'text/html'); }); });
优点：
- 可以在不同的命名限流器中定义不同的定制响应，实现更细粒度的控制。
- 避免了异常的抛出和捕获，直接在限流逻辑中返回响应。
缺点：
- 与异常处理器方法类似，路由闭包只会在未限流时执行。它也无法将限流状态传递给路由闭包。
方法三：自定义限流中间件并传递状态给路由闭包
如果你的核心需求是让路由闭包能够根据限流状态来决定响应，那么你需要创建一个自定义中间件，在其中执行限流逻辑，并将限流状态作为属性添加到 Request 对象中，然后将请求传递给路由闭包。
实现步骤：
-
创建自定义限流中间件。 使用 php artisan make:middleware CustomThrottleMiddleware 命令创建中间件，并实现限流逻辑。在这个中间件中，我们将不再抛出异常，而是将限流状态设置到 $request 对象中。
// app/Http/Middleware/CustomThrottleMiddleware.php limiter = $limiter; } /** * Handle an incoming request. * * @param \Illuminate\Http\Request $request * @param \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response) $next * @param int|string $maxAttempts 最大尝试次数 * @param float|int $decayMinutes 衰减时间（分钟） * @param string $prefix 缓存键前缀 * @return \Symfony\Component\HttpFoundation\Response */ public function handle(Request $request, Closure $next, $maxAttempts = 60, $decayMinutes = 1, $prefix = '') { // 构建限流键，可以根据用户ID、IP等信息自定义 $key = $prefix . sha1($request->ip()); // 示例：使用IP作为限流键 // 检查是否请求过多 $tooManyAttempts = $this->limiter->tooManyAttempts($key, $maxAttempts); // 如果未超限，则记录一次访问 if (! $tooManyAttempts) { $this->limiter->hit($key, $decayMinutes * 60); } // 将限流状态和其他相关信息添加到请求属性中 $request->attributes->set('tooManyAttempts', $tooManyAttempts); $request->attributes->set('maxAttempts', (int) $maxAttempts); $request->attributes->set('decayMinutes', (int) $decayMinutes); // 还可以添加剩余尝试次数、重试时间等信息 // $request->attributes->set('remainingAttempts', $this->limiter->retriesLeft($key, $maxAttempts)); // $request->attributes->set('retryAfter', $this->limiter->availableIn($key)); // 将请求传递给下一个中间件或路由闭包 return $next($request); } } -
注册自定义中间件。 在 App\Http\Kernel.php 的 $routeMiddleware 数组中注册你的自定义中间件。
// app/Http/Kernel.php \App\Http\Middleware\CustomThrottleMiddleware::class, ]; // ... } 在路由中使用自定义中间件并获取状态。 在路由闭包中，通过注入
