Laravel查询作用域：复用数据库查询逻辑的最佳实践
项目地址: https://gitcode.com/GitHub_Trending/la/laravel 在日常开发中，你是否经常遇到重复编写相同数据库查询条件的情况？比如在用户管理模块中，需要多次筛选"活跃用户"或"管理员角色"，每次都要重复写where('status', 1)或where('role', 'admin')。这不仅导致代码冗余，还会增加维护成本。Laravel的查询作用域（Query Scopes）正是为解决这一痛点而生，它能将常用查询逻辑封装为模型方法，实现代码复用和逻辑集中管理。本文将从基础定义到高级应用，全面讲解查询作用域的使用技巧。
什么是查询作用域
查询作用域是Laravel模型中定义的特殊方法，用于封装可复用的查询逻辑。这些方法返回Illuminate\Database\Eloquent\Builder实例，可通过链式调用与其他查询条件组合。作用域分为本地作用域（Local Scopes）和全局作用域（Global Scopes）两类：前者需手动调用，后者会自动应用于模型的所有查询。
本地作用域 vs 全局作用域
| 类型 | 定义方式 | 调用方式 | 应用场景 |
|---|---|---|---|
| 本地作用域 | 方法名以scope开头 | Model::scopeName() | 特定场景的查询复用（如筛选活跃用户） |
| 全局作用域 | 实现Scope接口或使用匿名全局作用域 | 自动应用，无需手动调用 | 全表数据过滤（如软删除SoftDeletes） |
本地作用域：按需调用的查询逻辑
本地作用域是最常用的作用域类型，通过在模型中定义以scope为前缀的方法实现。以下以User模型为例，演示如何创建和使用本地作用域。
基础实现步骤
- 定义作用域方法：在模型中创建以
scope开头的方法，接收Builder实例作为参数。 - 封装查询逻辑：在方法中通过
Builder实例添加查询条件，并返回该实例。 - 调用作用域：在查询时通过
scopeName（省略scope前缀）调用。
示例：筛选活跃用户
假设用户表中有status字段（1=活跃，0=禁用），我们可以定义一个scopeActive方法：
// app/Models/User.php
public function scopeActive($query)
{
return $query->where('status', 1);
}
调用方式：
// 获取所有活跃用户
$activeUsers = User::active()->get();
// 链式调用其他条件
$recentActiveUsers = User::active()
->where('last_login_at', '>=', now()->subMonth())
->orderBy('name')
->get();
带参数的作用域
作用域支持接收额外参数，实现动态查询条件。例如筛选特定角色的用户：
// app/Models/User.php
public function scopeRole($query, $roleName)
{
return $query->where('role', $roleName);
}
调用时传入参数：
// 获取管理员用户
$admins = User::role('admin')->get();
// 结合活跃用户筛选
$activeAdmins = User::active()->role('admin')->get();
全局作用域：自动应用的查询过滤
全局作用域会自动应用于模型的所有查询，适用于需要全表过滤的场景（如多租户系统的数据隔离、软删除功能）。Laravel内置的SoftDeletes trait就是通过全局作用域实现的。
定义全局作用域
有两种方式定义全局作用域：匿名全局作用域和自定义作用域类。
方式1：匿名全局作用域
通过模型的booted方法注册匿名全局作用域：
// app/Models/User.php
protected static function booted()
{
static::addGlobalScope('active', function ($query) {
$query->where('status', 1);
});
}
以上代码会自动为所有User查询添加where('status', 1)条件，如需排除作用域，可使用withoutGlobalScope：
// 获取所有用户（包括禁用用户）
$allUsers = User::withoutGlobalScope('active')->get();
方式2：自定义作用域类
对于复杂逻辑，建议创建独立的作用域类：
- 创建作用域类：在
app/Scopes目录下创建类，实现Scope接口。
// app/Scopes/ActiveScope.php
namespace App\Scopes;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;
class ActiveScope implements Scope
{
public function apply(Builder $builder, Model $model)
{
$builder->where('status', 1);
}
}
- 在模型中注册：
// app/Models/User.php
use App\Scopes\ActiveScope;
protected static function booted()
{
static::addGlobalScope(new ActiveScope);
}
移除全局作用域
如需在特定查询中排除全局作用域，可使用以下方法：
// 移除单个作用域
User::withoutGlobalScope(ActiveScope::class)->get();
// 移除所有全局作用域
User::withoutGlobalScopes()->get();
// 移除多个指定作用域
User::withoutGlobalScopes([ActiveScope::class, AnotherScope::class])->get();
高级技巧：作用域组合与扩展
作用域链式组合
本地作用域支持链式调用，可组合多个查询条件：
// 筛选活跃管理员并按创建时间排序
$activeAdmins = User::active()
->role('admin')
->orderBy('created_at', 'desc')
->take(10)
->get();
作用域中使用关系查询
作用域可结合模型关系（Relationships）实现关联查询复用。例如筛选有未读消息的用户：
// app/Models/User.php
public function scopeHasUnreadMessages($query)
{
return $query->whereHas('messages', function ($q) {
$q->where('read_at', null);
});
}
假设User模型定义了messages关联：
public function messages()
{
return $this->hasMany(Message::class);
}
调用方式：
$usersWithUnread = User::hasUnreadMessages()->get();
动态作用域（条件式全局作用域）
通过判断当前上下文，动态决定是否应用全局作用域。例如，仅在前台查询时过滤未审核内容：
// app/Models/Post.php
protected static function booted()
{
if (!app()->runningInConsole() && !auth()->check()) {
static::addGlobalScope('approved', function ($query) {
$query->where('approved', true);
});
}
}
最佳实践与注意事项
命名规范
- 作用域方法名使用驼峰式命名，调用时自动转换为蛇形命名（如
scopeRecentActive对应recentActive调用）。 - 作用域名称应清晰描述查询意图（如
scopeActive而非scopeFilter1）。
性能优化
- 避免在作用域中执行额外查询（如
get()或first()），始终返回Builder实例。 - 复杂作用域可添加查询注释，便于调试：
public function scopeActive($query) { return $query->where('status', 1)->comment('筛选活跃用户'); }
代码组织
- 当模型中作用域数量较多时，可使用trait拆分作用域：
// app/Models/Scopes/UserScopes.php trait UserScopes { public function scopeActive($query) { /* ... */ } public function scopeRole($query, $role) { /* ... */ } } // 在User模型中使用 class User extends Authenticatable { use UserScopes; }
调试技巧
使用toSql()方法查看作用域生成的SQL语句，验证查询逻辑：
dd(User::active()->role('admin')->toSql());
应用场景案例
案例1：电商订单查询
在Order模型中定义多个作用域，实现不同状态订单的快速筛选：
// app/Models/Order.php
public function scopePending($query)
{
return $query->where('status', 'pending');
}
public function scopePaid($query)
{
return $query->where('status', 'paid');
}
public function scopeShipped($query)
{
return $query->where('status', 'shipped');
}
public function scopeThisMonth($query)
{
return $query->whereMonth('created_at', now()->month)
->whereYear('created_at', now()->year);
}
业务层调用：
// 获取本月已支付未发货订单
$unshippedPaidOrders = Order::paid()
->shipped(false) // 假设shipped作用域支持参数
->thisMonth()
->get();
案例2：内容管理系统
结合全局作用域和本地作用域，实现文章的多维度筛选：
// app/Models/Article.php
use Illuminate\Database\Eloquent\SoftDeletes;
class Article extends Model
{
use SoftDeletes; // 全局作用域：自动排除已删除文章
// 本地作用域：筛选已发布文章
public function scopePublished($query)
{
return $query->where('published_at', '<=', now())
->where('is_draft', false);
}
// 本地作用域：按分类筛选
public function scopeCategory($query, $categoryId)
{
return $query->where('category_id', $categoryId);
}
}
前台调用（自动排除删除文章）：
$techArticles = Article::published()
->category(5) // 技术分类ID=5
->orderBy('published_at', 'desc')
->take(10)
->get();
总结与扩展学习
查询作用域是Laravel ORM的强大特性，通过封装查询逻辑显著提升代码复用性和可维护性。掌握以下核心要点：
- 本地作用域：手动调用，适用于特定场景查询。
- 全局作用域：自动应用，适用于全表过滤。
- 作用域组合：通过链式调用实现复杂查询。
- 参数化：动态调整查询条件，增强灵活性。
扩展学习资源
- 官方文档：Laravel查询作用域
- 源码参考：查看
Illuminate\Database\Eloquent\Builder类了解链式查询实现原理。 - 相关功能：结合查询构建器宏实现跨模型的查询复用。
通过合理设计作用域，可将业务查询逻辑与控制器解耦，使代码更符合单一职责原则，为大型项目的维护提供有力支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
