PHP怎么处理Eloquent Scopes查询作用域复用_Laravel查询逻辑封装【指南】

Eloquent 的查询作用域（Scopes）是个好东西，用好了能让代码精简不少，但用砸了，排查问题的过程能让人怀疑人生。尤其是那些“明明逻辑对，但数据就是不对”的诡异场景，十有八九是作用域在背后搞鬼。下面这几个核心痛点，是线上环境实实在在踩过的坑。

本地作用域：小心思，大问题

断链的源头，往往只是一个 return

写本地作用域最基础也最要命的一点：必须返回 $query 实例。Eloquent 在调用本地作用域时，会把当前查询构造器实例传进去，它需要你把这个“接力棒”再传回来。一旦断了，后面跟的 where、orderBy 这些方法就会报错，或者更糟糕——静默失效，查出来的数据跟预想的不一样。

• 错误示范：public function scopeActive($query) { $query->where('status', 'active'); } —— 这里就漏了关键的 return。
• 正确写法：public function scopeActive($query) { return $query->where('status', 'active'); }
• 别在作用域里“翻旧账”： 别想着去获取 $this->id 之类的模型实例属性。此时模型还没从数据库里加载出来，你拿到的只会是 null 或者抛个异常。
• 命名守规矩： 方法必须是 public 的，并且严格以 scope 开头，比如 scopeLatest。调用的时候直接用 ->latest()，Eloquent 会自动解析。

带参数的作用域，是另一个常见的“翻车”现场

参数类型不匹配、空值没处理、或者传了个不该传的对象进去，是本地作用域最常出问题的几个地方。PHP 8+ 的严格类型检查会让这类问题直接报错，但在低版本 PHP 里，它可能只在运行时悄悄崩溃。

• 把类型写死： 比如 public function scopeWithinDays($query, int $days = 7)，这样你就不可能传个字符串 '30' 进去，导致 subDays() 报错。
• 对可为空的参数做好兜底： public function scopeByCategory($query, ?string $category = null) { return $category ? $query->where('category', $category) : $query; } 这样，传了 null 就直接返回原始查询，不出错。
• 别把请求上下文带进来： 本地作用域不是控制器，它不应该知道 Request 或 Auth 的存在。别把 $request 对象传进去，耦合度高不说，还影响测试。
• 快速验证的方法： 写完作用域，直接在 Tinker 里跑 User::where('name', 'test')->byCategory('admin')->get()，比写单元测试更快发现参数问题。

全局作用域：CLI 环境下的“幽灵”

全局作用域最大的问题在于，它在 CLI 或队列任务里拿不到 HTTP 请求上下文。如果你在 apply() 方法里硬编码从 session() 或 request() 里取租户 ID，那这些任务一跑，条件必然为空或者直接报错。

• 正确的租户 ID 获取方式： 必须通过服务容器来解析，比如 app(TenantManager::class)->currentId()。这个 TenantManager 类需要设计好面对 CLI 环境时的备用逻辑。
• 别用 whereNotNull 这种“万能药”兜底： 在 apply() 里写 whereNotNull('tenant_id') 这种条件，会污染所有查询，甚至让 forceDelete() 都带上这个限制，后果很严重。
• remove() 方法不是摆设： 做数据迁移或者后台管理时，需要用 Model::withoutGlobalScopes()->get() 来跳过全局作用域。但前提是你的全局作用域确实实现了 remove() 方法，很多人的代码里都漏了这一步。
• 别重复造轮子： Lara vel 自带的 SoftDeletes trait 已经帮你管理了删除状态的查询。如果你再手动加一层全局 whereNull('deleted_at')，就会和它冲突，导致 restore() 等方法失效。

scopeWithoutTrashed：自定义软删除作用域的“陷阱”

很多人在作用域里直接写个 whereNull('deleted_at') 当成“不包含已删除”的条件。这很危险——万一哪天这个模型没启用 SoftDeletes trait，这个条件就变成了一个无意义的过滤，还可能掩盖掉业务流程上的错误。

• 加一层保护： 正确的做法是加个判断：if (static::usesSoftDelete()) { $query->whereNull('deleted_at'); }
• 别在 boot() 里强制加条件： 官方明确反对在 boot() 方法里用 addGlobalScope() 强制加软删除条件。这会让 restore() 和后台列表功能出问题。
• 优先用 withoutTrashed()： 日常查询直接用 Model::withoutTrashed() 就好，它内部已经包含了安全判断。只有在需要封装特定语义（比如叫 scopePublished()）时，才考虑自建作用域。
• 注意重复条件： 如果你同时用了自己写的 scopeWithoutTrashed() 和 Lara vel 自带的 withoutTrashed()，SQL 里会出现两个 WHERE deleted_at IS NULL。虽然逻辑没错，但查不出数据时排查起来就很费劲了。

总的来说，写对一个作用域本身不难。真正考验水平的，是确保它在命令行、队列、API、后台管理这些不同上下文中，行为表现完全一致。全局作用域常在非 HTTP 场景下静默失效，本地作用域则常因参数校验不严搞出线上异常。这些问题往往都没日志、没提示，只能靠扎实的测试覆盖和良好的调用习惯来兜底。