中间件 #

一、中间件概述 #

1.1 什么是中间件 #

中间件是过滤HTTP请求的机制，可以在请求到达控制器之前或之后执行操作。

text 
请求处理流程
┌─────────────┐
│   用户请求   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  中间件1    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  中间件2    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  控制器      │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   响应返回  │
└─────────────┘

1.2 中间件类型 #

类型 说明
前置中间件 请求处理前执行
后置中间件 请求处理后执行
终止中间件 响应发送后执行

二、创建中间件 #

2.1 创建命令 #

bash 
php artisan make:middleware CheckAge

2.2 中间件结构 #

php 
// app/Http/Middleware/CheckAge.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class CheckAge
{
    public function handle(Request $request, Closure $next)
    {
        if ($request->age < 18) {
            return redirect('home');
        }

        return $next($request);
    }
}

2.3 前置中间件 #

php 
public function handle(Request $request, Closure $next)
{
    // 在控制器执行前执行
    
    return $next($request);
}

2.4 后置中间件 #

php 
public function handle(Request $request, Closure $next)
{
    $response = $next($request);
    
    // 在控制器执行后执行
    
    return $response;
}

2.5 终止中间件 #

php 
public function terminate(Request $request, $response)
{
    // 响应发送后执行
    // 例如：记录日志
}

三、注册中间件 #

3.1 全局中间件 #

php 
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\App\Http\Middleware\CheckAge::class);
})

3.2 路由中间件 #

php 
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'age' => \App\Http\Middleware\CheckAge::class,
        'role' => \App\Http\Middleware\CheckRole::class,
    ]);
})

3.3 中间件组 #

php 
->withMiddleware(function (Middleware $middleware) {
    $middleware->group('web', [
        \App\Http\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \App\Http\Middleware\VerifyCsrfToken::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ]);
    
    $middleware->group('api', [
        \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        \Illuminate\Routing\Middleware\ThrottleRequests::class.':api',
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ]);
})

四、使用中间件 #

4.1 路由中间件 #

php 
// 单个路由
Route::get('/admin', function () {
    //
})->middleware('auth');

// 多个中间件
Route::get('/admin', function () {
    //
})->middleware(['auth', 'admin']);

// 中间件组
Route::middleware(['auth', 'admin'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

4.2 控制器中间件 #

php 
class UserController extends Controller
{
    public function __construct()
    {
        $this->middleware('auth');
        
        $this->middleware('admin')->only(['create', 'store', 'destroy']);
        
        $this->middleware('verified')->except('index');
    }
}

4.3 排除中间件 #

php 
Route::middleware(['auth'])->group(function () {
    Route::get('/profile', function () {
        // 需要认证
    });
    
    Route::get('/public', function () {
        // 不需要认证
    })->withoutMiddleware(['auth']);
});

五、中间件参数 #

5.1 定义带参数中间件 #

php 
class CheckRole
{
    public function handle(Request $request, Closure $next, ...$roles)
    {
        if (!in_array($request->user()->role, $roles)) {
            abort(403, '无权访问');
        }
        
        return $next($request);
    }
}

5.2 使用带参数中间件 #

php 
Route::get('/admin', function () {
    //
})->middleware('role:admin');

Route::get('/editor', function () {
    //
})->middleware('role:admin,editor');

六、内置中间件 #

6.1 常用中间件 #

中间件 说明
auth 用户认证
auth.basic HTTP基础认证
cache.headers 缓存头
can 授权检查
guest 仅限访客
password.confirm 密码确认
signed 签名URL验证
throttle 请求频率限制
verified 邮箱验证

6.2 使用示例 #

php 
// 认证
Route::middleware('auth')->group(function () {
    // ...
});

// 频率限制
Route::middleware('throttle:60,1')->group(function () {
    // 每分钟60次
});

// 授权
Route::middleware('can:update,post')->group(function () {
    // ...
});

七、中间件排序 #

7.1 设置优先级 #

php 
->withMiddleware(function (Middleware $middleware) {
    $middleware->priority([
        \Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests::class,
        \Illuminate\Cookie\Middleware\EncryptCookies::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests::class,
        \Illuminate\Routing\Middleware\ThrottleRequests::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
        \Illuminate\Auth\Middleware\Authorize::class,
    ]);
})

八、实战示例 #

8.1 日志中间件 #

php 
class LogRequests
{
    public function handle(Request $request, Closure $next)
    {
        Log::info('Request:', [
            'url' => $request->url(),
            'method' => $request->method(),
            'ip' => $request->ip(),
            'user_agent' => $request->userAgent(),
        ]);

        return $next($request);
    }
}

8.2 CORS中间件 #

php 
class Cors
{
    public function handle(Request $request, Closure $next)
    {
        return $next($request)
            ->header('Access-Control-Allow-Origin', '*')
            ->header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
            ->header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    }
}

8.3 API版本中间件 #

php 
class ApiVersion
{
    public function handle(Request $request, Closure $next, $version)
    {
        config(['api.version' => $version]);
        
        return $next($request);
    }
}

九、总结 #

9.1 核心要点 #

要点 说明
创建 php artisan make:middleware
注册 bootstrap/app.php
使用 ->middleware()
参数 中间件后加参数

9.2 下一步 #

掌握了中间件后，让我们继续学习 服务容器，了解Laravel IoC容器！

最后更新：2026-03-28