Laravel查询参数怎么映射

Laravel查询参数映射详解：从入门到精通

目录导读

1. 什么是查询参数映射？
2. Laravel中的基本查询参数处理
3. 高级映射技巧：请求到模型的优雅转化
4. 实战案例：构建智能API查询系统
5. 常见问题FAQ

---

什么是查询参数映射？

在Web开发中，查询参数映射（Query Parameter Mapping）是指将URL中的查询字符串（如?name=John&age=25）与后端代码中的变量或数据库查询条件进行关联的过程，在Laravel中，这不仅仅是简单的$request->input('name'),而是涉及以下核心能力：

• 自动绑定：将HTTP请求参数直接映射到Eloquent查询构造器
• 类型转换：字符串参数转整数、日期、布尔值等
• 过滤与排序：动态构建where、orderBy、limit等子句
• 安全验证：防止SQL注入与不合法输入

核心价值：避免手动编写大量条件判断,将重复逻辑抽象为可复用的映射规则。

---

Laravel中的基本查询参数处理

1 原生请求获取方式

// 控制器中获取参数
public function index(Request $request) {
    $name = $request->query('name', 'default');
    $page = $request->integer('page', 1);
    $active = $request->boolean('active');
}

2 手动构建查询（不推荐）

$query = User::query();
if($request->has('name')) {
    $query->where('name', 'like', '%'.$request->name.'%');
}
if($request->has('age')) {
    $query->where('age', '>=', $request->integer('age'));
}

问题：参数增多时代码膨胀,维护困难。

---

高级映射技巧：请求到模型的优雅转化

1 使用Laravel的where魔术方法

// URL: ?name=John&age=25
$users = User::whereName($request->name)
             ->whereAge($request->integer('age'))
             ->get();
// 但无法动态处理可选参数

2 自定义参数映射服务（推荐方案）

创建一个专用的QueryMapper类：

namespace App\Services;
class UserQueryMapper {
    protected $allowedFilters = ['name', 'age', 'email'];
    protected $columnMap = [
        'full_name' => 'name', // 前端参数 → 数据库字段
        'age_min' => 'age'
    ];
    public function apply($query, array $params) {
        foreach($params as $key => $value) {
            if(!in_array($key, $this->allowedFilters)) continue;
            $column = $this->columnMap[$key] ?? $key;
            match($key) {
                'name' => $query->where($column, 'like', "%{$value}%"),
                'age' => $query->where($column, '>=', (int)$value),
                'email' => $query->where($column, $value),
                default => null
            };
        }
        return $query;
    }
}

3 使用第三方包：spatie/laravel-query-builder

这是业内最成熟的解决方案：

// 安装：composer require spatie/laravel-query-builder
$users = QueryBuilder::for(User::class)
    ->allowedFilters(['name', 'age', 'status'])
    ->allowedSorts(['name', 'created_at'])
    ->allowedIncludes(['posts'])
    ->get();

• 自动处理过滤：?filter[name]=John → WHERE name LIKE '%John%'
• 排序：?sort=-created_at → ORDER BY created_at DESC
• 包含关系：?include=posts → 预加载关联

优点：零配置、支持复杂条件（如范围查询filter[age][gt]=18）、自动文档生成。

---

实战案例：构建智能API查询系统

假设我们有一个文章API,需要支持以下查询：

GET /api/articles?filter[title]=laravel&filter[category]=tutorial&sort=-published_at&page=2&per_page=15

1 控制器实现

use Spatie\QueryBuilder\QueryBuilder;
use App\Models\Article;
class ArticleController extends Controller {
    public function index() {
        $articles = QueryBuilder::for(Article::class)
            ->allowedFilters([
                'title',
                'category',
                'status',
                'author.name', // 关联表字段
                AllowedFilter::exact('id'), // 精确匹配
                AllowedFilter::scope('published_after') // 自定义作用域
            ])
            ->allowedSorts(['title', 'published_at', 'created_at'])
            ->allowedIncludes(['author', 'comments'])
            ->defaultSort('-published_at')
            ->paginate(request()->input('per_page', 15));
        return ArticleResource::collection($articles);
    }
}

2 自定义过滤作用域

// Article模型
public function scopePublishedAfter($query, $date) {
    return $query->where('published_at', '>=', Carbon::parse($date));
}
// 请求：?filter[published_after]=2024-01-01

3 安全处理与验证

// 使用表单请求验证
public function rules() {
    return [
        'filter.title' => 'nullable|string|max:100',
        'sort' => 'nullable|in:title,published_at,-title,-published_at',
        'page' => 'integer|min:1',
    ];
}

---

常见问题FAQ

Q1: 查询参数映射与直接使用Request有哪些性能差异？

A: 直接使用$request->input()无额外开销，但自定义映射或使用spatie/laravel-query-builder会产生微小的解析开销（约0.1-0.5ms），在百万级请求下建议启用OPCache，对于中小型项目可忽略不计,而代码可维护性提升显著。

Q2: 如何防止用户通过查询参数进行SQL注入？

A:

• 使用Eloquent ORM自动参数绑定（内部使用PDO预处理）
• 始终使用AllowedFilter::exact()或scope()而非原始字符串拼接
• 在自定义映射中使用where($column, $operator, $value)形式
• 对排序字段设置白名单（allowedSorts）

Q3: 复杂查询（如多表关联的OR条件）如何处理？

A: 使用AllowedFilter::callback()定义自定义过滤逻辑：

AllowedFilter::callback('search', function ($query, $value) {
    $query->where(function ($q) use ($value) {
        $q->where('title', 'like', "%{$value}%")
          ->orWhere('body', 'like', "%{$value}%");
    });
});
// 请求：?filter[search]=Laravel教程

Q4: 前端参数命名与数据库字段不一致怎么办？

A: 在映射定义中使用闭包或配置映射表：

AllowedFilter::custom('full_name', new Filters\NameFilter)

或修改$columnMap数组如表1所示。

Q5: 分页参数（page/per_page）是否需要映射？

A: Laravel的paginate()方法自动处理page和per_page参数，但对于自定义分页,可以：

$perPage = min(request()->integer('per_page', 15), 100); // 限制最大100条
$users = User::paginate($perPage);

---

通过合理运用查询参数映射，你可以将混乱的查询逻辑转化为声明式、可测试的代码，推荐优先使用spatie/laravel-query-builder这样的成熟方案，对于特殊需求再构建自定义映射器。好的映射系统应该让前端开发者按直觉写查询，而后端开发者只需定义规则。