在laravel应用开发中，构建灵活且强大的搜索功能是常见的需求。当搜索条件不仅限于模型自身的字段，还涉及到其关联模型的字段时，eloquent orm的查询构建方式需要特别注意。本文将详细阐述在处理多对多关联关系（如用户与部门、用户与角色）的复杂搜索时，如何正确使用eloquent进行高效查询。
理解 with() 与 whereHas()/orWhereHas() 的区别
在Laravel中，with() 方法用于进行预加载（Eager Loading），它的主要目的是在查询主模型的同时，加载其关联模型的数据，以避免N+1查询问题。然而，with() 内部的 where 子句仅用于过滤已加载的关联数据，并不会影响主模型（例如 User）的查询结果。
例如，以下代码：
$query = User::with([
'roles' => function($query) use($searchValues) {
return $query->where('title', 'LIKE','%'.$searchValues.'%');
},
'departments' => function($query) use($searchValues) {
return $query->where('title', 'LIKE','%'.$searchValues.'%');
}
])
->search($searchValues)
->orderBy($orderColumnName,$order)
->limit($request->length)
->get();这段代码的问题在于，with() 中的条件只会过滤预加载的 roles 和 departments 集合，而不会过滤 User 模型本身。这意味着即使某个用户的角色或部门标题不匹配搜索值，该用户记录仍然会被返回，只是其关联的角色或部门数据可能为空或不完整。如果我们的目标是根据关联模型的字段来筛选主模型记录，就需要使用 whereHas() 或 orWhereHas() 方法。
whereHas() 和 orWhereHas() 方法的用途是根据关联模型上的条件来过滤主模型。它们会生成 JOIN 或 EXISTS 子句，从而确保只有满足关联条件的父模型记录才会被检索。
orWhere 的逻辑分组与陷阱
在使用 orWhere 时，尤其是在结合 where 或其他复杂条件时，需要特别注意其逻辑分组。如果不进行显式的分组，orWhere 可能会导致意想不到的查询结果。Laravel 官方文档也强调了这一点：
"您应该始终对 orWhere 调用进行分组，以避免在应用全局作用域时出现意外行为。"
例如，一个查询 SELECT * FROM users WHERE (name = 'John' OR email = 'john@example.com') AND status = 'active' 与 SELECT * FROM users WHERE name = 'John' OR email = 'john@example.com' AND status = 'active' 是不同的。后者会因为运算符优先级而导致 email = 'john@example.com' AND status = 'active' 先被评估。
在本文的搜索场景中，我们希望根据用户自身的字段（first_name, last_name, email）以及其关联角色和部门的标题进行多条件模糊搜索。这意味着所有的搜索条件都应该是 OR 关系，共同作用于主查询。
解决方案：结合 orWhereHas 与局部作用域
为了实现既能根据用户自身字段搜索，又能根据关联关系字段搜索，并且所有条件都是 OR 关系，我们需要结合使用 orWhereHas 和局部作用域。
首先，我们定义一个 User 模型的局部作用域 scopeSearch，用于处理用户自身字段的模糊搜索：
// app/Models/User.php
class User extends Authenticatable
{
// ... 其他属性和方法
public function scopeSearch($query, $searchValues)
{
// 这里的 orWhere 都是针对当前查询的，所以不需要额外分组
return $query->where('first_name', 'like', '%' . $searchValues . '%')
->orWhere('last_name', 'like', '%' . $searchValues . '%')
->orWhere('email', 'like', '%' . $searchValues . '%');
}
public function departments()
{
return $this->belongsToMany(Department::class, 'users_departments', 'user_id', 'department_id');
}
public function roles()
{
return $this->belongsToMany(Role::class, 'users_roles', 'user_id', 'role_id');
}
}接下来，我们将 orWhereHas 应用到主查询中，并结合 search 作用域。为了代码的简洁性，我们可以将重复的闭包定义为一个变量。
// 在控制器或服务中
use App\Models\User;
use Illuminate\Http\Request;
public function getUsers(Request $request)
{
$searchValues = $request->input('search'); // 获取搜索值
$orderColumnName = $request->input('order_column', 'id'); // 排序字段
$order = $request->input('order_direction', 'asc'); // 排序方向
// 定义用于关联查询的闭包，避免重复代码
$relationshipSearchClosure = function ($query) use ($searchValues) {
return $query->where('title', 'LIKE', "%{$searchValues}%");
};
$users = User::with([
'roles' => $relationshipSearchClosure, // 预加载匹配的角色
'departments' => $relationshipSearchClosure // 预加载匹配的部门
])
->search($searchValues) // 搜索用户自身的字段
->orWhereHas('roles', $relationshipSearchClosure) // 或搜索关联的角色
->orWhereHas('departments', $relationshipSearchClosure) // 或搜索关联的部门
->orderBy($orderColumnName, $order)
->limit($request->length)
->get();
return response()->json($users);
}代码解析：
- $relationshipSearchClosure: 这是一个闭包变量，包含了对关联模型 title 字段进行模糊搜索的逻辑。这样做可以避免在 with()、orWhereHas('roles') 和 orWhereHas('departments') 中重复编写相同的条件。
- User::with(['roles' => $relationshipSearchClosure, 'departments' => $relationshipSearchClosure]): 这一部分负责预加载匹配 searchValues 的角色和部门数据。请注意，它仍然不会过滤 User 记录本身，只是确保如果 User 记录被返回，其关联数据中包含符合条件的部分。
- ->search($searchValues): 调用 User 模型中定义的 scopeSearch 局部作用域。这会为主查询添加 WHERE first_name LIKE ... OR last_name LIKE ... OR email LIKE ... 条件。
- ->orWhereHas('roles', $relationshipSearchClosure): 这是关键所在。它会为主查询添加一个 OR EXISTS 子句，检查是否存在至少一个与当前用户关联的角色，且该角色的 title 字段匹配 $searchValues。
- ->orWhereHas('departments', $relationshipSearchClosure): 同样，它为主查询添加另一个 OR EXISTS 子句，检查是否存在至少一个与当前用户关联的部门，且该部门的 title 字段匹配 $searchValues。
- ->orderBy($orderColumnName, $order)->limit($request->length)->get(): 最后的排序、限制和获取结果操作。
通过这种方式，我们构建了一个高效且逻辑正确的查询，它能够根据用户自身字段或其关联的角色/部门字段进行模糊搜索，并且所有条件都以 OR 关系连接。
总结与最佳实践
- 区分 with() 和 whereHas()/orWhereHas(): with() 用于预加载数据，不影响主查询的过滤；whereHas()/orWhereHas() 用于根据关联模型的条件过滤主模型。
- 正确使用 orWhere 逻辑分组: 当在同一个查询中混合使用 where 和 orWhere 时，务必使用闭包对 orWhere 条件进行分组，以避免优先级问题和意外的查询结果。在本文的例子中，由于 search 作用域内部的 orWhere 仅针对自身字段，且 orWhereHas 是在顶层与 search 作用域并行，所以它们之间是自然的 OR 关系，无需额外的分组。
- 利用局部作用域: 将复杂的查询逻辑封装到局部作用域中，可以提高代码的可读性、复用性和维护性。
- 考虑数据库性能: 对于大规模数据和频繁的模糊查询，确保相关字段（如 first_name, last_name, email, roles.title, departments.title）上建立了合适的数据库索引，以优化查询性能。
- 调试查询: 在遇到问题时，可以使用 toSql() 和 getBindings() 方法来查看 Eloquent 生成的 SQL 语句和绑定值，这对于调试复杂的查询非常有帮助。
遵循这些原则，您将能够更有效地在 Laravel 应用中构建健壮且高性能的复杂搜索功能。
