Laravel 8 可通过自定义 RateLimiter 策略和中间件实现按用户角色、API Key 或设备指纹动态限流，并统一返回 JSON 格式 429 响应；需注册策略、创建继承 ThrottleRequests 的中间件重写 handle 方法、在路由中绑定策略名，并验证响应头与 JSON 错误体。
你需要为 Laravel 8 的 API 接口设置可按用户角色、API Key 或设备指纹动态调整的请求频率限制，而不是固定用 IP 或 ID 统一限流——这要求中间件能识别业务维度的唯一标识，并在超限时返回标准 JSON 响应而非 HTML 页面。
注册自定义限流策略并绑定到 RateLimiter
打开 app/Providers/AppServiceProvider.php，在 boot() 方法中添加策略定义：
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
RateLimiter::for('api_strict', function (Request $request) {
if ($request->header('X-Api-Key')) {
$key = hash_hmac('sha256', $request->header('X-Api-Key'), config('app.key'));
return Limit::perMinute(10)->by($key);
}
return Limit::perMinute(3)->by($request->ip());
});
注意：hash_hmac 生成的键必须是纯字符串，不能含斜杠或控制字符，否则 Redis 存储失败。
创建可复用的自定义中间件类
执行命令生成中间件：
php artisan make:middleware ApiThrottleMiddleware
编辑 app/Http/Middleware/ApiThrottleMiddleware.php，继承原生 ThrottleRequests 并重写关键方法：
public function handle($request, Closure $next, $limiter = 'api_strict') {
$response = $this->handleRequest($request, $next, $limiter);
if ($response instanceof Response && $response->getStatusCode() === 429) {
return response()->json([
'error' => 'Too many requests',
'retry_after' => $response->headers->get('Retry-After') ?? 60
], 429)
->withHeaders($response->headers->allPreserveCase());
}
return $response;
}
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
这一步绕过了默认的 HTML 429 页面，强制统一返回 JSON 格式错误体，前端可直接解析 retry_after 字段做倒计时重试。
在路由中启用并传入策略名
方法一：单个路由指定策略
Route::get('/v1/profile', [ProfileController::class, 'show'])
→ middleware('throttle:api_strict');
方法二：路由分组批量应用
Route::middleware(['throttle:api_strict'])->prefix('v1')->group(function () {
Route::get('/posts', [PostController::class, 'index']);
Route::post('/comments', [CommentController::class, 'store']);
});
方法三：按用户角色差异化调用（需配合 auth:sanctum）
RateLimiter::for('api_role_based', function (Request $request) {
$user = $request->user();
if ($user && $user->role === 'admin') {
return Limit::perMinute(500)->by($user->id);
}
return Limit::perMinute(30)->by($user?->id ?: $request->ip());
});
然后路由中写 middleware('throttle:api_role_based') 即可生效。
验证限流是否生效
① 启动本地开发服务器：php artisan serve
② 使用 curl 发起连续请求：
curl -H "X-Api-Key: test-key-123" http://localhost:8000/v1/profile
③ 观察响应头：
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
Retry-After: （仅触发后出现）
④ 第 11 次请求时，确认返回状态码为 429 且响应体是 JSON 格式，不是视图页面。
