Laravel API多条件筛选应优先使用链式where，校验参数有效性、转换数字类型、统一模糊搜索方式；避免动态调用，推荐显式if控制；when仅适用于简单单字段条件且闭包必须返回$query；分页前须select指定字段防性能问题。
用 where 链式调用做基础多条件筛选
Laravel API 里最直接的多条件过滤，就是靠 Eloquent 的 where 方法链。它天然支持 AND 逻辑，参数顺序不影响结果，但要注意字段类型和空值处理。
常见错误现象：where('status', request('status')) 在 status 为空字符串或 null 时，会查出意外数据（比如把所有 status 为 0 或 '' 的都捞出来）。
- 先校验参数是否有效再拼条件：
request()->filled('status')比request('status') !== null更安全 - 数字字段别漏掉类型转换：
where('price', '>=', (int) request('min_price')) - 模糊搜索统一用
whereLike，别混用like和=
动态构建查询时避免 call_user_func_array 或反射
有人想用数组循环 + call_user_func_array($query, ['where', ...]) 来“自动”加条件，这写法看着省事，实则难调试、IDE 不识别、PHPStan 报错，还容易传错参数顺序。
正确做法是把条件逻辑收口到一个方法里，用明确的 if/else 控制分支：
if ($request->filled('category_id')) {
$query->where('category_id', $request->integer('category_id'));
}
if ($request->filled('q')) {
$query->where('title', 'like', "%{$request->q}%");
}
这样每行意图清晰，加日志、断点、单元测试都方便；也避免了 PHP 动态调用带来的性能微损（虽小但没必要）。
when 方法比手动 if 更简洁但有陷阱
when 是 Laravel 提供的链式条件语法糖，写起来干净，但新手常踩两个坑：一是误以为它能替代完整 if 分支，二是忽略闭包里没返回 $builder 导致链断裂。
使用场景：适合单字段、单逻辑的简单开关，比如启用/禁用某类过滤；不适合嵌套判断或需要复用变量的场景。
- 必须在闭包里返回
$builder，否则后续get()会报错：->when($request->filled('archived'), fn ($q) => $q->where('archived', true)) - 多个
when并列没问题，但别在里面写复杂逻辑，比如DB::transaction或额外查询 - 注意布尔值陷阱：
when(null)不执行，when(0)会执行——所以数字型参数建议用filled或显式比较
分页前别忘了 select 字段裁剪
API 过滤常配合 paginate() 使用，但默认 select * 在大表上会拖慢响应，尤其加了 join 或 JSON 字段后更明显。
性能影响：字段越多，MySQL 网络传输、PHP 序列化、内存占用都线性上涨；某些字段（如 content TEXT）还可能触发临时磁盘表。
- 强制指定字段：
select('id', 'title', 'status', 'created_at')，别依赖模型$fillable或$casts - 关联字段要用
with+select组合，比如with(['user:id,name,email']) - 如果前端真需要全部字段，至少用
toQuery()->toSql()看一眼生成的 SQL，确认没 N+1 或冗余 join
复杂点在于过滤条件和 select 字段之间存在隐式耦合——比如按用户邮箱过滤，就得确保 users.email 在 select 列表里，否则 where 会失效。这点很容易被忽略，一上线就 500。
