从入门到精通：Laravel API接口限流完整实战手册【保姆级教程】-php教程-PHP中文网

Laravel API限流需基于Redis驱动，通过RouteServiceProvider定义按用户ID或IP区分的命名策略，并在api路由中应用throttle:api中间件；同时配置自定义429响应及暴露X-RateLimit头，确保游客与登录用户隔离计数且避免NAT误杀。

从入门到精通：laravel api接口限流完整实战手册【保姆级教程】

你需要为 Laravel API 接口配置稳定、可区分用户身份、能返回标准 JSON 的限流机制，避免因 session 依赖导致 throttle 中间件在 routes/api.php 中完全失效，同时防止 NAT 环境下按 IP 限流误杀大量正常用户。

确认限流失效的根本原因

打开 routes/api.php，检查目标路由是否被 api 中间件组包裹 → 查看 app/Http/Kernel.php 中 $middlewareGroups['api'] 是否包含 \Illuminate\Routing\Middleware\ThrottleRequests::class → 运行 php artisan route:middleware | grep throttle，确认 throttle 中间件注册状态 → 执行 php artisan tinker，输入 cache()->store('redis')->get('throttle:ip:127.0.0.1')，若返回 null 或报错，说明缓存驱动未生效。

【必须用 Redis 缓存驱动】 Laravel 的限流计数器依赖原子操作，array 或 file 驱动在多进程下必然失效，且 RateLimiter::remaining() 会恒定返回 -1。

启用基础 API 限流（每分钟 60 次）

编辑 app/Providers/RouteServiceProvider.php，在 configureRateLimiting() 方法内添加：

RateLimiter::for('api', function (Request $request) { return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip()); });

修改 routes/api.php 中对应路由：Route::get('/status', [StatusController::class, 'check'])->middleware('throttle:api');

这一步让登录用户按 ID 单独计数，未登录用户 fallback 到 IP。注意 ?-> 是 PHP 8.0+ 空安全操作符，避免 Call to a member function id() on null 错误。

精细化区分游客与登录用户的限流策略

方法一：角色差异化配额

在 configureRateLimiting() 中替换原 api 策略：

RateLimiter::for('api', function (Request $request) { if ($request->user()?->is_premium) { return Limit::perMinute(500)->by($request->user()->id); } elseif ($request->user()) { return Limit::perMinute(100)->by($request->user()->id); } else { return Limit::perMinute(10)->by($request->ip()); } });

方法二：按请求头识别设备指纹（防 CDN/IP 共享）

新增策略 'api-by-device'：

RateLimiter::for('api-by-device', function (Request $request) { $deviceId = $request->header('X-Device-ID'); return Limit::perMinute(30)->by($deviceId ?: $request->ip()); });

Laravel Cloud

Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载

然后在特定路由启用：->middleware('throttle:api-by-device')

【X-Device-ID 值必须为纯字符串】 若含空格或斜杠，Redis key 会损坏，导致限流完全不触发。

自定义 429 响应格式并暴露关键响应头

第一步：创建中间件 php artisan make:middleware ApiThrottleResponse

第二步：在 app/Http/Middleware/ApiThrottleResponse.php 的 handle() 方法中，捕获 ThrottleRequestsException：

try { return $next($request); } catch (ThrottleRequestsException $e) { return response()->json([ 'message' => '请求过于频繁，请稍后再试', 'retry_after' => $e->getHeaders()['Retry-After'] ?? 60 ], 429) ->withHeaders([ 'X-RateLimit-Limit' => $e->getHeaders()['X-RateLimit-Limit'], 'X-RateLimit-Remaining' => $e->getHeaders()['X-RateLimit-Remaining'], 'Retry-After' => $e->getHeaders()['Retry-After'], ]); }

第三步：在 app/Http/Kernel.php 的 $middlewareGroups['api'] 中，将 \App\Http\Middleware\ApiThrottleResponse::class 放在 \Illuminate\Routing\Middleware\ThrottleRequests::class 之后。

第四步：确保 config/cors.php 中 'expose' 数组包含 ['X-RateLimit-Limit', 'X-RateLimit-Remaining', 'Retry-After']，否则前端无法读取这些头部。