本文详解如何在 Lara vel 中通过本地作用域（Local Scopes）封装条件逻辑，实现对 Client 关联的 Credit 模型按 status = 1（ACTIVE）高效筛选，并在 Livewire 视图中清晰展示“活跃信贷数”，避免 N+1 查询与重复条件硬编码。
在业务开发中，我们常常会遇到这样的场景：需要统计客户拥有的信贷总数，但仅仅一个总数往往不够。更常见的需求是，我们得区分出哪些是“活跃”的信贷。如果直接在视图里遍历过滤，性能堪忧不说，代码也显得杂乱无章。
那么，有没有一种既高效又优雅的解决方案呢？答案是肯定的。关键在于，将状态筛选的逻辑下沉到模型层，用本地作用域（Local Scopes）来封装这些可复用的查询约束。这不仅是性能优化的最佳实践，更是 Lara vel Eloquent 设计哲学的核心体现。
一、定义本地作用域（Local Scope）
首先，我们需要在 Credit 模型中定义清晰、语义化的作用域。记住命名规范：方法名必须以 `scope` 开头，并采用驼峰命名法。
// app/Models/Credit.php
use Illuminate\Database\Eloquent\Builder;
class Credit extends Model
{
const ACTIVE = 1;
const LIQUIDATED = 2;
protected $fillable = ['amount', 'amount_end', 'status', 'dues'];
// ... 其他关系定义（client, provider, payments）
/**
* 本地作用域：仅查询状态为 ACTIVE 的信贷
*/
public function scopeActive(Builder $query): Builder
{
return $query->where('status', self::ACTIVE);
}
/**
* 本地作用域：仅查询状态为 LIQUIDATED 的信贷
*/
public function scopeLiquidated(Builder $query): Builder
{
return $query->where('status', self::LIQUIDATED);
}
}
⚠️ 这里有个关键点：作用域方法必须返回 `$query`（即 Builder 实例），这样才能支持链式调用。第一个参数固定为 `Builder $query`，Eloquent 会自动为我们注入。
二、在关联查询中使用作用域（关键！）
定义好作用域只是第一步，如何用对地方才是精髓。一个常见的误区是试图对已经加载完成的集合（比如 `$item->credits`）调用作用域——这行不通，因为作用域是 Eloquent Builder 的方法，而非 Collection 的方法。
正确的做法是，在查询数据库的阶段就应用作用域。以 Livewire 组件为例，我们可以在获取数据时，通过 `withCount` 方法预加载并统计过滤后的结果。
// app/Livewire/ShowClient.php
public function render()
{
$clients = Client::withCount(['credits as active_credits_count' => fn ($q) => $q->active()])
->with(['credits' => fn ($q) => $q->active()]) // 可选：预加载活跃信贷数据
->get();
return view('livewire.show-client', compact('clients'));
}
这段代码的妙处在于 `withCount` 的高级语法。它会在数据库层面生成一个子查询，精准统计每个客户的活跃信贷数量，并将结果直接赋给 `$client->active_credits_count` 属性。整个过程零内存开销，性能达到极致。
三、更新 Livewire 视图逻辑
经过上面的处理，视图层的逻辑就变得异常简洁。我们不再需要任何遍历或过滤操作，直接使用计算好的属性即可。
@foreach ($clients as $item)
{{ $item->name }}
@switch($item->active_credits_count)
@case(0)
No Active Credits
@break
@case(1)
1 Active Credit
@break
@default
{{ $item->active_credits_count }} Active Credits
@break
@endswitch
@endforeach
四、进阶提示：组合与复用
- ✅ 作用域天生支持链式组合，比如 `Credit::active()->where('amount', '>', 1000)->get()`，这让复杂查询的构建变得非常直观。
- ✅ 可以灵活搭配 `whereHas()` 来筛选主模型，例如查找所有拥有活跃信贷的客户：
Client::whereHas('credits', fn ($q) => $q->active())->get(); - ❌ 调试时需注意，避免在作用域内直接调用 `$query->toSql()`（可能导致未编译错误），推荐使用 `dd($query->toRawSql())` 或借助 Lara vel Telescope 等工具。
说到底，运用本地作用域不仅仅是为了代码整洁或性能提升。它更是一种将业务语义（如什么是“active”）直接注入到模型 API 中的设计思想。通过面向对象的方式清晰地表达数据意图，这才是 Eloquent 模型真正的力量所在。
