scope是将语义明确、复用频繁的业务筛选逻辑从控制器抽离至模型中封装的查询作用域，必须以scope开头、只接受$query和一个额外参数、返回$query以支持链式调用，并需兜底处理空值、时间反序等问题。
为什么多条件查询代码越来越乱
因为每个条件都用 if 套一层 where，嵌套深、重复多、逻辑散——尤其是用户筛选项一多（比如时间范围 + 状态 + 关键词 + 分类），where 调用就堆成面条代码，改一个条件得翻三页。
根本问题不在写法，而在职责没分清：业务筛选逻辑不该和数据库操作混在一起。Scope 就是把「哪些数据该被查出来」这个判断，从控制器里拎出来，单独封装。
- 不是所有
where都适合塞进 Scope，只抽离**语义明确、复用频繁、带业务含义**的组合，比如statusActive()、searchByKeyword() - Scope 必须定义在模型类里，且方法名要以
scope开头（如scopeSearch()），否则框架不识别 - 传参只能是一个
$query对象 + 一个额外参数（数组或字符串），不能多于两个参数，否则调用时会报错Too many arguments
怎么写一个可用的查询作用域
Scope 本质就是一个接收 $query 并返回它的闭包式方法，重点是它必须主动调用 where 等链式方法，并返回 $query 本身（不然链式中断）。
常见错误是忘了 return $query，或者在作用域里写了 return $query->select() 这类终结操作，导致后续无法继续链式调用。
- 正确写法：
return $query->where('status', 1)->where('is_deleted', 0); - 错误写法：
$query->where(...);（没 return）、return $query->find();（终结了查询） - 支持多参数？不行。但可以传一个数组：
scopeFilter($query, $params)，然后在内部解构$params['keyword']、$params['start_time'] - 多个 Scope 可叠加使用：
UserModel::scope('active')->scope('search', ['k' => 'admin'])->select();
Scope 和普通方法、闭包查询的区别在哪
普通模型方法（比如 getActiveList()）封装的是完整查询结果，返回数组或集合；闭包查询（where(function ($q) {...})）只解决“同一 where 下的子条件”，不解决跨场景复用；而 Scope 是介于两者之间：它不执行查询，只修饰 $query 对象，让调用方决定何时执行、如何组装。
- Scope 天然支持链式，普通方法不支持（除非你手动 return $this）
- 闭包查询无法复用，每次都要重写；Scope 定义一次，全项目可调用
- Scope 在底层会被统一处理为
Query的扩展，所以兼容with、order、paginate等所有后续操作 - 注意：Scope 不会自动过滤软删除字段，
useSoftDelete需要另外配置或显式加where('delete_time', null)
实际组合查询时容易踩的坑
最典型的是「空值条件没过滤」——比如搜索框为空时还执行 where('name', '')，直接让整条 SQL 查不到数据。Scope 里必须做兜底判断。
- 别直接用
where('field', $value)，先判断：if (!empty($value)) { $query->where('field', $value); } - 时间范围要防反序：
if ($start && $end && strtotime($start) > strtotime($end)) { [$start, $end] = [$end, $start]; } - 多个 Scope 顺序有影响：比如
scopeWithTrashed()必须放在最前，否则后面的作用域可能被软删除拦截 - 调试时看最终 SQL：开启
show_sql配置，或用buildSql()方法提前打印，别靠猜
Scope 不是银弹，它只解决「条件组织」的问题。真正复杂的权限过滤、动态表连接、聚合计算，还是得回到查询构造器或原生 SQL。但只要条件开始重复出现三次以上，就该考虑把它塞进 scope 里了。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
