本文深入探讨如何在 laravel 应用程序中定制限流中间件的响应行为。我们将介绍两种主要方法：通过全局异常处理器捕获 `throttlerequestsexception` 实现统一的限流响应，以及利用 laravel 命名限流器（named rate limiters）的 `responsecallback` 功能实现更精细、更具灵活性的限流策略和自定义响应，帮助开发者根据业务需求提供友好的用户体验。
Laravel 框架内置的 throttle 中间件是保护应用程序免受滥用和过载的强大工具。默认情况下，当请求达到限流阈值时，throttle 中间件会抛出 Illuminate\Http\Exceptions\ThrottleRequestsException 异常，这通常会导致 Laravel 返回一个 HTTP 429 (Too Many Requests) 状态码的响应，并可能显示默认的错误页面。
然而，在许多实际应用场景中，开发者可能不希望仅仅返回一个通用的 429 错误页面。例如，我们可能希望：
直接将限流状态（如一个布尔值 tooManyAttempts）作为参数传递给路由闭包，虽然在概念上吸引人，但与 Laravel 中间件的工作方式并不直接兼容。中间件通常在请求到达路由之前处理请求，并决定是继续处理还是提前终止请求。当限流触发时，中间件会抛出异常来终止请求流，而不是将状态传递给后续的路由处理逻辑。因此，我们需要采用更符合 Laravel 架构的方式来定制限流响应。
接下来，我们将介绍两种实现这一目标的有效方法。
当 throttle 中间件触发限流时，它会抛出 ThrottleRequestsException。Laravel 的全局异常处理器 (app/Exceptions/Handler.php) 是捕获和处理应用程序中所有异常的中心位置。通过在此处捕获 ThrottleRequestsException，我们可以全局性地定制限流时的响应。
修改 app/Exceptions/Handler.php 文件 在 render 方法中添加一个条件判断，检查抛出的异常是否为 ThrottleRequestsException。如果是，则返回你自定义的响应。
// app/Exceptions/Handler.php
namespace App\Exceptions;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Http\Exceptions\ThrottleRequestsException;
use Throwable;
class Handler extends ExceptionHandler
{
/**
* A list of the exception types that are not reported.
*
* @var array<int, class-string<Throwable>>
*/
protected $dontReport = [
//
];
/**
* A list of the inputs that are never flashed to the session on validation exceptions.
*
* @var array<int, string>
*/
protected $dontFlash = [
'current_password',
'password',
'password_confirmation',
];
/**
* Register the exception handling callbacks for the application.
*
* @return void
*/
public function register()
{
$this->reportable(function (Throwable $e) {
//
});
}
/**
* Render an exception into an HTTP response.
*
* @param \Illuminate\Http\Request $request
* @param \Throwable $exception
* @return \Symfony\Component\HttpFoundation\Response
*
* @throws \Throwable
*/
public function render($request, Throwable $exception)
{
if ($exception instanceof ThrottleRequestsException) {
// 获取限流相关的 HTTP 头信息，例如 Retry-After
$headers = $exception->getHeaders();
// 返回自定义的响应
// 示例1: 返回一个自定义的HTML页面，状态码200
return response("<h1>请求过于频繁，请稍后再试！</h1><p>请在 " . ($headers['Retry-After'] ?? '几秒') . " 后重试。</p>
<div class="aritcle_card">
<a class="aritcle_card_img" href="/ai/1154">
<img src="https://img.php.cn/upload/ai_manual/000/000/000/175680126049574.png" alt="Motiff">
</a>
<div class="aritcle_card_info">
<a href="/ai/1154">Motiff</a>
<p>Motiff是由猿辅导旗下的一款界面设计工具，定位为“AI时代设计工具”</p>
<div class="">
<img src="/static/images/card_xiazai.png" alt="Motiff">
<span>148</span>
</div>
</div>
<a href="/ai/1154" class="aritcle_card_btn">
<span>查看详情</span>
<img src="/static/images/cardxiayige-3.png" alt="Motiff">
</a>
</div>
", 200)
->header('Content-Type', 'text/html')
->withHeaders($headers); // 推荐保留限流头信息
// 示例2: 返回一个JSON响应，状态码429 (更符合RESTful API规范)
// return response()->json([
// 'message' => 'Too many requests.',
// 'retry_after' => $headers['Retry-After'] ?? null,
// ], 429)->withHeaders($headers);
}
return parent::render($request, $exception);
}
}应用限流中间件 在路由中使用标准的 throttle 中间件即可。
// routes/web.php
Route::middleware('throttle:10,1')->group(function () {
Route::get('/test/throttle-exception', function () {
return response('您好，请求正常。', 200);
});
});Laravel 提供了命名限流器（Named Rate Limiters）功能，它允许你定义多个具名的限流规则，并在路由中引用它们。更重要的是，命名限流器允许你通过 responseCallback 选项为每个限流器定义一个自定义的响应回调函数。这是实现高度灵活限流响应定制的关键。
定义命名限流器 在 app/Providers/RouteServiceProvider.php 文件的 boot 方法中，使用 RateLimiter::for() 方法定义你的命名限流器。
// app/Providers/RouteServiceProvider.php
namespace App\Providers;
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Foundation\Support\Providers\RouteServiceProvider as ServiceProvider;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\Facades\Route;
class RouteServiceProvider extends ServiceProvider
{
// ... 其他属性和方法
/**
* Define your route model bindings, pattern filters, and other route configuration.
*
* @return void
*/
public function boot()
{
// 定义一个名为 'custom-web-throttle' 的限流器
RateLimiter::for('custom-web-throttle', function (Request $request) {
return Limit::perMinute(5)->response(function (Request $request, array $headers) {
// 这是当 'custom-web-throttle' 限流器触发时，将执行的自定义响应逻辑
return response("<h1>Web 页面请求过于频繁！</h1><p>请稍后重试。</p>", 200)
->header('Content-Type', 'text/html')
->withHeaders($headers); // 确保包含限流头
});
});
// 定义一个名为 'api-throttle' 的限流器
RateLimiter::for('api-throttle', function (Request $request) {
// 可以根据用户是否登录、用户类型等动态调整限流规则
$maxAttempts = $request->user() ? 60 : 10; // 登录用户每分钟60次，未登录10次
return Limit::perMinute($maxAttempts)
->by(optional($request->user())->id ?: $request->ip()) // 区分用户或IP
->response(function (Request $request, array $headers) {
// 这是当 'api-throttle' 限流器触发时，将执行的自定义响应逻辑
return response()->json([
'status' => 'error',
'message' => 'Too many requests for this API endpoint.',
'retry_after_seconds' => $headers['Retry-After'] ?? null,
], 429) // API 通常返回 429 状态码
->withHeaders($headers); // 确保包含限流头
});
});
$this->configureRateLimiting(); // 如果你还有其他限流配置，通常会在这里调用
$this->routes(function () {
Route::middleware('api')
->prefix('api')
->group(base_path('routes/api.php'));
Route::middleware('web')
->group(base_path('routes/web.php'));
});
}
/**
* Configure the rate limiters for the application.
*
* @return void
*/
protected function configureRateLimiting()
{
// 可以在这里定义其他限流器
}
}应用命名限流器到路由 在路由文件中，使用 throttle:你的限流器名称 来应用你定义的命名限流器。
// routes/web.php
Route::middleware('throttle:custom-web-throttle')->group(function () {
Route::get('/test/custom-web', function () {
return response('您好，Web 页面请求正常。', 200);
});
});
// routes/api.php
Route::middleware('throttle:api-throttle')->group(function () {
Route::get('/data', function () {
return response()->json(['data' => 'API 数据']);
});
});状态码的选择:
保留限流 HTTP 头: 在自定义响应中，无论是通过异常处理器还是命名限流器的 responseCallback，都强烈建议保留或重新添加 Laravel 默认提供的限流相关 HTTP 头：
异常处理器与命名限流器的优先级: 如果一个路由同时使用了命名限流器，并且该限流器定义了 responseCallback，那么当限流触发时，responseCallback 会优先执行并返回响应。在这种情况下，ThrottleRequestsException 将不会被抛出，因此全局异常处理器中的相关逻辑也不会被触发。这意味着 responseCallback 提供了更局部的、更高优先级的控制。
避免在路由闭包中直接处理限流: 如前所述，直接将限流状态传递给路由闭包是不可行的。限流中间件的设计哲学是作为请求管道中的一个守卫，当条件不满足时，它会中断管道并抛出异常或直接返回响应，而不是让请求继续向下传递。
Laravel 为开发者提供了灵活的机制来定制限流中间件的响应行为。
选择哪种方法取决于你的具体需求和对代码维护性的考量。无论选择哪种方式，都应遵循 HTTP 最佳实践，尤其是在处理 API 限流时，确保返回清晰的状态码和有用的限流头信息。
以上就是Laravel 限流中间件响应定制：从异常处理到命名限流器回调的详细内容，更多请关注php中文网其它相关文章！
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移，垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是，许多工具可以让 Windows 保持平稳运行。
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号
198
收藏
