Laravel自定义查询构建器_添加whereLike模糊查询【详解】

先说几个核心判断：Lara vel 并没有内置 whereLike 方法，这并非设计缺陷，反而是官方有意为之。说白了，它只是 where($column, 'like', $value) 的语法糖，多一层封装对实际开发没有任何增益，反倒容易让人忽略 SQL 查询中通配符位置和索引效率这些真正关键的问题。如果你直接调用 whereLike，会得到Call to undefined method 的错误——别想着去找第三方包或者写宏了，用标准 where 配合 like 操作符，才是最安全也最清晰的实现方式。

为什么没有 whereLike 方法

Lara vel 的查询构造器，无论是 Eloquent 还是 Query Builder，一直都没有内置 whereLike。社区里确实有人封装成宏或者 trait，但官方选择不提供，原因很务实：

• 它本质上只是 where($column, 'like', $value) 的语法糖，并不能带来语义上的增益
• 多一层封装反而模糊了 SQL 的本质，容易让新手误以为这是一个“特殊的模糊函数”，从而忽略通配符位置和索引的影响
• 更容易诱导出错误写法，比如 whereLike('name', $q) 这样不带百分号的调用，结果查不到数据还让人摸不着头脑

正确写法：where + like + 手动控制通配符

所有模糊匹配都应当显式决定通配符的放置位置，这直接影响查询性能和语义：

• where('title', 'like', "%{$q}%") → 全模糊，前后都可变，无法走 B-tree 索引，数据量大时要谨慎使用
• where('title', 'like', "{$q}%") → 前缀匹配，能命中索引，适合搜索建议、品牌名等场景
• where('title', 'like', "%{$q}") → 后缀匹配，MySQL 8.0+ 可以用反向索引优化，但需要手动创建
• 千万别把 "%{$q}%" 拼进 whereRaw() 里——whereRaw('title LIKE ?', ["%{$q}%"]) 这种写法是错的，问号不会自动帮你包裹通配符，必须自己加上

多字段 OR 模糊必须用闭包分组

这是线上最容易翻车的点。下面这段代码看着没问题，实际逻辑已经崩了：

$users = User::where('name', 'like', "%{$q}%")
    ->orWhere('email', 'like', "%{$q}%")
    ->where('status', 1)
    ->get();

生成的 SQL 等价于 WHERE (name LIKE ?) OR (email LIKE ?) AND (status = 1)，也就是说 status 这个条件只约束了 email 的匹配项。正确的做法是：

• 把所有 orWhere 放进一个 where() 闭包里
• 非模糊条件（比如 status、deleted_at）写在闭包外面
• 关联字段的模糊查询用 orWhereHas()，同样要包进同一个闭包

举个例子：

$users = User::where('status', 1)
    ->where(function ($q) use ($q) {
        $q->where('name', 'like', "%{$q}%")
          ->orWhere('email', 'like', "%{$q}%")
          ->orWhereHas('profile', fn ($sub) => $sub->where('bio', 'like', "%{$q}%"));
    })
    ->get();

空值、类型与分页的连环坑

搜索接口上线后出问题，往往不是因为模糊逻辑本身，而是边缘情况没有处理好：

• $request->input('q') 可能是 null、空字符串、或者纯空白字符——直接塞进 where() 会导致查出全表或者报错，必须用 $request->filled('q') 来做校验
• 用户搜 123，但字段是字符串型（比如订单号），where('order_no', $q) 会被 MySQL 隐式转成数字，123A 这样的记录就匹配失败了；模糊查询不存在这个问题，但需要确认字段类型到底适不适合模糊搜索
• paginate() 必须放在整个查询链的最后，哪怕你加了 selectRaw() 或 withCount()，只要它不在末尾，COUNT(*) 就会漏掉条件，分页数据就会出错

说白了，真正难的一直不是“怎么写 like”，而是想清楚：这个搜索到底要解决什么问题？要不要支持分词？要不要做相关性排序？百万级数据如果还硬扛 LIKE '%xxx%'，不如早点切到 Scout 加 Meilisearch——模糊查询只是一个入口，而不是终点。