Laravel关联查询模糊搜索实战教程

本文深入剖析了 Laravel 中关联模型模糊搜索的实战要点与常见陷阱，重点揭示了因 SQL 运算符优先级导致的 `orWhere` 链式调用逻辑错误、多关键词分词组合查询的正确构建方式、`whereHas` 与 `orWhereHas` 在主模型筛选中的不可替代性，并强调了索引优化、输入校验（`filled()`）、安全绑定（禁用 `whereRaw` 拼接）、中文排序规则及分页时机等关键性能与安全实践——帮你避开线上漏数据、慢查询、SQL 注入等高频坑，写出既健壮又高效的模糊搜索逻辑。

直接用 orWhereHas() 就能查出“主模型字段或关联模型字段匹配关键词”的结果，但必须用闭包包裹所有 orWhere 条件，否则逻辑错乱、漏数据。

为什么 orWhere 单独链式调用会出错

因为 SQL 中 OR 优先级低于 AND，Eloquent 默认把连续的 where 和 orWhere 翻译成平级条件。比如：

Article::where('title', 'like', '%a%')
    ->orWhere('description', 'like', '%a%')
    ->orWhereHas('files', fn ($q) => $q->where('filename', 'like', '%a%'))

实际生成的 SQL 相当于：WHERE (title LIKE ?) OR (description LIKE ?) OR EXISTS (...) —— 看似没问题。但一旦前面加了其他 where（比如状态过滤），就会变成：

WHERE status = 1 AND title LIKE ? OR description LIKE ? OR EXISTS(...)

这等价于：(status = 1 AND title LIKE ?) OR description LIKE ? OR EXISTS(...)，导致 status 条件只对第一个字段生效。

正确做法是显式分组：

• 所有模糊条件包进一个 where() 闭包里，用 orWhere 连接
• 把非模糊条件（如 status、user_id）写在闭包外面

关联字段模糊搜索必须用 whereHas 或 orWhereHas

with() 不是筛选工具，它只控制预加载内容；哪怕你在 with(['files' => fn ($q) => $q->where(...)]) 里加条件，也只会过滤附件列表，不会影响 Article 是否被查出来。

真正能根据关联数据筛选主模型的，只有：

• whereHas('relation', $callback)：主模型必须有满足条件的关联记录（类似 INNER JOIN）
• orWhereHas('relation', $callback)：和主模型自身条件做 OR 关系，适合“标题或文件名含关键词”这类场景

注意：whereHas() 内部的 $query 是关联模型的查询实例，字段名要对应关联表，不是主表字段。

多关键词分词搜索要手动拆解再嵌套

用户搜 "laravel api"，不能只查 LIKE '%laravel api%'——这样匹配不到 title='Laravel' + description='API docs' 的组合。

得先分词，再为每个词构建一组 OR 条件：

$keywords = preg_split('/\s+/', $request->input('q'), -1, PREG_SPLIT_NO_EMPTY);
$articles = Article::query();

if (! empty($keywords)) {
    $articles->where(function ($q) use ($keywords) {
        foreach ($keywords as $kw) {
            $q->orWhere(function ($inner) use ($kw) {
                $inner->where('title', 'like', "%{$kw}%")
                      ->orWhere('description', 'like', "%{$kw}%")
                      ->orWhereHas('files', fn ($f) => $f->where('filename', 'like', "%{$kw}%"));
            });
        }
    });
}

$articles->where('status', 1)->paginate(15);

这种写法生成的是：WHERE status = 1 AND ((title LIKE ? OR description LIKE ? OR EXISTS(...)) OR (title LIKE ? OR ...))，语义清晰且可控。

性能与安全必须同步处理

LIKE '%keyword%' 在百万数据下必然全表扫描，加 B-Tree 索引无效；同时，用户输入不校验会引发注入或报错：

• 永远用 where('field', 'like', "%{$value}%")，别碰 whereRaw 拼字符串
• 空值必须用 $request->filled('q') 判断，filled() 能过滤 null/''/[]
• 中文搜索若需拼音或简繁体兼容，MySQL 建议用 utf8mb4_0900_as_cs 排序规则，或直接上 Scout + Meilisearch
• 分页必须放在最后，paginate() 要看到完整 WHERE 才能正确 COUNT

最易忽略的一点：关联模糊搜索时，orWhereHas 的子查询如果没有索引，可能比主表还慢——务必给关联表的搜索字段（如 article_files.filename）单独建索引。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~