Laravel + Dcat Admin 实战：送水站后台的中间件、状态机与队列设计

简介：这是一份基于PHP Laravel与Dcat Admin构建的送水后台管理系统源码包，面向掌握PHP基础、想了解主流框架整合开发或需要快速搭建管理后台的开发者。系统实现了订单管理、用户管理、配送员管理等完整业务模块，代码中清晰展示了路由定义、中间件权限校验、Eloquent ORM数据库操作、Auth用户认证以及Dcat Admin菜单与界面资源的组织方式。资源整体共986个文件，以444个js脚本、137个php业务代码、115个css样式、99个html视图为主，辅以字体、图片、配置文件等，压缩包仅7.59MB，目录结构规整，便于按模块查阅。已有278人在线学习浏览。深入阅读可掌握Laravel的路由与服务容器、Dcat Admin的自定义组件和菜单配置、基于Policy的访问策略，以及Blade模板渲染后台页面的工程实践，适合用于课程设计、毕业设计或实际业务系统的二次开发。

1. 一个送水站后台，为什么要同时押注 Laravel 和 Dcat Admin

送水业务看起来是“体力活”，但跑起来的系统一点都不简单：客户要按小区、楼栋、楼层记地址，订单要区分“立即送”和“预约送”，水票要防止超发和重复核销，配送员的在途单量要实时看到。这些需求落成一个后台管理系统时，Laravel 正好覆盖了从路由、队列到任务调度的完整服务端链路，而 Dcat Admin 能基于 Laravel 生态把表单、表格、权限管理快速组装成一套可操作的后台界面，两者组合就是目前 PHP 后台管理系统里相当主流的一种搭建方式。

这套系统的源码通常以 zip 形式分发，解压后结构相对固定：app 目录里是控制器和模型，database 里是迁移文件和填充数据，dcat 相关的资源放在 Admin 扩展目录中。你拿到的不只是“页面”，而是一整套业务状态机、队列任务和权限分配。适合谁？一个是送水站做数字化管理，另一个是想在 Laravel 后台管理系统上做二次开发的 PHP 工程师。下面我会按“中间件权限 → 业务建模 → 异步队列 → 后台 CRUD → 部署排错”的顺序，把它拆成可以直接复现的工程步骤。

2. Laravel 路由与中间件：权限链路在送水系统中的落地

2.1 为什么先把中间件设计放在订单功能之前

送水后台存在一个隐蔽问题：订单被创建后，所有接单员其实都能看到全城的客户地址。业务上“抢单式”管理没问题，但“追责式”管理就必须让每个操作都能回溯到具体的人。Laravel 中间件在这里承担“统一拦截”的角色。

Laravel 中间件的实现原理和装饰器模式非常接近。每个中间件都会接收请求对象，做完前置处理（比如判断用户是否登录），然后调用$next($request)把请求传递给下一个中间件，直到进入控制器；响应返回时会再次经过中间件做后置处理。Laravel 框架层用Illuminate\Pipeline\Pipeline完成这种洋葱式的层层包裹。这也是为什么 Dcat Admin 会自带一层admin.auth中间件，它拦截的是“是否登录后台”。

如果你在送水系统里想把“操作日志”“权限校验”“接口响应格式”这些横切逻辑统一收口，中间件就是第一道关卡。下面这个命令生成一个用于校验订单归属的中间件：

php artisan make:middleware OrderScopeMiddleware

生成的文件默认放在app/Http/Middleware/OrderScopeMiddleware.php。中间件里的核心逻辑是：判断当前用户能访问的订单范围，是“只看自己区域内”还是“全部”，再决定是否放行或抛出 403。

2.2 自定义一个「订单归属校验」中间件并注册到路由组

OrderScopeMiddleware的 handle 方法内一般这样写：

public function handle(Request $request, Closure $next, string $scope = 'own') { $user = $request->user(); if ($scope === 'own' && !$user->can_view_all_orders) { // 限制只能访问自己的订单，把 user_id 注入请求参数 $request->merge(['scoped_user_id' => $user->id]); } return $next($request); }

这段代码的关键在$next($request)这一行，它表示中间件的前置逻辑到此结束，请求继续向后传递。如果前面的逻辑里有“不满足条件就 abort”的分支，请求就不会进入控制器。$scope参数是从路由定义里传入的，比如下面这个路由组就区分了“自有订单”和“全部订单”两个范围：

Route::middleware(['auth:admin', 'order.scope:own'])->group(function () { Route::get('/my-orders', [OrderController::class, 'index']); }); Route::middleware(['auth:admin', 'order.scope:all'])->group(function () { Route::get('/all-orders', [OrderController::class, 'index']); });

注册中间件别名需要在app/Http/Kernel.php的$routeMiddleware数组里加一行'order.scope' => \App\Http\Middleware\OrderScopeMiddleware::class。需要注意别名不能和auth、admin.auth重名，Dcat Admin 会自动注册admin.auth别名，你要做的只是把自定义中间件排在它的后面，保证“先登录，再鉴权”。

2.3 中间件顺序的常见坑：为什么登录状态在控制器里拿不到

中间件在 Laravel 里的执行顺序由$middlewarePriority数组控制，普通开发中最常见的问题是：在中间件里直接调用$request->user()，但前置的 session 或 auth 中间件还没执行，得到null。送水系统的订单接口一般挂在auth:admin之下，Dcat Admin 的认证用户模型是独立的admin_user表，所以你在自定义中间件里做的第一件事应该是确认数据源来自哪张表。

顺序修正方法是在路由组里显式控制：

Route::middleware(['admin.auth', 'order.scope:own'])->group(...);

中间件的执行顺序在 Laravel 中是从左到右，因此admin.auth必须写在order.scope之前。如果你把自定义中间件写在前面，再去用户对象，就会得到 null，这种问题排查起来非常隐蔽，因为浏览器依然返回 200，只是业务数据不对。

下表是送水后台常用的中间件及其用途参考：

提示：中间件的数量不是越多越好，能合并成参数判断的逻辑就合并。送水系统的订单接口往往有多个版本，中间件参数比复制多个中间件类更容易维护。

3. 送水业务的数据建模：客户、订单、水票和配送员的状态机设计

3.1 订单状态机：从“下单”到“已送达”的字段规划

送水系统的订单状态如果只用一个status字段存数字，会带来两个问题：一是状态流转没有约束，谁都能把“已送达”改回“待派单”；二是改状态的日志分散在不同控制器里，后续对账困难。我见过比较好的做法，是先把整条状态链路用常量定义成一个“状态机”类，在业务层统一校验。

订单的状态可以分成这样几档：待派单、已派单、配送中、已送达、已取消、退款中。其中“已取消”还包含“客户取消”和“超时未派单自动取消”两个触发源，如果状态机里不区分，运营后台就会看到一个笼统的“已取消”，既不知道原因，也追不了责。

定义状态机的类通常长这样：

class OrderStatus { public const PENDING = 0; // 待派单 public const ASSIGNED = 1; // 已派单 public const DELIVERING = 2; // 配送中 public const COMPLETED = 3; // 已送达 public const CANCELED = -1; // 已取消 public const TRANSITIONS = [ self::PENDING => [self::ASSIGNED, self::CANCELED], self::ASSIGNED => [self::DELIVERING, self::CANCELED], self::DELIVERING => [self::COMPLETED], ]; }

这种写法的意义在于：所有状态变化都必须在代码里显式声明“从哪个状态可以走到哪个状态”，控制器里绝不能直接$order->status = 3一存了之。TRANSITIONS数组就是一张合法流转表，任何不在表里的跳转都直接抛出异常。

3.2 建表 migration 和业务 Service 层的配合

建表时，orders 表除了基本的状态字段，还需要冗余客户地址快照。为什么要冗余？因为客户地址在前台是可以修改的，而订单一旦生成，配送员拿到的必须是下单那一刻的地址。若在服务端反复 join 客户表，等地址被改后整个订单历史就全乱了。migration 里几个关键字段如下：

Schema::create('orders', function (Blueprint $table) { $table->id(); $table->unsignedBigInteger('customer_id')->index(); $table->unsignedBigInteger('delivery_man_id')->nullable()->index(); $table->tinyInteger('status')->default(0); $table->string('address_snapshot', 255); $table->integer('bucket_count')->default(1); $table->timestamp('expected_delivery_time')->nullable(); $table->timestamps(); });

订单创建的动作不放在控制器里，而是抽到OrderService里，原因是“派单”这个动作会同时影响三张表：orders 表加配送员、delivery_men 表加在途单量、operation_logs 表加一条操作记录。三个写入如果在控制器里散着写，任何一个失败都会造成数据不一致。Service 层配合DB::transaction可以保证要么全部成功，要么全部回滚。

3.3 水票核销时的并发控制：lockForUpdate 具体怎么用

水票核销是送水系统中最需要并发保护的场景。用户在小程序端连续点击两次“用券下单”，后端可能同时收到两个请求，如果都读到“票面剩余 1 张”，就会产生超发。Laravel 里最直接的手段是悲观锁：

DB::transaction(function () use ($ticketId) { $ticket = WaterTicket::where('id', $ticketId) ->lockForUpdate() ->firstOrFail(); if ($ticket->status !== 0) { throw new \Exception('水票已被使用，请刷新后再试'); } $ticket->status = 1; $ticket->used_at = now(); $ticket->save(); });

lockForUpdate会在数据库层面给这一行记录加排他锁，事务提交前其他事务的读写都会被阻塞。但要注意：这只是锁住了“核销”这个动作，并没有锁住“下单”本身。如果用户同时用两张水票下单，而两张票属于同一个人，建议把整个下单事务按 customer_id 做一次分布式锁处理，这样体验更完整。当然事务里的锁必须保持事务尽可能短，不要在锁内调用第三方短信接口。

4. 用 Redis 消费组承接业务峰值：送水系统的队列任务与调度

4.1 高峰期的三个异步场景

送水站的单量有明显的波峰：早高峰 8-10 点、傍晚 17-19 点，以及水票秒杀活动开始的前 10 分钟。此时同步请求如果做短信通知、库存扣减、对账统计，一个请求就要耗 200ms 以上，并且某个服务一旦超时，订单主流程也会被拖垮。

送水后台里必须异步化的三件事分别是：短信通知、水票核销后的回调统计、以及配送员小程序端的实时在途单量推送。这三类任务的共同点是不需要立刻返回给客户端，失败后还要支持重试。Laravel 的 Queue 机制天然覆盖这一需求，底层连接推荐直接使用 Redis。

4.2 手写一个队列任务并用 Dispatch 分发

创建队列任务的命令是php artisan make:job SendOrderSms，生成的文件在app/Jobs目录。任务类的 handle 方法里注入依赖，Laravel 的 IoC 容器会自动解析。

class SendOrderSms implements ShouldQueue { public function handle() { $phone = $this->order->customer_phone; SmsChannel::send($phone, '您的桶装水订单已派单，配送员15分钟内出发'); } }

调用侧一般是订单状态变为“已派单”时执行：

SendOrderSms::dispatch($order);

如果任务失败，Laravel 默认会把它放进failed_jobs表。该表的三个字段connection、queue、payload能准确告诉你失败任务来自哪个队列。这里有一个细节：任务类里用public $timeout和public $tries控制单次执行时间和重试次数，短信通道如果持续超时，任务重试 3 次后进失败队列表，人工复核是合理的上限。

4.3 Horizon 与 Redis 消费组的参数设置

到这一步，任务已经写好了，但谁去执行它？答案是 worker 进程。生产环境建议让 Laravel Horizon 接管，而不要直接php artisan queue:work。Horizon 的一个明显优势是它能用可视化管理 Redis 里的队列，还能读取消费组里的待处理任务数。

一个基础的 horizon 配置示例如下：

'defaults' => [ 'supervisor-1' => [ 'connection' => 'redis', 'queue' => ['sms', 'stats'], 'balance' => 'simple', 'maxProcesses' => 10, 'maxTime' => 60, 'tries' => 3, ], ],

参数说明：balance设为simple表示每个进程只处理一个队列任务，避免队列之间互相排队；maxProcesses指最多拉起 10 个 worker 进程，不要盲目调大，进程数高于 CPU 核数会导致上下文切换开销反而增加；maxTime指单进程运行 60 秒后重启，能解决 PHP 进程内存泄漏的累积问题。Redis 消费组模式下，每个 worker 从 stream 里读取任务后，需要手动调用ack才能移除消息。Horizon 已经把这个过程封装好了，你要做的反而是避免在任务里写die或exit，否则进程直接退出会破坏消费组机制。

提示：送水后台的短信任务如果经常失败，先检查.env里QUEUE_CONNECTION是否为redis，默认的sync同步驱动虽然调试方便，但生产环境务必切换，否则队列任务会退化成同步执行。

5. Dcat Admin 快速搭后台：把订单和配送员做成一张“活”的工单

5.1 用 dcat/laravel-admin 建后台骨架的完整命令链

Dcat Admin 是 Laravel 生态里一个基于 Laravel 的快速后台开发工具，它的核心价值在于：你不需要从零写 HTML、CSS 和 Vue 组件，只需要定义好数据表格（Grid）和表单（Form），它就会生成对应的管理界面。安装方式在 Laravel 项目里执行：

composer require dcat/laravel-admin php artisan admin:install

admin:install会完成三件关键工作：创建admin_users管理用户表、生成后台路由文件（默认路径是admin）、把静态资源发布到 public 目录。这里要注意版本兼容问题，Dcat Admin 2.x 对 Laravel 的版本要求是 8.x 及以上，装完之后最好用php artisan serve先在本地跑一遍/admin登录页，确认能打开再继续开发。

5.2 Grid 表格开发：订单列表的筛选器和操作按钮是怎么配置出来的

订单管理页是送水后台最核心的页面，它需要同时支持按客户手机号搜索、按配送员筛选、按状态分组、以及导出某日全部订单。在 Dcat Admin 里，这一切都是通过控制器里的grid()方法配置的。

protected function grid() { return Grid::make(new Order(), function (Grid $grid) { $grid->column('id', '单号')->sortable(); $grid->column('customer.phone', '客户电话'); $grid->column('delivery_man.name', '配送员'); $grid->column('status', '状态')->using(OrderStatus::labels()); $grid->column('created_at', '下单时间')->sortable(); $grid->filter(function (Grid\Filter $filter) { $filter->like('customer.phone', '客户电话'); $filter->equal('status', '状态')->select(OrderStatus::labels()); }); $grid->actions(function (Grid\Displayers\Actions $actions) { $actions->disableView(); $actions->disableDelete(); }); }); }

上述配置里，customer.phone是一种关联查询字段写法，Dcat Admin 会自动去orders表关联customers表取值，省去手动 join。using()方法的作用是把 int 状态值映射成文字，这样列表里展示的就是“待派单”而不是数字 0。filter 闭包里写的equal是一种精确筛选，like是模糊筛选，这两个方法会对 SQL 查询条件自动做转义，安全性优于直接写在 where 里。

5.3 表单和权限分配：接单员的角色里只给“处理自己订单”的按钮

后台表单对应的是form()方法，创建订单时，配送员选择框应该被限制在“当前配送员”角色内。Dcat Admin 的表单支持Form::select选项数据源指定，常见写法是传一个异步接口，让搜索时动态加载数据，避免几千名配送员一次性拉下来拖慢表单页面。

权限分配要跟第 2 章的中间件配合起来。Dcat Admin 自带 RBAC 权限管理，在后台的“角色”菜单里给“接单员”这个角色只勾选“订单查看”和“状态更新”，不给“删除”和“导出”。但这里有个隐患：按钮隐藏不等于接口安全。前端不显示删除按钮，只意味着操作入口藏掉了，请求依然可以直接打给删除接口，因此后端中间件仍然要校验权限。Dcat Admin 在 Form 的creating和updating回调事件里可以做最后一道拦截。

$form->saving(function (Form $form) { if (!admin_user()->can('order.update')) { throw new \Exception('您没有修改订单的权限'); } });

这段saving回调在数据写入前执行，admin_user()是 Dcat Admin 提供的获取当前登录后台用户的方法。把它和页面调用权限组合在一起，才能说真正完成了“按钮可见”和“操作可达”两层控制。

6. 部署与排错：跑通送水后台的三个验证点和日志修复顺序

6.1 部署前必须检查的目录权限和配置缓存

送水后台项目上传到服务器之后，前几次启动报错大多集中在权限问题。第一个要检查的是storage/和bootstrap/cache/目录的写权限。Laravel 的日志、缓存文件、session 都写在 storage 下，权限不足时会出现“Permission denied”的 RuntimeException。第二个容易踩的坑是.env文件在php artisan config:cache之后会“失效”。如果你把配置文件缓存了，.env的修改不会立即生效，必须重新执行php artisan config:clear；同时config:cache期间不要用env()函数，官方建议只在配置文件里读环境变量。

6.2 用三个命令验证整条链路是否跑通

部署完成后，我一般会按顺序跑三条命令：

php artisan route:list --path=admin php artisan queue:work redis --once php artisan admin:update-extension

第一条命令用来验证 Dcat Admin 的路由有没有被正确加载，输出结果里应该能看到admin/dashboard、admin/auth/login等条目。第二条命令验证 Redis 队列能否正常消费一条任务，--once表示处理一条任务后立即退出，这个参数很适合部署后做冒烟测试，不会像queue:work那样一直挂在前台。第三条命令用来同步 Dcat Admin 扩展资源，静态文件变更时后台登录页会出现样式错乱，跑一遍基本能解决。

6.3 日志排查的顺序：从 laravel.log 到 failed_jobs 表

如果后台登录页总是 500，第一步不是改代码，而是打开storage/logs/laravel.log看最后 20 行。常见错误有两种：一种是数据库连接失败，错误信息里会出现SQLSTATE[HY000] [1045]这类字符串，直接把.env里的 DB 配置对一遍即可；另一种是扩展包版本冲突，通常是执行composer update之后产生的，此时按错误提示里的堆栈返回到对应 vendor 包版本。

队列任务错误看failed_jobs表比看 laravel.log 更直观，因为落库的异常信息里有完整的堆栈。快速定位：

SELECT id, queue, exception FROM failed_jobs ORDER BY id DESC LIMIT 5;

这条 SQL 能看到失败的队列名和异常信息字段。如果处理的是短信任务，重点看异常里有没有返回 code，比如“签名错误”是模板问题，而“欠费”则是账户问题，这两类修法完全不同。最后提醒一点：送水系统的实时配送状态不要直接查 orders 表的updated_at，把配送状态缓慢地写到 Redis 里，用 TTL 控制自动过期，这样后端压力小，配送员小程序也读得快。

本文还有配套的精品资源，点击获取