Laravel Eloquent 本地作用域：精准筛选关联模型中的特定状态数据

本文详解如何在 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 模型真正的力量所在。