Laravel 查询条件简化：使用 when() 动态构建搜索逻辑

本文介绍如何用 laravel 的 `when()` 方法替代冗长的 if-elseif 链，动态、安全、可读性强地构建多条件数据库查询。

在 Laravel 开发中，处理前端传来的多字段组合搜索（如关键词、日期范围、员工 ID 等）时，若采用传统 if/elseif 嵌套判断，不仅代码臃肿、难以维护，还极易因逻辑分支遗漏导致查询异常或 SQL 错误（例如 orWhere 未正确分组引发意外匹配）。幸运的是，Laravel 提供了优雅的解决方案——when() 方法，它支持按条件惰性追加查询子句，让查询构造变得声明式、扁平化且高度可扩展。

✅ 推荐写法：链式 when() 构建动态查询

$countries = Country::query()
    // 全局状态过滤（假设 status 也来自请求）
    ->when($request->filled('status'), function ($query) use ($request) {
        $query->where('sr_status', 'LIKE', "%{$request->input('status')}%");
    })
    // 日期起始筛选
    ->when($request->filled('datefrom'), function ($query) use ($request) {
        $query->whereDate('created_at', '>=', $request->input('datefrom'));
    })
    // 日期截止筛选
    ->when($request->filled('dateto'), function ($query) use ($request) {
        $query->whereDate('created_at', '<=', $request->input('dateto'));
    })
    // 多字段模糊搜索（注意：此处需用 where + orWhere 分组，避免逻辑错误）
    ->when($request->filled('keyvalue'), function ($query) use ($request) {
        $key = $request->input('keyvalue');
        $query->where(function ($q) use ($key) {
            $q->where('sr_name', 'LIKE', "%{$key}%")
              ->orWhere('tel_code', 'LIKE', "%{$key}%")
              ->orWhere('country_code', 'LIKE', "%{$key}%")
              ->orWhere('currency_name', 'LIKE', "%{$key}%");
        });
    })
    // 员工 ID 模糊匹配
    ->when($request->filled('prepid'), function ($query) use ($request) {
        $query->where('prep_emp', 'LIKE', "%{$request->input('prepid')}%");
    })
    // 统一排序
    ->orderBy('sr_id')
    ->get();

⚠️ 关键注意事项

• orWhere 的分组陷阱：原始代码中 orWhere 直接链式调用会导致与前面 where 条件形成 OR 关系（如 WHERE status LIKE ... OR sr_name LIKE ...），破坏预期逻辑。务必用 where(function ($q) { ... }) 将多 orWhere 包裹为独立子查询组。
• filled() vs has() vs exists()：推荐使用 $request->filled('field') 判断字段非空且非 null（等价于 !empty($request->input('field'))），比直接比较 == '' 更健壮（能正确处理 '0'、0、false 等边界值）。
• SQL 注入防护：Laravel 的 where() 和 whereDate() 均使用预处理语句，只要不拼接原始 SQL 字符串（如 DB::raw()），即可自动防止注入；但切勿用 sprintf 或 . 拼接用户输入到查询中。
• 性能优化建议：对高频搜索字段（如 sr_name, tel_code）建立复合索引或全文索引；日期字段确保 created_at 有索引。

✅ 总结

用 when() 替代 if-elseif 不仅大幅精简代码（从 50+ 行降至 20 行内），更提升了可读性、可测试性与可维护性。每个条件独立、互不干扰，新增搜索字段只需追加一个 ->when(...) 即可，无需修改原有逻辑分支。这是 Laravel Eloquent “流式查询构造” 能力的典型实践，也是构建健壮搜索功能的标准范式。