在Laravel的数据库操作体系中，查询构建器是开发者与底层SQL之间的重要桥梁。虽然框架内置了大量便捷方法，但在处理“不匹配”这类反向过滤逻辑时，原生API只提供了whereNotIn、whereNotBetween以及whereNotLike等有限能力。如果业务里需要一种语义更清晰的whereNotMatch方法来表达“字段不匹配某模式”，就需要我们主动扩展查询构建器。本文将从实现机制、代码编写以及方案对比三个维度，详细讲解如何为Laravel添加这一自定义查询。
理解Laravel查询构建器的扩展点
Laravel的查询构建器主要由IlluminateDatabaseQueryBuilder类承担，而我们在模型里调用的Builder其实是与之关联的EloquentBuilder。要对所有查询统一增加方法，最干净的做法是利用宏（Macro）机制。宏允许在不修改框架源码的前提下，给类的实例动态添加方法，且这些方法是全局生效的。查询构建器在解析条件时，最终都会调用底层的where方法并指定布尔连接符与操作符，因此我们的whereNotMatch本质上就是封装了一次带有NOT LIKE或NOT REGEXP操作符的where调用。
除了宏之外，也有人会选择继承Builder类并替换数据库连接中的builder实例，但这种方式侵入性较强，需要改动服务提供者里的解析逻辑。宏的优势在于只需在服务提供者boot阶段注册一次，后续在任何Repository或模型查询中都能直接链式调用。同时宏内部可以完整使用参数绑定，避免字符串拼接带来的SQL注入隐患。理解这一点，是写出安全扩展的前提。
还需要注意，EloquentBuilder并不会自动代理所有QueryBuilder的宏。如果你希望模型查询也能用，通常要同时为EloquentBuilder注册同名宏，或者在宏内部通过调用getQuery()拿到底层实例。本文示例将直接在QueryBuilder上注册，并在Eloquent层做一层薄封装，确保两种调用方式都顺畅。
编写whereNotMatch宏的完整实现
下面给出在AppServiceProvider里注册宏的示例代码。我们设计一个whereNotMatch方法，接收字段名、匹配模式以及可选的连接类型，默认使用NOT LIKE进行模糊不匹配。为了兼容不同数据库，模式串里统一使用百分号作为通配符，并由框架自动处理参数绑定。
<?php
namespace AppProviders;
use IlluminateSupportServiceProvider;
use IlluminateDatabaseQueryBuilder as QueryBuilder;
use IlluminateDatabaseEloquentBuilder as EloquentBuilder;
class AppServiceProvider extends ServiceProvider
{
public function boot()
{
QueryBuilder::macro('whereNotMatch', function ($column, $pattern, $boolean = 'and') {
$value = '%' . $pattern . '%';
// 调用底层where，指定操作符为NOT LIKE
return $this->where($column, 'NOT LIKE', $value, $boolean);
});
EloquentBuilder::macro('whereNotMatch', function ($column, $pattern, $boolean = 'and') {
// 转发到查询构建器
$this->getQuery()->whereNotMatch($column, $pattern, $boolean);
return $this;
});
}
}
上述代码注册完成后，就能在代码中这样使用：User::whereNotMatch('name', 'test')->get()。它会生成类似select * from users where name NOT LIKE ?的SQL，绑定参数为%test%。如果我们要支持正则表达式不匹配，比如MySQL的NOT REGEXP，只需把宏里的操作符换成NOT REGEXP，并调整value为纯正则串即可。但需注意SQLite并不支持REGEXP原生操作符，跨数据库时要做好兼容判断。
在复杂查询中，你可能希望用orWhereNotMatch来拼接或条件。实现方式完全一致，只需在调用时传入boolean参数为'or'，或者再注册一个orWhereNotMatch宏内部调用whereNotMatch并传'or'。这种扩展不会影响原有查询的索引使用，因为NOT LIKE在多数情况下仍可能走字段扫描，但在中等数据量下表现稳定。
对比原生排除方案与自定义方法的优劣
很多场景下开发者会用whereNotLike直接写，例如->where('name', 'NOT LIKE', '%test%')。这当然能工作，但语义不够直观，新成员阅读代码时往往要反应一下才能明白是“不包含”。自定义whereNotMatch把意图显式化，也集中了通配符拼接逻辑，以后若想改成全词不匹配或正则不匹配，只需改宏一处。从可维护性看，封装后的方法明显优于散落各处的原始调用。
另一种常见做法是使用whereRaw写原生SQL片段，如whereRaw('name NOT REGEXP ?', [$pattern])。这种方式灵活却牺牲了可读性与部分数据库抽象能力，一旦切换数据库就得逐个检查。而宏方案保留查询构建器的链式风格，也能继续结合分页、排序等方法。下面是简要对比：
| 方案 | 可读性 | 数据库兼容 | 维护成本 |
|---|---|---|---|
| 原生whereNotLike | 中 | 高 | 中 |
| whereRaw原生片段 | 低 | 低 | 高 |
| 自定义whereNotMatch宏 | 高 | 高（可内部适配） | 低 |
从团队协作角度，统一的方法名也能配合IDE自动补全与静态分析工具，减少误写操作符的机会。当业务规则变化，比如要求不匹配时忽略大小写，我们可以在宏内对pattern做 strtolower 并对字段套一层LOWER函数，调用方完全无感。这种集中控制的能力，是简单散写SQL难以具备的。
最后提醒，任何扩展都建议配套单元测试。你可以伪造数据库或利用SQLite内存库，断言生成的SQL与绑定值符合预期。这样在Laravel版本升级导致Builder内部变动时，测试能第一时间报警，保障自定义查询构建器长期可用。
Laravel查询构建器whereNotMatch修改时间：2026-08-15 06:42:30