$append字段未出现在api返回中是因为未触发访问器，常见原因包括：$appends未声明为public、命名不匹配（如full_name需对应getfullnameattribute）、被$hidden过滤、未调用append()或未走完整序列化流程。
模型里写了 $appends 却没出现在 API 返回里？不是 Laravel 坏了，是它根本没触发访问器——绝大多数问题出在声明方式、命名匹配或序列化时机上。
为什么 $appends 字段在 toArray() 里不出现
最常被忽略的前提：模型必须真正走完序列化流程。用 dd($model)、var_dump($model) 或直接 echo 对象，$appends 完全不会执行。
-
$appends必须声明为public，写成protected $appends或漏掉声明，Laravel 静默跳过，不报错也不警告 - 数组值必须是小写下划线格式字符串，比如
['full_name', 'is_admin']；对应访问器方法名必须严格是getFullNameAttribute()和getIsAdminAttribute()，少一个大写字母或下划线都不行 - 访问器方法必须是
public、无参数、非静态；返回值建议兜底（如return $this->first_name . ' ' . ($this->last_name ?? '') ?: ''），避免返回null（toJson()默认过滤null） - 如果字段同时在
$hidden里，哪怕进了$appends，也会被彻底过滤掉
用 append() 动态追加比改 $appends 更安全
全局 $appends 会让所有接口都带上字段，而 append() 只影响当前实例或集合，按需注入，不污染模型定义。
- 只能对 Eloquent
Collection调用，即必须在get()之后：User::where(...)->get()->append(['full_name'])；where()->append()->get()会直接报错 - 单个模型也能用：
$user->append('permissions')->toArray()，但注意它返回新实例，原对象不变 - 名称仍需小写下划线，Laravel 自动匹配
getXXXAttribute()；若字段被$hidden拦住，得先$user->makeVisible(['permissions'])，再append()，顺序不能反 - 不调用
append()就不执行访问器，彻底规避“为不用的字段买单”
API Resource 里 $appends 完全不生效
JsonResource 是独立转换层，它不读取模型的 $appends 配置。即使模型定义了 $appends = ['avatar_url']，Resource 的 toArray() 也不会自动包含它。
- 必须手动在 Resource 的
toArray()中写：'avatar_url' => $this->avatar_url，靠这行触发访问器 - 不要在 Resource 里重写逻辑（比如再拼一次
first_name . last_name），否则维护成本翻倍、测试难覆盖 - 如果字段依赖当前用户（如
is_favorited），别在模型访问器里硬写auth()->id()；应在 Resource 构造时传参，或用with()注入上下文 - 关联字段（如
$this->posts->count()）未预加载，依然会触发 N+1——该用withCount('posts')的地方不能省
哪些字段根本不该塞进 $appends
运行时才确定的值（比如权限判断、请求头校验、缓存键生成）、涉及数据库查询的字段、或只在某几个接口需要的字段，硬塞进 $appends 会导致逻辑耦合、性能不可控、调试困难。
- 依赖请求上下文的字段（如
is_favorited），应优先用 Resource 层处理，或通过append()+ 运行时访问器实现 - 需要查库的字段（如
getOrderCountAttribute()），必须提前用withCount()或selectRaw()预加载，访问器里只读属性 - 敏感字段（如
raw_data）不该靠$appends控制可见性，而该用makeVisible()按角色动态暴露 - 字段名和访问器命名不一致、
$casts覆盖了同名字段、模型用了toArray()以外的方式转数组（如json_encode($model)），都会让$appends失效
