Laravel 10 + Spatie Permission 实战：从零搭建企业级RBAC权限管理系统（附完整代码示例）

本文详细讲解如何在Laravel 10框架中集成Spatie Laravel Permission库，构建一套标准的RBAC（基于角色的访问控制）权限管理系统。内容涵盖Composer依赖安装、数据库迁移、角色与权限的增删改查、中间件防护、Blade模板指令集成以及常见缓存问题处理。通过本教程，可快速实现用户、角色、权限的关联管理，适用于后台管理系统的权限控制场景。

环境准备与依赖安装

确保系统已安装Laravel 10及MySQL/PostgreSQL数据库。通过Composer安装Spatie Permission扩展包：

composer require spatie/laravel-permission

发布迁移文件与配置文件：

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="migrations"
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="config"

执行数据库迁移，系统将自动创建roles、permissions、model_has_roles、model_has_permissions、role_has_permissions五张核心表：

php artisan migrate

模型配置

在User模型中引入HasRoles trait，使其具备角色与权限管理能力：

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;

    // 其他模型代码...
}

角色与权限的创建

通过Tinker或控制器创建基础权限与角色。以下为控制器示例：

use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;

// 创建权限
$permission = Permission::create(['name' => 'edit articles']);
$permission = Permission::create(['name' => 'delete articles']);

// 创建角色并分配权限
$role = Role::create(['name' => 'writer']);
$role->givePermissionTo('edit articles');

$role = Role::create(['name' => 'admin']);
$role->givePermissionTo(['edit articles', 'delete articles']);

用户角色与权限分配

为用户分配角色或权限，支持直接分配或通过角色继承：

use App\Models\User;

$user = User::find(1);

// 分配角色
$user->assignRole('writer');

// 分配多个角色
$user->assignRole(['writer', 'admin']);

// 直接分配权限（无需通过角色）
$user->givePermissionTo('delete articles');

权限校验与中间件应用

1. 路由中间件防护

在app/Http/Kernel.php中注册中间件（新版本Laravel通常已自动注册）：

protected $routeMiddleware = [
    // ...
    'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
    'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
];

在路由中使用中间件限制访问：

// 仅允许admin角色访问
Route::group(['middleware' => ['role:admin']], function () {
    Route::get('/admin/dashboard', [AdminController::class, 'index']);
});

// 需要特定权限
Route::get('/articles/delete', [ArticleController::class, 'delete'])
    ->middleware('permission:delete articles');

2. 代码层权限判断

在控制器或Blade模板中进行权限校验：

控制器示例：

if ($user->can('edit articles')) {
    // 执行编辑逻辑
}

if ($user->hasRole('admin')) {
    // 管理员逻辑
}

Blade模板示例：

@can('edit articles')
    <a href="/articles/1/edit">编辑文章</a>
@endcan

@role('admin')
    <a href="/admin/settings">系统设置</a>
@endrole

Blade指令扩展

Spatie提供了便捷的Blade指令，简化前端权限控制：

{{-- 检查是否有任一权限 --}}
@hasanyrole('writer|admin')
    欢迎编辑或管理内容
@endhasanyrole

{{-- 检查是否有全部权限 --}}
@hasallroles('writer|admin')
    具备全部权限
@endhasallroles

多守卫（Guard）支持

在多认证系统（如前后端分离）场景下，可配置不同守卫。在config/auth.php中定义守卫后，创建角色时指定守卫：

$role = Role::create(['name' => 'editor', 'guard_name' => 'api']);

查询时指定守卫：

$user->hasPermissionTo('edit articles', 'api');

缓存管理

Spatie Permission默认使用缓存提升性能。在角色或权限变更后，需清除缓存：

use Spatie\Permission\PermissionRegistrar;

app()[PermissionRegistrar::class]->forgetCachedPermissions();

建议在权限管理模块的增删改操作后自动调用此方法，避免权限更新延迟。

数据表结构说明

核心表结构如下：

roles：存储角色信息（id, name, guard_name）
permissions：存储权限信息（id, name, guard_name）
model_has_roles：用户与角色关联表（model_id, model_type, role_id）
model_has_permissions：用户与权限关联表（model_id, model_type, permission_id）
role_has_permissions：角色与权限关联表（role_id, permission_id）

最佳实践建议

权限命名规范：采用动作+资源格式，如create users、edit articles，便于批量管理。
角色层级设计：避免角色交叉过多，推荐“用户→角色→权限”的单向关联。
缓存优化：生产环境保持缓存开启，仅在权限变更时清除缓存。
测试覆盖：编写单元测试验证权限逻辑，确保权限控制无遗漏。

通过以上步骤，可快速构建一套稳定、可扩展的RBAC权限系统。Spatie Permission的灵活设计支持复杂权限场景，结合Laravel的中间件与Blade指令，能高效实现企业级权限管理需求。