本文介绍在 Laravel 中将 users 与 roles 多对多关联查询（通过 user_role 中间表）的结果，从嵌套数组形式转换为“一个用户-一个角色”的扁平化对象列表，提供 Eloquent 链式处理与原生 SQL 两种高效实现方式。
本文介绍在 laravel 中将 `users` 与 `roles` 多对多关联查询（通过 `user_role` 中间表）的结果，从嵌套数组形式转换为“一个用户-一个角色”的扁平化对象列表，提供 eloquent 链式处理与原生 sql 两种高效实现方式。
在构建权限系统或用户角色导出接口时，常需将 Eloquent 的多对多关系（如 User::with('roles')）返回的嵌套结构——即每个用户携带一个 Collection 形式的 roles 属性——转换为更利于前端渲染、CSV 导出或数据分析的“一行一用户-角色组合”格式。此时，原始结构（每个用户对应多个角色子数组）不再适用，我们需要将其扁平化（flatten）：若某用户拥有 3 个角色，则生成 3 条独立记录，每条记录包含该用户全部字段 + 单一角色数据。
✅ 方案一：Eloquent + Collection flatMap()（推荐用于中等数据量）
利用 Laravel Collection 的 flatMap() 方法，在内存中对已加载的模型进行结构重组。关键在于：对每个用户，遍历其 roles 集合，克隆用户实例并注入单一角色对象，最终合并为一维集合：
use Illuminate\Support\Facades\DB;
$userRoleFlattened = \App\Models\User::with('roles')->get()->flatMap(function ($user) {
// 若用户无角色，保留原用户（可选：也可跳过，用 `->filter()` 清除）
if ($user->roles->isEmpty()) {
return $user;
}
return $user->roles->map(function ($role) use ($user) {
$newUser = $user->replicate(); // 更安全替代 clone：避免触发构造逻辑或丢失属性
$newUser->setAttribute('role', $role); // 将角色作为独立属性挂载
$newUser->setAttribute('role_id', $role->id);
$newUser->setAttribute('role_name', $role->name);
return $newUser;
});
});
⚠️ 注意事项：
replicate()比clone更可靠，它会重置主键、时间戳，并保留$casts和$appends等模型元信息；- 避免直接赋值
$newUser->roles = $role，因roles是关系方法，应使用新属性名（如role）避免冲突；- 此方案适合数据量 ≤ 5000 条（含关联），否则易触发内存溢出（OOM）。
✅ 方案二：原生 JOIN 查询（高性能首选，适用于大数据量）
绕过 Eloquent 关系加载，直接使用查询构造器进行三表联查，一次性获取扁平化结果，零内存膨胀：
$userRoleJoined = DB::table('users')
->join('user_role', 'user_role.user_id', '=', 'users.id')
->join('roles', 'user_role.role_id', '=', 'roles.id')
->select('users.*', 'roles.id as role_id', 'roles.name as role_name', 'roles.slug as role_slug')
->get();
该 SQL 等效于：
SELECT users.*, roles.id AS role_id, roles.name AS role_name, ... FROM users JOIN user_role ON user_role.user_id = users.id JOIN roles ON user_role.role_id = roles.id;
✅ 优势：
- 数据库层完成关联与扁平化，响应快、内存占用恒定；
- 可无缝配合
->cursorPaginate()实现海量数据分页；- 字段别名（如
roles.name as role_name）确保结果中无键名冲突，便于序列化。
? 总结建议
| 场景 | 推荐方案 | 原因 |
|---|---|---|
| 快速原型、小数据（ |
flatMap() + replicate()
|
开发简洁，保持 Eloquent 生态一致性 |
| API 接口、报表导出、后台管理列表（尤其 > 2k 记录） | 原生 DB::table()->join()
|
性能可控、无 N+1 风险、易于添加索引优化 |
| 需严格类型安全或 DTO 输出 | 在 JOIN 结果基础上映射至自定义 Resource 或 Data Transfer Object（DTO） | 解耦数据结构与业务逻辑 |
无论采用哪种方式，最终你都将获得一个 Illuminate\Support\Collection（或 Illuminate\Support\LazyCollection），其中每个元素都是一个独立对象，具备完整的用户字段与唯一角色信息，可直接 ->toArray()、->toJson() 或传递给前端渲染。
