Laravel 优化查询复用需定义规范本地作用域（scopeXxx）、实现带参动态作用域、提取共用作用域至 Trait、链式组合多作用域，并按需禁用全局作用域。
如果您在 Laravel 项目中反复编写相同查询条件（如 where('status', 'active') 或 whereNotNull('published_at')），不仅增加维护成本，还易引发逻辑不一致。以下是优化 Laravel 框架作用域、实现查询范围高效复用的具体操作：
一、定义规范的本地作用域
本地作用域必须以 scope 开头，接收 $query（Builder 实例）为首个参数，并始终返回该实例以维持链式调用。任何遗漏 return $query 或错误命名（如写成 active() 而非 scopeActive()）均会导致调用失败。
1、在模型类中声明方法，命名格式为 scopeXxx，例如 scopePublished；
2、方法体内仅执行查询构造器操作，禁止调用 get()、first() 或返回数组；
3、确保末尾返回 $query，例如 return $query->where('status', 'published');。
二、实现带参数的动态作用域
当查询条件依赖运行时输入（如日期范围、分类标识），需定义接收额外参数的作用域。参数校验与类型转换须由开发者显式处理，Laravel 不自动解析字符串为时间对象或过滤空值。
1、方法签名必须将 $query 置于首位，后续参数按需添加，例如 scopeCreatedAfter($query, $date)；
2、在方法内使用 Carbon::parse($date)->startOfDay() 安全转换时间参数；
3、对可能为空的参数添加默认值或提前判空，例如 $date = $date ?? now()->subDays(7);；
4、调用时直接传入参数，如 ->createdAfter('2026-04-01')。
三、提取共用作用域至 Trait
多个模型需共享同一组查询逻辑（如状态启用、软删除过滤、租户隔离）时，将作用域封装进 Trait 可避免重复定义，同时支持 PHP 的多继承特性，提升跨模型复用效率。
1、创建新文件 app/Scopes/ActiveScope.php，定义 trait 并包含 scopeActive 方法；
2、在 trait 中确保所有作用域均遵循返回 $query 的规则；
3、在目标模型中使用 use ActiveScope; 引入该 trait；
4、引入后即可在任意模型上调用 ->active()，无需重复编码。
四、组合多个作用域构建复杂查询
本地作用域天然支持链式叠加，每个作用域在同一个 Builder 实例上连续追加条件，最终生成单条 SQL。这种组合方式语义清晰、调试直观，且可按需启用或跳过任一环节。
1、确保各作用域方法名均以 scope 开头并返回 $query；
2、在查询时按业务意图顺序拼接，例如 Post::published()->popular()->withTitle('API')->get()；
3、Laravel 按调用顺序依次执行每个作用域内部的 where 条件；
4、若某作用域需根据条件跳过，可配合 when() 方法动态控制，例如 ->when($request->has('status'), fn($q) => $q->active())。
五、按需禁用全局作用域
全局作用域虽能统一注入条件（如多租户 tenant_id 过滤），但测试、后台管理或数据迁移等场景常需临时绕过。Eloquent 提供原生机制解除全局约束，避免手动重写全部查询逻辑。
1、确认全局作用域已通过 static::addGlobalScope() 在模型 booted() 方法中注册；
2、在特定查询中调用 withoutGlobalScopes() 移除所有全局作用域；
3、若仅需移除某一类，传入作用域类名，例如 withoutGlobalScope(TenantScope::class)；
4、也可使用 withTrashed() 等内置方法替代，前提是全局作用域未覆盖其行为逻辑。
