Eloquent Attribute Flattening 是开发者对“将模型中嵌套 JSON/数组属性展开为独立访问器字段”的俗称；通过 $casts + Accessor 实现安全扁平化，配合 $appends 可在 toArray() 中自动包含，需防 N+1、重复解析与循环引用。
什么是 Eloquent Attribute Flattening？
它不是 Laravel 官方术语，而是开发者对「把模型中嵌套的 JSON/数组属性展开成独立字段」这一需求的俗称。比如 user->profile 是个 JSON 字段，含 {"city": "Shanghai", "job": {"title": "Engineer"}}，你想直接用 $user->city 或 $user->job_title 访问，而不是写 $user->profile['city'] 或 data_get($user->profile, 'job.title')。
用 Accessor + cast 实现安全扁平化
这是最可控、兼容性最好的方式，不破坏原始字段，也不依赖第三方包。核心是：在模型里定义访问器（Accessor），同时配合 $casts 确保 JSON 字段被正确反序列化为数组。
-
$casts = ['profile' => 'array']必须设置，否则$this->profile是字符串，data_get()会失效 - 访问器名必须符合 Laravel 命名规范（驼峰转下划线），如想暴露
job_title，就写getJobTitleAttribute() - 避免在访问器里做 heavy 操作（如 DB 查询），它会在每次获取时触发
- 如果 JSON 结构可能为空或缺失键，务必用
data_get($this->profile, 'job.title', '')而非直接链式访问，防止 Notice
示例：
class User extends Model
{
protected $casts = [
'profile' => 'array',
];
public function getCityAttribute()
{
return data_get($this->profile, 'city', '');
}
public function getJobTitleAttribute()
{
return data_get($this->profile, 'job.title', '');
}
}
用 $appends + toArray() 自动包含扁平字段
当你需要把扁平字段一起输出（比如 API 返回），不能只靠访问器 —— Laravel 默认不会把访问器塞进 toArray()，得显式声明 $appends。
立即学习“PHP免费学习笔记（深入）”；
-
$appends = ['city', 'job_title']中的键名必须和访问器去掉get/Attribute后的名称一致 - 如果某个扁平字段只在特定场景需要（比如管理后台），不要加进
$appends，否则每次toArray()都会执行对应访问器，影响性能 - 注意：
$appends对toJson()和 API Resource 也生效，但 Resource 可以覆盖控制，优先用 Resource 的toArray()手动组装更清晰
警惕 toArray() 时的循环引用与性能陷阱
扁平化本身不重，但若在访问器里调用另一个模型关系（如 $this->posts->count()），再放进 $appends，会导致 N+1 和内存暴涨。常见错误包括：
- 在
getFullNameAttribute()里调用$this->relation->name，而该关系未预加载 - 用
json_decode($this->json_field, true)替代$casts，导致每次访问都重复解析 - 把整个嵌套数组用
array_merge()展开后赋给$appends，失去字段粒度控制，且无法单独缓存
真正要扁平多层嵌套（如 3 级以上）又频繁使用时，建议提前在数据库加冗余字段，用模型事件自动维护，而不是 runtime 解析。
