whenLoaded 应在关联可能已加载且需避免重复查询或报错时使用，它不触发查询、只安全访问已加载数据，适用于响应组装等场景，而首次获取数据应选 with。
什么时候该用 whenLoaded 而不是 with
当你已经确定某个关联可能已被加载（比如在 API 响应构造器里复用已有模型），但又不想重复查询、也不希望它在未加载时报错访问，whenLoaded 才是安全选择。它不触发查询，只做“有就用，没有就跳过”的守门员。
常见错误现象：$post->author->name 在没 with('author') 的情况下直接调用，抛出 Trying to get property 'name' of non-object；有人误以为 whenLoaded('author', fn($a) => $a->name) 会自动加载 author——它不会，必须提前加载或配合 load 使用。
- 适用场景：响应组装、视图中条件渲染、DTO 构建器
- 不适用场景：首次获取数据、需要强制关联存在时（该用
with或whereHas） - 性能影响：零额外查询，纯内存判断，比
optional($post->author)->name更语义清晰
whenLoaded 的闭包参数到底是什么
闭包接收的参数是已加载的关联实例，类型取决于关联定义：一对一返回模型对象，一对多返回集合（Collection），多对多也返回集合。别默认它是数组或模型，尤其在处理 hasMany 时容易漏掉 ->first() 或 ->count()。
示例：$post->whenLoaded('comments', fn($comments) => $comments->count()) 是对的；但写成 fn($comments) => $comments->first()->content 就可能因空集合 crash。
- 一对一（
belongsTo/hasOne）：传入单个模型或null - 一对多/多对多（
hasMany/belongsToMany）：传入Collection，不会是null - 闭包里别再调
load或fresh——违背“按需”本意，且可能引发 N+1
和 load + when 混用时的坑
有人想“先判断是否加载，没加载就手动 load”，于是写 $post->when(! $post->relationLoaded('comments'), fn() => $post->load('comments')) ——这不行。when 是 Collection 方法，不能用于模型实例；而且 load 返回的是模型本身，不是布尔值，逻辑会错乱。
正确做法只有两种：要么统一用 loadMissing（推荐），要么拆开判断：
- 安全兜底：用
$post->loadMissing('comments')，它只在未加载时查询，已加载则跳过 - 手动判断：用
$post->relationLoaded('comments') ? $post->comments->count() : 0 - 别在
whenLoaded闭包里再调load，闭包只负责消费，不负责加载
JSON 序列化时 whenLoaded 不生效？
因为 whenLoaded 是方法调用，不是属性，Eloquent 序列化时不会自动执行。你写 'author_name' => $post->whenLoaded('author', fn($a) => $a->name) 在数组里没问题，但若直接塞进 toArray() 或 API Resource 的 toArray，它不会被识别为可序列化字段。
常见错误：在 Resource 里写 'author' => $this->whenLoaded('author')，结果输出 null——因为 whenLoaded 返回的是闭包执行结果，不是字段名映射。
- Resource 中正确写法：
'author_name' => $this->whenLoaded('author', fn($a) => $a->name) - 避免在
$appends里依赖whenLoaded，append 字段是属性访问，不是方法调用 - 如果要整个关联结构按需出现，用
makeHidden/makeVisible配合条件更稳
最易被忽略的一点：关联是否加载，取决于当前模型实例的状态，而不是全局配置或查询作用域——同一个模型变量，在不同请求生命周期里，relationLoaded 可能为真也可能为假，别假设它“应该”已加载。
