本文详细介绍了在 laravel 8 中如何利用查询构建器（query builder）或 eloquent orm 实现基于 url 查询参数的动态搜索与过滤功能。重点阐述了 `when` 方法的用法，通过条件判断优雅地向查询中添加 `where` 子句，从而避免了冗余代码，提升了代码的可读性和维护性，是处理可选搜索条件的推荐实践。
在开发 Web 应用时，基于用户输入的查询参数实现动态搜索和过滤功能是常见的需求。例如，一个管理系统可能需要根据 URL 中的 q (搜索关键词) 或 gender (性别) 参数来过滤用户列表。在 Laravel 中，优雅地处理这类可选的查询条件，是提升代码质量的关键。
动态查询条件的挑战
当我们需要根据 URL 查询字符串（如 http://127.0.0.1:8000/admin/users/supervisor?q=john&gender=m）来动态构建数据库查询时，一个常见的误区是直接将所有可能的 where 子句链式调用，而不考虑参数是否存在。
例如，以下代码在 q 或 gender 参数不存在时，会导致查询错误或行为异常：
// 潜在问题代码示例
$roles = Role::where('role', '=', $role)
->where('name', 'like', "%$request->$q%") // 如果 $request->q 不存在，会出错
->where('gender', '=', $request->gender) // 如果 $request->gender 不存在，会出错
->orderBy('id', 'desc')
->paginate(20);其根本原因在于，当 $request->q 或 $request->gender 不存在时，它们的值可能为 null，导致 where 子句的条件不正确或抛出异常。为了解决这个问题，一种直观的方法是使用 if 语句进行条件判断：
// 使用 if 语句实现条件查询
public function index (Request $request)
{
$role = getRoleCode($request->role);
$rolesQuery = Role::where('role', '=', $role); // 初始化查询构建器
if ($request->has('q')) { // 使用 has() 方法检查参数是否存在
$rolesQuery->where('name', 'like', '%'. $request->input('q') .'%'); // 使用 input() 安全获取参数
}
if ($request->has('gender')) {
$rolesQuery->where('gender', '=', $request->input('gender'));
}
$roles = $rolesQuery->orderBy('id', 'desc')->paginate(20);
return view('admin.users.index', [
'roles' => $roles,
// ... 其他视图数据
]);
}这种方法是有效的，但当条件增多时，代码会显得冗长且链式调用的流畅性被中断。
Laravel when 方法：优雅的条件查询
Laravel 的查询构建器和 Eloquent ORM 提供了一个更优雅的解决方案：when 方法。when 方法允许你根据一个布尔条件来决定是否执行某个查询子句，从而使代码更加简洁和富有表现力。
when 方法的签名如下：
->when(mixed $condition, callable $callback, callable $defaultCallback = null)
- $condition: 这是一个混合类型的值。如果它评估为 true（或非空、非零），则会执行 $callback。如果它评估为 false（或空、零），则如果提供了 $defaultCallback，则执行 $defaultCallback。
- $callback: 这是一个闭包函数，它接收当前的查询构建器实例作为第一个参数，以及 $condition 的值（如果 $condition 不是布尔值）作为第二个参数。
- $defaultCallback: （可选）当 $condition 为 false 时执行的闭包函数。
使用 when 方法重构动态搜索：
use Illuminate\Http\Request;
use App\Models\Role; // 假设你的模型是 Role
public function index (Request $request)
{
// 假设 getRoleCode() 函数用于获取角色编码
$roleCode = getRoleCode($request->role);
$roles = Role::where('role', $roleCode) // 初始查询条件
// 当 $request->input('q') 存在且非空时，执行闭包添加 name 搜索条件
->when($request->input('q'), function ($query, $search) {
return $query->where('name', 'like', '%'. $search .'%');
})
// 当 $request->input('gender') 存在且非空时，执行闭包添加 gender 过滤条件
->when($request->input('gender'), function ($query, $gender) {
return $query->where('gender', $gender);
})
->orderBy('id', 'DESC') // 排序
->paginate(20); // 分页
return view('admin.users.index', [
'roles' => $roles,
'role_name' => config('settings.roles')[$roleCode],
'role_en_name' => $request->role,
'q' => $request->q,
'gender' => $request->gender
]);
}代码解析：
- Role::where('role', $roleCode): 首先构建基础查询，筛选出特定角色的用户。
- ->when($request->input('q'), function ($query, $search) { ... }):
- $request->input('q') 作为 when 方法的第一个参数（$condition）。input() 方法会安全地获取请求参数，如果参数不存在则返回 null。在 PHP 中，null 会被评估为 false，非空字符串则评估为 true。
- 如果 q 参数存在且有值，则闭包会被执行。闭包接收当前查询构建器实例 $query 和 $request->input('q') 的值 $search。
- 在闭包内部，我们通过 $query->where('name', 'like', '%'. $search .'%') 添加了 name 字段的模糊搜索条件。
- ->when($request->input('gender'), function ($query, $gender) { ... }):
- 类似地，这行代码根据 gender 参数是否存在和有值，来添加 gender 字段的精确匹配条件。
- ->orderBy('id', 'DESC')->paginate(20): 最后，应用排序和分页。
这种方式的优点在于：
- 简洁性：将条件判断和查询构建融为一体，代码更紧凑。
- 可读性：链式调用使得查询逻辑一目了然。
- 安全性：$request->input() 自动处理参数不存在的情况，when 方法则进一步确保只有在条件满足时才添加查询子句。
注意事项与最佳实践
- 使用 request()->input() 或 $request->input(): 始终使用这些方法来获取请求参数，它们比直接访问 $request->q 更安全，因为它们在参数不存在时会返回 null，避免潜在的错误。
- 通配符处理: 对于 LIKE 搜索，确保正确地在搜索关键词前后添加 % 通配符。
- 默认值与验证: 考虑为搜索参数设置默认值，或者在控制器中对请求参数进行验证，以确保数据的有效性。
- 复杂条件: 对于更复杂的条件逻辑，你可以在 when 闭包内部使用 orWhere、whereHas 等更高级的查询方法。
- 代码可维护性: 当搜索条件非常多时，可以考虑将查询逻辑封装到自定义的查询作用域（Scope）中，或者使用管道模式（Pipeline Pattern）来进一步提高代码的可维护性。
总结
在 Laravel 中处理动态条件查询时，when 方法是构建灵活、可读且高效查询的强大工具。它通过将条件判断与查询构建无缝集成，显著简化了代码结构，是实现动态搜索和过滤功能的推荐实践。掌握 when 方法将使你的 Laravel 应用在处理复杂数据查询时更加健壮和优雅。
