用Laravel实现管理后台批量修改角色权限,如何通过事务避免部分更新?
在管理后台一次选中“编辑”和“运营”两个角色,把权限勾选为“订单查看、订单导出、报表查看”后,页面看起来只是提交了一次表单,数据库实际却要修改两组角色与权限的关联数据。如果第一个角色已经更新成功,第二个角色在写入时因为数据约束、数据库连接或并发锁发生异常,而代码没有使用统一事务,后台就会出现“页面提示失败,但部分角色已经被修改”的状态。
要避免这种情况,批量操作不能只依赖前端按钮状态,也不能认为 Eloquent 的 sync() 会自动覆盖整个批次。正确做法是先明确提交数据代表的最终状态,再把角色校验、权限校验、关联表更新、审计记录等数据库操作放入同一个事务中。事务回调中的任何异常都必须继续抛出,让 Laravel 自动回滚。
先明确批量修改的语义
批量修改角色权限通常有两种业务含义。
第一种是“覆盖为当前勾选结果”。管理员选中多个角色,并提交一组权限,表示这些角色最终都只能拥有这组权限。请求可以设计为:
{
"role_ids": [2, 5],
"permission_ids": [3, 7, 9]
}
这表示角色 2 和角色 5 的权限最终都应为 3、7、9。原来存在但不在这次提交中的权限需要被移除,数据库中缺少的权限需要被补充。
第二种是“增量修改”。例如请求只表示增加权限 9,或者只移除权限 3。这种接口需要额外传递操作类型:
{
"role_ids": [2, 5],
"permission_ids": [9],
"operation": "attach"
}
如果管理后台是完整的复选框列表,通常更适合使用第一种“最终状态覆盖”模式。因为服务端可以把一次请求当作完整快照处理,重复提交同一份数据不会不断产生新的关联记录,也更容易实现幂等。
本文使用“覆盖为最终权限集合”的方式。空数组也有明确含义:
{
"role_ids": [2],
"permission_ids": []
}
这表示清空角色 2 的所有权限,而不是“没有提交权限字段”。
数据表必须提供数据库级约束
假设项目使用 roles、permissions 和 permission_role 三张表。角色与权限的中间表至少应包含以下约束:
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
Schema::create('permission_role', function (Blueprint $table) {
$table->foreignId('role_id')
->constrained('roles')
->cascadeOnDelete();
$table->foreignId('permission_id')
->constrained('permissions')
->cascadeOnDelete();
$table->primary(['role_id', 'permission_id']);
});
}
public function down(): void
{
Schema::dropIfExists('permission_role');
}
};
联合主键有两个作用:
- 防止同一个角色与同一个权限出现重复关联;
- 让
sync()的删除和插入操作有明确的数据约束。
如果项目已有中间表,不能直接重复创建这张表,而要确认实际表名和字段名。例如有些项目使用 role_permission,权限管理扩展包可能使用 role_has_permissions。模型中的关联表名必须与现有数据库一致。
角色模型和权限模型可以这样定义关联:
namespace App\Models;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Foundation\Auth\User as Authenticatable;
class Role extends Authenticatable
{
public function permissions(): BelongsToMany
{
return $this->belongsToMany(
Permission::class,
'permission_role',
'role_id',
'permission_id'
);
}
}
如果 Role 不是认证模型,应根据项目实际情况继承 Model。关键不是继承关系,而是 permissions() 使用了正确的中间表和外键。
数据库引擎也会影响事务结果。MySQL 项目应确认相关表使用 InnoDB,而不是不支持事务回滚的存储引擎。只读检查可以使用:
SHOW TABLE STATUS LIKE 'permission_role';
检查结果中的 Engine 应与项目的事务要求相符。PostgreSQL 的普通表默认支持事务,但仍需要确认中间表没有使用特殊的非事务实现。
先在请求层校验输入
请求校验应尽量在开启事务前完成。这样可以避免明显无效的请求进入数据库写入流程,同时也能让接口返回清晰的 422 错误。
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
class BatchRolePermissionRequest extends FormRequest
{
public function authorize(): bool
{
return $this->user()?->can('manage-role-permissions') ?? false;
}
public function rules(): array
{
return [
'role_ids' => [
'required',
'array',
'min:1',
],
'role_ids.*' => [
'integer',
'distinct',
'exists:roles,id',
],
// present 表示字段必须存在,但允许传空数组
'permission_ids' => [
'present',
'array',
],
'permission_ids.*' => [
'integer',
'distinct',
'exists:permissions,id',
],
];
}
}
exists 只能说明记录存在,不能说明当前操作员有权把某个权限授予某个角色。例如系统可能规定:
- 普通管理员不能修改超级管理员角色;
- 普通管理员不能授予“用户删除”权限;
- 某些权限只能由平台管理员配置。
这些规则需要通过 Gate、Policy 或服务层的业务判断完成,不能只依靠 exists。
路由可以将权限控制放在中间件或 Form Request 中:
use App\Http\Controllers\Admin\BatchRolePermissionController;
use Illuminate\Support\Facades\Route;
Route::put(
'/admin/role-permissions/batch',
[BatchRolePermissionController::class, 'update']
)->middleware('auth');
如果项目已有管理后台权限中间件,也可以将实际的权限名称放在路由中,避免在多个位置重复配置。
用事务包住整个批次
事务的边界应覆盖所有角色的关联更新,而不是只包住其中一次 sync()。
下面的服务类使用 Laravel 10、11 中通用的事务写法,示例假定项目使用 PHP 8.1 及以上版本:
namespace App\Services;
use App\Models\Permission;
use App\Models\Role;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;
use Illuminate\Validation\ValidationException;
class RolePermissionBatchService
{
public function replace(
array $rawRoleIds,
array $rawPermissionIds
): string {
$roleIds = collect($rawRoleIds)
->map(static fn ($id): int => (int) $id)
->unique()
->sort()
->values();
$permissionIds = collect($rawPermissionIds)
->map(static fn ($id): int => (int) $id)
->unique()
->sort()
->values();
if ($roleIds->isEmpty()) {
throw ValidationException::withMessages([
'role_ids' => '至少选择一个角色。',
]);
}
$operationId = (string) Str::uuid();
DB::transaction(function () use (
$roleIds,
$permissionIds
): void {
/*
* exists 规则在事务外执行过一次。
* 这里再次读取并加锁,避免校验后到写入前发生并发变化。
*/
$permissionRows = $permissionIds->isEmpty()
? collect()
: Permission::query()
->whereIn('id', $permissionIds->all())
->orderBy('id')
->lockForUpdate()
->get(['id']);
if ($permissionRows->count() !== $permissionIds->count()) {
throw ValidationException::withMessages([
'permission_ids' => '部分权限已经不存在或不可用。',
]);
}
$roles = Role::query()
->whereIn('id', $roleIds->all())
->orderBy('id')
->lockForUpdate()
->get();
if ($roles->count() !== $roleIds->count()) {
throw ValidationException::withMessages([
'role_ids' => '部分角色已经不存在或不可用。',
]);
}
foreach ($roles as $role) {
/*
* sync 表示将关联关系替换为最终集合:
* 不在 permissionIds 中的记录会被删除,
* permissionIds 中缺少的记录会被插入。
*/
$role->permissions()->sync($permissionIds->all());
}
}, 3);
return $operationId;
}
}
这里的第二个参数 3 表示事务遇到可重试的并发死锁时,Laravel 最多尝试执行三次。它不是所有异常的通用重试开关,业务校验失败、外键错误和代码异常仍然应该直接失败。
控制器负责读取已经验证过的数据,并在服务方法成功返回后响应:
namespace App\Http\Controllers\Admin;
use App\Http\Controllers\Controller;
use App\Http\Requests\BatchRolePermissionRequest;
use App\Services\RolePermissionBatchService;
use Illuminate\Http\JsonResponse;
class BatchRolePermissionController extends Controller
{
public function update(
BatchRolePermissionRequest $request,
RolePermissionBatchService $service
): JsonResponse {
$data = $request->validated();
$operationId = $service->replace(
$data['role_ids'],
$data['permission_ids']
);
return response()->json([
'operation_id' => $operationId,
'updated_roles' => count($data['role_ids']),
'permission_count' => count($data['permission_ids']),
]);
}
}
如果事务回调中的任何数据库操作抛出异常,DB::transaction() 会执行回滚,异常继续向外抛出,由 Laravel 的异常处理器转换为对应的 HTTP 响应。
角色权限后台的事务逻辑运行在应用与数据库所在的基础环境中。A5数据提供香港、美国、日本等地区的物理服务器,覆盖不同CPU、内存、SSD或NVMe存储及网络线路配置,可作为Laravel管理后台、接口服务与数据库部署的硬件资源选择。业务部署可结合访问区域、数据规模和应用负载组织相应的计算、存储与网络资源。
为什么必须使用外层事务
sync() 解决的是一个角色与多个权限之间的关系同步,不代表多个角色之间已经具备原子性。
假设没有外层事务,代码如下:
foreach ($roles as $role) {
$role->permissions()->sync($permissionIds);
}
可能发生这样的顺序:
- 角色 2 的旧权限被删除;
- 角色 2 的新权限写入成功;
- 角色 5 的旧权限被删除;
- 角色 5 写入时出现数据库异常;
- 代码返回失败,但角色 2 已经发生变化,角色 5 可能处于空权限或半更新状态。
而在事务中,数据库看到的是一个整体:

- 开启事务;
- 锁定本次涉及的角色;
- 更新角色 2;
- 更新角色 5;
- 全部成功后提交;
- 任一步骤抛出异常则回滚全部修改。
事务不仅能处理“第二个角色失败”,也能处理单个 sync() 内部的中途失败。因为 sync() 可能先删除不需要的关联,再插入新的关联,如果它不在外层事务中,单个角色的关系更新也可能出现不完整状态。
需要特别避免吞掉异常:
DB::transaction(function () use ($roles, $permissionIds): void {
foreach ($roles as $role) {
try {
$role->permissions()->sync($permissionIds);
} catch (\Throwable $exception) {
report($exception);
// 错误做法:记录后不再抛出
}
}
});
如果异常被捕获后没有重新抛出,事务闭包可能正常结束,Laravel 会认为事务可以提交。正确处理方式是记录后继续抛出:
DB::transaction(function () use ($roles, $permissionIds): void {
foreach ($roles as $role) {
try {
$role->permissions()->sync($permissionIds);
} catch (\Throwable $exception) {
report($exception);
throw $exception;
}
}
});
实际项目中,如果没有特殊的错误转换需求,可以不在服务层捕获异常,直接让事务自动回滚,并交给全局异常处理器记录日志和返回响应。
使用行锁处理并发修改
事务解决的是一批操作的原子性,不能自动决定两个管理员同时提交不同权限集合时谁应该生效。
例如管理员甲打开角色 2 的权限页面时看到的是:
角色 2:权限 3、7
管理员乙随后打开同一个页面并增加权限 9,提交集合:
权限 3、7、9
管理员甲没有刷新页面,又取消权限 7,提交集合:
权限 3
如果两次操作都成功,最终状态通常由最后提交的事务决定。lockForUpdate() 会让两个事务按顺序执行,避免两个事务同时修改同一角色造成关联表竞争,但它不会自动识别“第二个页面是旧数据”。
服务类中的这段代码用于锁定本次涉及的角色:
$roles = Role::query()
->whereIn('id', $roleIds->all())
->orderBy('id')
->lockForUpdate()
->get();
这里有两个细节。
第一,查询必须在事务中执行。脱离事务使用 lockForUpdate(),锁的有效时间和实际效果都无法达到预期。
第二,角色 ID 使用固定顺序排序。两个批次同时修改角色 2 和角色 5 时,如果一个事务按 [2, 5] 加锁,另一个按 [5, 2] 加锁,就可能形成互相等待。固定加锁顺序能够降低死锁概率,事务重试则用于处理仍然可能出现的数据库级死锁。
如果业务不允许旧页面覆盖新修改,可以在 roles 表增加版本字段,例如:
$table->unsignedInteger('permission_version')->default(0);
页面读取角色权限时同时返回版本号,提交时携带:
{
"role_ids": [2],
"permission_ids": [3, 9],
"versions": {
"2": 4
}
}
服务层锁定角色后比较数据库中的版本号:

$expectedVersion = (int) ($versions[(string) $role->id] ?? -1);
if ((int) $role->permission_version !== $expectedVersion) {
throw new ConflictHttpException(
"角色 {$role->id} 已被其他操作修改,请刷新后重试。"
);
}
全部修改成功后再递增版本:
$role->increment('permission_version');
这样可以将“最后一次提交覆盖前一次提交”改为“检测到页面过期后拒绝提交”。是否需要这种机制,取决于后台是否允许最后写入者覆盖前一个管理员的操作。
将审计记录放在同一个事务中
角色权限属于敏感的管理数据,通常需要记录谁在什么时候修改了哪些角色和权限。审计记录如果在事务外写入,可能出现两种不一致:
- 权限修改回滚了,但审计日志显示修改成功;
- 权限修改已经提交,但审计记录写入失败。
如果审计记录是数据库表,建议把它和关联表更新放在同一个事务中:
DB::transaction(function () use (
$roleIds,
$permissionIds,
$operatorId,
$operationId
): void {
// 查询并锁定角色、权限
// 执行每个角色的 sync
RolePermissionOperation::create([
'id' => $operationId,
'operator_id' => $operatorId,
'role_ids' => $roleIds->all(),
'permission_ids' => $permissionIds->all(),
'operation' => 'replace',
]);
});
对应模型需要将 JSON 字段转换为数组:
class RolePermissionOperation extends Model
{
public $incrementing = false;
protected $keyType = 'string';
protected $casts = [
'role_ids' => 'array',
'permission_ids' => 'array',
];
protected $fillable = [
'id',
'operator_id',
'role_ids',
'permission_ids',
'operation',
];
}
如果审计记录写入失败,就让异常继续抛出,使权限更新也回滚。审计表如果只用于调试而不是合规记录,也可以使用应用日志,但要注意日志不受数据库事务控制,不能把日志当成事务的一部分。
队列、缓存和事务提交的先后关系
数据库事务提交前,不应向外部系统发送“权限已经修改”的通知,也不应让队列任务立即读取最终权限。
错误的处理方式是:
DB::transaction(function () use ($roleIds, $permissionIds): void {
// 修改角色权限
RefreshPermissionCache::dispatch();
});
如果队列连接配置为立即发送,队列消费者可能在事务提交前运行。消费者读取到的可能是旧数据,也可能因为使用了其他数据库连接而无法看到当前事务中的未提交数据。
可以使用 Laravel 队列的提交后派发能力:

DB::transaction(function () use (
$roleIds,
$permissionIds,
$operationId
): void {
foreach ($roleIds as $roleId) {
$role = Role::query()
->whereKey($roleId)
->lockForUpdate()
->firstOrFail();
$role->permissions()->sync($permissionIds->all());
}
RefreshPermissionCache::dispatch($operationId)
->afterCommit();
});
afterCommit() 的作用是让任务等待当前事务成功提交后再进入队列。如果事务回滚,任务不会按“成功修改”的状态执行。
如果缓存刷新失败,而数据库已经成功提交,缓存与数据库仍可能短时间不一致。对权限数据要求更高时,可以在事务中写入一条 outbox 记录,事务提交后由后台任务反复投递和处理。这样“需要发送的事件”本身和权限修改一起提交,任务执行失败时可以重试,而不是依赖一次普通的队列调用。
缓存清理也不应该被当成数据库回滚的一部分。以权限扩展包为例,如果项目使用 Spatie Laravel Permission,推荐在事务中使用扩展包提供的关系方法,并确认其缓存清理行为与当前版本相容。若直接操作扩展包的中间表,则应在事务成功后清理权限缓存,而不是在写入中途清理:
DB::transaction(function () use ($roles, $permissionIds): void {
foreach ($roles as $role) {
$role->permissions()->sync($permissionIds->all());
}
});
app(\Spatie\Permission\PermissionRegistrar::class)
->forgetCachedPermissions();
使用扩展包模型时,关系表和方法名称必须以项目安装版本为准。典型的角色模型可以使用:
DB::transaction(function () use ($roles, $permissionIds): void {
foreach ($roles as $role) {
$role->syncPermissions(...$permissionIds->all());
}
});
如果需要清空权限,必须确认当前版本对空参数的处理方式;不确定时,应先查阅项目已安装版本的接口定义,或者使用扩展包关系方法明确执行清空操作。不要把自定义 permissions() 关系和扩展包的 syncPermissions() 混用,否则可能绕过缓存、事件或模型约束。
每个角色拥有不同权限时的处理方式
如果批量操作不是给多个角色设置同一组权限,而是一次提交多个角色各自的最终权限,可以将请求改成:
{
"roles": [
{
"id": 2,
"permission_ids": [3, 7]
},
{
"id": 5,
"permission_ids": []
}
]
}
请求规则可以写成:
public function rules(): array
{
return [
'roles' => ['required', 'array', 'min:1'],
'roles.*.id' => [
'required',
'integer',
'distinct',
'exists:roles,id',
],
'roles.*.permission_ids' => [
'present',
'array',
],
'roles.*.permission_ids.*' => [
'integer',
'distinct',
'exists:permissions,id',
],
];
}
服务层先整理成“角色 ID对应权限集合”的映射,再一次性锁定全部角色:
$desiredPermissions = collect($data['roles'])
->mapWithKeys(function (array $item): array {
$permissionIds = collect($item['permission_ids'])
->map(static fn ($id): int => (int) $id)
->unique()
->sort()
->values()
->all();
return [(int) $item['id'] => $permissionIds];
});
$roleIds = $desiredPermissions
->keys()
->map(static fn ($id): int => (int) $id)
->sort()
->values();
DB::transaction(function () use (
$roleIds,
$desiredPermissions
): void {
$roles = Role::query()
->whereIn('id', $roleIds->all())
->orderBy('id')
->lockForUpdate()
->get();
if ($roles->count() !== $roleIds->count()) {
throw ValidationException::withMessages([
'roles' => '部分角色不存在。',
]);
}
foreach ($roles as $role) {
$permissions = $desiredPermissions->get($role->id, []);
$role->permissions()->sync($permissions);
}
});
这个版本仍然是一个事务。角色 2 的同步成功、角色 5 的同步失败时,两者都会回滚。不同之处只是每个角色使用的最终权限集合不再相同。
正常结果和异常分支
接口可以使用统一的 JSON 响应,例如成功时返回:
{
"operation_id": "7d0d5f82-2d3a-4f1d-9f9f-4f66c8fd5e72",
"updated_roles": 2,
"permission_count": 3
}
不同分支的数据库结果应保持清晰:
| 处理分支 | 数据库结果 | 建议响应 |
|---|---|---|
| 请求字段缺失或 ID 格式错误 | 未开启写入或事务尚未产生修改 | 422 |
| 角色或权限在校验后被删除 | 事务回滚,批次不变 | 409 或 422 |
| 中间表外键、唯一键或连接异常 | 全部回滚 | 500 或 503 |
| 数据库发生可重试死锁 | Laravel 重新执行事务,最终成功或失败 | 成功或 503 |
| 全部更新和审计记录成功 | 事务提交,所有角色达到最终状态 | 200 |
| 提交后缓存任务失败 | 数据库已提交,任务应重试 | 200,记录任务失败 |
不要在服务层捕获数据库异常后直接返回“更新失败”而不抛出。如果需要把异常转换为 409 或 503,应先保证事务已经回滚,再由异常处理层统一处理。
用数据库状态验证结果
提交成功后,管理页面可以重新请求角色权限,而不是只根据前端复选框状态显示“成功”。以角色 2 和角色 5 都设置为权限 3、7、9 为例,可以使用只读查询检查:

SELECT role_id, permission_id
FROM permission_role
WHERE role_id IN (2, 5)
ORDER BY role_id, permission_id;
预期结果应包含六条关联记录:
role_id | permission_id
--------+--------------
2 | 3
2 | 7
2 | 9
5 | 3
5 | 7
5 | 9
也可以通过 Laravel Tinker 查看:
Role::query()
->with('permissions:id')
->whereIn('id', [2, 5])
->orderBy('id')
->get()
->mapWithKeys(function (Role $role) {
return [
$role->id => $role->permissions
->pluck('id')
->sort()
->values()
->all(),
];
})
->all();
验证时应特别检查空权限场景。请求角色 2 的 permission_ids 为 [] 后,查询结果应该没有角色 2 的关联记录,而不是保留旧权限。
测试必须覆盖真正的回滚场景
只测试“所有角色都更新成功”不能证明事务有效,还需要制造一个发生在事务中间的异常。
建议至少覆盖以下场景:
- 两个角色提交同一组权限,检查两者都达到最终集合。
permission_ids为空,检查旧关联全部删除。- 请求包含不存在的角色或权限,检查数据库没有任何变更。
- 第一个角色更新后,第二个角色触发业务异常,检查第一个角色也恢复到事务前状态。
- 两个请求同时修改同一角色,检查没有重复中间表记录。
- 队列或缓存任务只能在事务提交后运行。
- 旧页面携带过期版本号时,检查服务端拒绝覆盖新数据。
回滚测试可以通过测试替身在循环中间抛出异常,也可以通过一个仅用于测试的领域校验触发异常。关键断言不是接口返回了错误,而是确认事务前的关联数据仍然存在,且没有留下第一步已经写入的记录。
如果生产环境使用 MySQL 或 PostgreSQL,集成测试最好使用相同类型的数据库。SQLite 内存数据库便于执行快速测试,但它的锁行为、外键配置和并发特性与生产数据库不完全相同,不能仅凭 SQLite 测试结果判断生产环境的并发事务行为。
大批量数据不应随意拆成多个事务
当一次修改几十个角色、每个角色关联几十个权限时,单个事务通常比较容易理解和维护。事务持续时间主要取决于查询数量、锁竞争和中间表写入量,而不是简单归因于服务器配置。
如果批量规模扩大到数千个角色,继续在一个 HTTP 请求中长时间持有大量行锁,可能导致:
- 其他权限修改请求等待;
- 数据库死锁概率增加;
- PHP 请求超时,但数据库事务仍在回滚;
- 队列和后台操作积压。
这时有两种不同方向:
- 如果业务要求“全部成功或全部失败”,应保留一个事务,并优化查询、锁顺序和批量写入方式;
- 如果业务允许最终一致,则可以建立批次任务表,先保存待处理状态,再由队列分段处理,并记录每个角色的处理结果。
分成多个队列任务后,原本的全有或全无语义就不存在了。此时接口必须明确显示“处理中”“部分完成”或“失败待重试”,不能继续返回一个看起来像全部完成的成功状态。
上线前,把事务边界落实到每条写入路径
完成接入后,可以按下面的顺序检查:
- 前端提交的是最终权限集合,还是增量操作,接口字段含义必须固定;
- 空数组是否明确表示清空;
- 所有角色 ID 和权限 ID 是否经过服务端校验;
- 当前操作员是否有权修改目标角色并授予目标权限;
- 角色、权限和中间表是否使用支持事务的数据库引擎;
- 所有角色是否在同一个事务中更新;
- 批量锁是否使用稳定的 ID 顺序;
- 事务回调中是否存在吞掉异常的
try...catch; - 审计记录是否与权限写入使用同一个事务;
- 队列、事件和缓存刷新是否在提交后执行;
- 页面成功后是否重新读取数据库状态;
- 是否测试了第二个角色失败时第一个角色也回滚的场景。
这样处理后,批量修改的结果就不再依赖循环执行到哪一步,也不依赖页面是否及时刷新。数据库要么一次性接受完整的权限集合,要么保留事务开始前的状态,后台显示的操作结果也能与实际数据保持一致。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9999.html



