Spatie Laravel Permission 多守卫系统使用指南

Spatie Laravel Permission 多守卫系统使用指南

laravel-permission Associate users with roles and permissions 项目地址: https://gitcode.com/gh_mirrors/la/laravel-permission

多守卫系统概述

在 Laravel 权限管理系统中，守卫(Guard)是一个核心概念。默认情况下，当使用 Laravel 的标准认证配置时，Spatie Laravel Permission 包的所有核心功能都可以开箱即用，无需额外配置。

但当应用需要同时使用多个守卫时，这些守卫会为权限和角色创建独立的"命名空间"——每个守卫都有自己独立的权限和角色集合，这些权限和角色只能分配给该守卫对应的用户模型。

多守卫系统的局限性

使用多守卫系统时需要注意一个关键限制：必须为每个守卫单独注册相同的权限名称（角色同理）。例如，"edit-article"权限需要为应用使用的每个守卫分别创建一次。如果尝试使用不存在的权限+守卫组合进行认证，系统会抛出异常。

单守卫系统优化方案

如果应用结构不需要区分不同守卫的权限/角色（即所有守卫使用相同的权限/角色集合），可以通过以下方式强制使用单一守卫：

在用户模型中重写 getDefaultGuardName 方法，并指定 $guard_name 属性。这样只需为该守卫创建一次角色/权限，无需重复创建。

protected string $guard_name = 'web';

protected function getDefaultGuardName(): string 
{
    return $this->guard_name; 
}

最佳实践建议：

1. 如果应用只使用一个守卫（非默认的web守卫），建议调整 config/auth.php 中守卫的顺序，将主要守卫设为默认并放在首位
2. 删除配置文件中未使用的守卫定义，保持配置简洁

多守卫下的权限和角色管理

创建新权限和角色时，如果未指定守卫，系统会使用 auth.guards 配置数组中定义的第一个守卫。

// 为admin守卫创建manager角色
$role = Role::create(['guard_name' => 'admin', 'name' => 'manager']);

// 为admin守卫的用户定义"publish articles"权限
$permission = Permission::create(['guard_name' => 'admin', 'name' => 'publish articles']);

// 为web守卫的用户定义不同的"publish articles"权限
$permission = Permission::create(['guard_name' => 'web', 'name' => 'publish articles']);

检查用户是否拥有特定守卫的权限：

$user->hasPermissionTo('publish articles', 'admin');

权限验证机制详解

当系统验证模型是否具有某个角色/权限时，会按照以下顺序检查守卫匹配（只会检查第一个匹配项，不会检查所有可能性）：

1. 首先检查模型上的 guardName() 方法（可返回字符串或数组）
2. 然后检查模型上的 $guard_name 属性（可返回字符串或数组）
3. 接着检查 auth.guards 配置中与加载模型守卫匹配的第一个守卫/提供者组合
4. 最后检查 auth.defaults.guard 配置（如果用户已登录则为用户守卫，否则为配置文件中的默认守卫）

多守卫下的权限分配

可以使用相同的核心方法为用户分配权限和角色，但需确保权限或角色的 guard_name 与用户的守卫匹配，否则会抛出 GuardDoesNotMatch 或 Role/PermissionDoesNotExist 异常。

如果用户需要使用来自不同守卫的多个角色或权限，可以在用户类的 $guard_name 属性或 guardName() 方法中返回所有允许的守卫数组：

protected $guard_name = ['web', 'admin'];

或

public function guardName() 
{
    return ['web', 'admin']; 
}

Blade模板指令的多守卫支持

所有Blade指令都支持通过第二个参数指定要使用的守卫：

@role('super-admin', 'admin')
    我是超级管理员!
@else
    我不是超级管理员...
@endrole

最佳实践总结

1. 简化守卫配置：如果不需要多守卫功能，尽量简化配置，使用单一守卫系统
2. 命名一致性：即使不同守卫使用相同权限名称，也应视为完全独立的权限实体
3. 守卫匹配验证：分配权限/角色前，务必验证守卫匹配性
4. 性能考虑：多守卫系统会增加数据库存储和查询开销，需合理设计

通过合理利用Spatie Laravel Permission包的多守卫功能，可以构建灵活、安全的权限管理系统，满足复杂应用场景的需求。

laravel-permission Associate users with roles and permissions 项目地址: https://gitcode.com/gh_mirrors/la/laravel-permission