$visible不是API字段开关，而是全局白名单锁：启用后未列字段一律不输出，新增字段需手动添加，且与$hidden及makeHidden/makeVisible互斥；真正可控方案是用API Resource配合only()和动态逻辑。
$visible 不是 API 字段开关，启用后会让所有未列明的字段默认消失，且无法按请求动态调整。
为什么 $visible 一用就丢字段
设了 $visible = ['id', 'name']，哪怕数据库里有 email、avatar_url，它们在 toArray() 或 API 响应里直接不出现——不是“隐藏”，是“拒绝输出”。新增字段也得手动加进数组，漏一个就永远不可见。
- 它和
$hidden是互斥模式：一旦定义$visible，$hidden和所有makeHidden()/makeVisible()全部失效 - 分页集合调用
$users->makeVisible(['email'])没反应？因为$visible白名单已锁死输出范围 - Resource 类里写
return $this->resource->toArray()，照样丢字段——白名单在模型序列化阶段就截断了
$visible 和 $hidden 能不能混用
不能。Laravel 底层只认一种策略：$visible 存在则强制白名单；$visible 为空或未定义，才走 $hidden 黑名单逻辑。两者同时存在时，$visible 优先生效，$hidden 彻底被忽略。
- 常见误操作：模型里先写
$hidden = ['password']，调试时又加$visible = ['id']，结果连name都没了 - 想临时多吐一个字段？
makeVisible()在$visible模式下完全不触发 - 唯一绕过方式：删掉
$visible，改用$hidden+makeVisible()组合
哪些场景真适合用 $visible
极少。仅适用于极简、字段绝对稳定、且无任何权限/客户端/版本差异的内部服务，比如某个只供 CLI 脚本读取的配置模型。
- 后台管理接口需要返回
email和last_login_at？别用$visible，改 Resource 的only() - App 端只要
id、nickname、avatar？定义toArrayForApp()方法，别污染模型 - 日志记录、队列任务、Telescope 调试里 dump 模型？
$visible会让这些地方也丢字段，排查时一头雾水
替代方案：比 $visible 更可控的字段控制
把字段决定权从模型层上移到响应生成点，才是 Laravel 推荐路径。
- API 响应统一走 Resource：
new UserResource($user)，在toArray()里用$this->resource->only(['id', 'name']) - 需临时暴露敏感字段？
$this->resource->makeVisible('api_token')，只影响当前响应 - 按权限动态控制：
auth()->user()->can('view_email', $user) ? ['email'] : []，拼进only()数组 - 避免在模型里写
$visible或$hidden做 API 过滤——那不是控制输出，是在给后续所有环节埋雷
最易被忽略的是：$visible 会穿透所有使用 toArray()/toJson() 的地方，包括你没意识到的队列任务、事件广播、缓存序列化。它不是“API 字段开关”，而是一把全局锁。
