when 是 Eloquent 的条件查询开关，仅在条件为真时执行闭包内查询构建操作；需校验空值、避免无效 like 和 whereIn 空数组，多 when 顺序执行且共享查询实例，unless 适用于否定语义场景。
when 方法怎么用才不踩坑
when 是 Eloquent 提供的链式条件构建方法，核心作用是：**只在条件为真时才执行后续闭包里的查询操作**。它不是“if 语句的语法糖”，而是“查询构建器的条件开关”——闭包里调用的 where、orderBy、with 等都会被真实追加到查询中；条件为假时，整个闭包被跳过，不影响已构建的部分。
常见错误是把它当普通 if 写成这样：
->when($request->has('status'), function ($query) use ($request) {
return $query->where('status', $request->status);
})
这其实没问题，但很多人误以为必须 return $query —— 实际上闭包内任何对 $query 的修改都是就地生效的，return 不是必须的（虽然加上更清晰）。更危险的是把复杂逻辑塞进闭包却不处理空值或类型转换，比如传入字符串 "0" 或空数组却没校验。
多个 when 连续使用时的执行顺序和依赖关系
多个 when 是顺序执行的，彼此独立，不会互相干扰。但要注意：它们共享同一个查询实例，所以后一个 when 看到的是前一个已经修改过的 $query。
- 如果前面的
when添加了where('deleted_at', null)，后面再用when($withTrashed, ...)就得显式调用withTrashed()覆盖，否则软删除条件仍生效 - 排序类条件（如
orderBy）会覆盖前面同字段的排序，不是叠加。例如两个when都设orderBy('created_at')，后者生效 - 关联预加载（
with）可多次调用，Eloquent 会自动去重，但嵌套结构（如with(['user.posts'])）不能靠多个when拼接，得合并写
when 和 unless 的配合使用场景
unless 是 when 的反向版本：条件为假时才执行闭包。两者组合能写出更紧凑的条件分支，尤其适合「默认启用某行为，仅在特定参数存在时禁用」这类逻辑。
比如搜索接口默认要排除软删除记录，但允许通过 ?with_trashed=1 强制包含：
->unless($request->boolean('with_trashed'), function ($query) {
$query->whereNull('deleted_at');
})
再比如分页参数校验：只在 per_page 合法时才应用，否则 fallback 到默认值，这时用 when 更自然；而「只有未登录用户才隐藏敏感字段」这种逻辑，用 unless(Auth::check()) 读起来更贴近业务语义。
注意：unless 的判断逻辑容易和直觉相反，建议只在条件语义明确为“否定触发”时用，避免嵌套 !$flag 再套 when，那纯属自找麻烦。
when 闭包里调用 with 或 join 时的注意事项
在 when 闭包中调用 with 是安全的，Eloquent 会延迟加载，不影响 SQL 构建；但 join 类操作（如 leftJoin）必须确保关联表字段名不冲突，且 select 显式声明字段，否则容易因重复列名报错。
典型陷阱：
- 多个
when分别加with('author')和with('category')没问题，但若其中一个还写了select('posts.*')，另一个没写，可能导致字段被覆盖或报错 - 用
when($search, fn($q) => $q->where('title', 'like', "%{$search}%"))时，如果$search是空字符串或 null，like "%%"会全表扫描，性能极差 —— 必须提前过滤掉无效搜索值 - 闭包中调用
whereIn时，传入空数组会导致 SQL 报错（WHERE id IN ()），需额外判断：when(!empty($ids), fn($q) => $q->whereIn('id', $ids))
真正难的不是语法，而是每个 when 后面都得想清楚：这个条件是否可能为空？是否会影响后续其他条件的语义？数据库层面会不会因此多扫几万行？
