使用 Laravel Query Builder 优雅实现动态搜索与条件查询

本文将深入探讨在 laravel 8 中，如何利用 eloquent 或 query builder 的 `when` 方法高效且优雅地处理动态搜索和条件查询。通过讲解 `when` 方法的工作原理及其应用，我们将学习如何根据请求参数的有无，灵活地构建数据库查询语句，从而避免冗余的条件判断，提高代码的可读性和可维护性。

在开发Web应用时，动态搜索和过滤功能是常见的需求。用户可能通过URL查询参数（例如 ?q=keyword&gender=m）来筛选数据。传统的做法是使用一系列 if 语句来判断每个参数是否存在，然后有条件地添加 where 子句。虽然这种方法可行，但当条件增多时，代码会变得冗长且难以管理。

传统条件查询的挑战

考虑以下场景，我们希望根据 q（搜索关键词）和 gender（性别）参数来过滤用户列表：

public function index (Request $request)
{
    $role = getRoleCode($request->role);
    $rolesQuery = Role::where('role', '=', $role);

    if ($request->q) {
        $rolesQuery->where('name', 'like', "%$request->q%"); // 注意：这里 $request->$q 是错误的写法，应为 $request->q
    }

    if ($request->gender) {
        $rolesQuery->where('gender', '=', $request->gender);
    }

    $roles = $rolesQuery->orderBy('id', 'desc')->paginate(20);

    return view('admin.users.index', [
        'roles' => $roles,
        // ... 其他视图数据
    ]);
}

上述代码中存在两个主要问题：

1. 变量引用错误："$request->$q%" 试图将 $q 作为一个变量名去访问 $request 对象的属性，这会导致错误。正确的做法应该是 "$request->q%" 或更推荐的 $request->input('q')。
2. 代码冗余：每个条件都需要一个 if 语句，当条件数量增加时，代码块会变得很长。

解决方案：利用 when 方法进行条件查询

Laravel 的 Eloquent ORM 和 Query Builder 提供了一个非常强大的 when 方法，专门用于处理这种条件性地向查询中添加子句的场景。when 方法的签名如下：

神采PromeAI

将涂鸦和照片转化为插画，将线稿转化为完整的上色稿。

111

查看详情

when(mixed $condition, callable $callback, callable $defaultCallback = null): static

• $condition: 这是一个布尔值或可以被评估为布尔值的值。如果 $condition 为 true（或“真值”），则会执行 $callback。
• $callback: 一个匿名函数，它接收当前查询构建器实例作为第一个参数，以及 $condition 的值作为第二个参数（如果 $condition 是非布尔值）。在这个回调中，你可以添加任何你想要的查询子句。
• $defaultCallback (可选): 如果 $condition 为 false（或“假值”），则会执行这个可选的回调。

通过 when 方法，我们可以将上述的条件查询重构为更简洁、更具可读性的形式。

use Illuminate\Http\Request;
use App\Models\Role; // 假设你的模型是 Role

class UserController extends Controller
{
    public function index(Request $request)
    {
        // 假设 getRoleCode 方法获取角色代码
        $roleCode = getRoleCode($request->role);

        $roles = Role::where('role', $roleCode)
            // 当 $request->input('q') 存在且非空时，执行回调函数
            ->when($request->input('q'), function ($query, $search) {
                return $query->where('name', 'like', '%' . $search . '%');
            })
            // 当 $request->input('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->input('q'), // 传递已过滤的搜索参数到视图
            'gender' => $request->input('gender') // 传递已过滤的性别参数到视图
        ]);
    }

    // 假设这是你的辅助函数
    private function getRoleCode($roleName)
    {
        // 实际逻辑可能更复杂，这里仅作示例
        return match ($roleName) {
            'supervisor' => 'SUP',
            'admin' => 'ADM',
            default => 'USR',
        };
    }
}

代码解析：

1. $request->input('q')：我们使用 input() 方法来安全地获取请求参数。如果参数不存在，input() 会返回 null，这在 when 方法中被评估为 false，从而不会执行对应的查询回调。
2. when($request->input('q'), function ($query, $search) { ... })：
   • $request->input('q') 作为第一个参数，如果它有值（即用户在URL中提供了 q 参数），则条件为真。
   • 回调函数被执行，并接收当前的 $query 实例和 $search（即 $request->input('q') 的值）。
   • 在回调中，我们安全地构建了 where('name', 'like', '%' . $search . '%') 子句。
3. 对于 gender 参数也采用了相同的逻辑。

when 方法的优势

• 简洁性：消除了多个 if 语句，使代码更加紧凑和易读。
• 可读性：查询逻辑流更加清晰，一眼就能看出哪些条件是动态添加的。
• 链式调用：完美融入 Laravel 的链式调用风格，提高了开发效率。
• 健壮性：when 方法结合 request()->input() 可以优雅地处理请求参数缺失的情况，避免了不必要的错误或复杂的条件检查。

注意事项

• $request->input() vs. $request->property: 建议使用 $request->input('key') 而不是 $request->key 来获取请求参数。input() 方法在参数不存在时会返回 null，这对于 when 方法的条件判断非常有用。而直接访问属性 $request->key 在参数不存在时可能会导致意外行为或报错（尽管 Laravel 通常会返回 null）。
• 复杂条件: 如果你的条件逻辑本身很复杂，或者需要根据多个请求参数来决定是否添加一个子句，你可以在 when 的第一个参数中放置一个更复杂的布尔表达式。
• 默认回调: 了解 when 方法的第三个参数 defaultCallback。如果你的查询在条件不满足时需要执行不同的逻辑，可以使用它。

总结

Laravel 的 when 方法是处理动态条件查询的强大工具，它使得构建灵活、可维护的搜索和过滤功能变得异常简单。通过将条件判断与查询逻辑分离，when 方法显著提升了代码的简洁性和可读性，是每个 Laravel 开发者都应该掌握的技巧。在需要根据用户输入动态调整查询逻辑的场景下，优先考虑使用 when 方法，它将帮助你编写出更优雅、更专业的 Laravel 代码。

以上就是使用 Laravel Query Builder 优雅实现动态搜索与条件查询的详细内容，更多请关注php中文网其它相关文章！