Laravel中间件编写教程及技巧分享

本文深入剖析Laravel中间件的正确编写规范与常见陷阱，强调必须通过`php artisan make:middleware`命令生成中间件类，否则即使代码完全正确也会因命名空间、方法签名或自动加载机制问题而彻底不执行；明确指出`handle()`方法中必须调用`$next($request)`以确保请求管道正常流转，遗漏将导致静默超时或空响应；详解带参数中间件的注册语法（必须使用数组形式如`['role:admin']`）、权限判断中的性能雷区（严禁在中间件中重复查库），并提供复用用户实例、预绑定服务、资源ID直比等高效实践方案，帮助开发者避开调试无果、响应卡死、权限失效等高频坑点。

中间件必须用 php artisan make:middleware 生成，手动创建的类即使放对位置、命名规范，Laravel 也不会加载它。

为什么中间件写了却完全不执行？

最常见原因是没走 Artisan 命令生成。Laravel 的自动发现机制只扫描通过 php artisan make:middleware 创建的类——它会确保命名空间、handle() 方法签名、Closure $next 参数类型全部正确。手动新建 CheckAdminRole.php 文件，哪怕内容一模一样，也会因 PSR-4 自动加载失败或方法签名微小偏差（比如漏了 \Closure 类型提示）被跳过。

典型错误现象：

• 在 app/Http/Kernel.php 的 $routeMiddleware 里注册了 'admin' => \App\Http\Middleware\CheckAdminRole::class，路由也加了 ->middleware('admin')，但请求压根不进 handle() 方法
• 调试时在 handle() 开头加 dd('here')，页面毫无反应

解决办法只有一条：php artisan make:middleware CheckAdminRole，然后把逻辑粘过去，别改签名。

handle() 方法里必须调用 $next($request) 吗？

必须。这是请求管道继续向下传递的唯一方式。漏掉这句，请求就卡死，不会报错，但你会看到：

• 浏览器一直 loading，最终超时（Nginx 504 或 PHP max_execution_time 超限）
• API 返回空响应体，状态码可能是 200 或 500，但无数据
• 日志里没有控制器执行记录，也没有后续中间件日志

注意：每个分支都得有返回值。不能只在 if 里 return，else 里忘写 $next($request)。正确写法是：

public function handle($request, Closure $next)
{
    if ($request->user() && $request->user()->banned) {
        return response('Banned!', 403);
    }

    // 所有路径最终都要走到这里或上面的 return
    return $next($request);
}

带参数的中间件怎么传参？

参数不是靠构造函数注入，而是从 handle() 第三个参数开始接收，且路由注册时必须用数组语法。

比如想限制「只有拥有指定角色的人才能访问」：

• 先改 handle() 签名：public function handle($request, Closure $next, $role)
• 路由写法必须是：->middleware(['role:admin'])，不是 ->middleware('role:admin')
• 如果写成字符串单值，Laravel 会当做一个中间件名去查 $routeMiddleware，找不到就静默忽略，等同于没加

另外，can 这类 Laravel 内置中间件依赖 Gate::define() 配置，没定义规则时永远返回 false，也不报错——这点极易被忽略。

权限判断逻辑能直接查数据库吗？

不能。每次请求都走 Eloquent 查询（比如 $request->user()->roles）会导致严重性能问题，尤其在高频接口或列表页中容易触发 N+1。

更合理的方式：

• 复用已加载的用户实例：$request->user()?->hasRole('admin')（需配合 spatie/laravel-permission 等扩展）
• 复杂权限提前绑定轻量服务，在 AppServiceProvider@boot 里 $this->app->singleton(MyPermissionChecker::class, ...)，中间件里直接 app(MyPermissionChecker::class)->can(...)
• “编辑当前文章”这类资源级判断，直接比对 $post->user_id === $request->user()->id，别再 Post::find() 查一次

中间件的 handle() 是整个请求生命周期里执行频次最高的函数之一，任何 IO 操作都该被警惕。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~