Laravel模型转JSON的核心在于toArray()与toJson()方法，前者将模型及关联递归转为数组，后者将其编码为JSON字符串。通过$casts可实现类型自动转换，如日期格式化。为控制输出字段，可使用$hidden或$visible属性实现黑名单或白名单机制，并可通过makeHidden()或makeVisible()动态调整。需添加非数据库字段时，可用$appends结合访问器返回计算值。深度定制可重写toArray()方法，但更推荐使用API Resources分离转换逻辑，支持条件输出（如when、whenLoaded）和嵌套资源，提升可维护性。此外，自定义Cast类（如加密字段）可在序列化前处理敏感数据。性能方面，N+1查询是主要陷阱，应通过with()预加载关联数据避免；同时应避免序列化冗余字段，精简传输数据以提升API效率。
Laravel模型转换为JSON，这事儿说起来简单，背后却藏着不少学问。核心上，Laravel模型提供了一套非常方便的机制来把数据库里的数据变成JSON格式，方便API接口传输或者前端消费。而JSON序列化本身，就是把一个数据结构（比如PHP的数组或对象）转换成JSON字符串的过程，这在Web开发里简直是家常便饭。
谈到Laravel模型，我们通常会接触到
toArray()
和
toJson()
这两个方法。
toJson()
其实就是调用了
toArray()
之后，再把结果通过PHP内置的
json_encode()
函数转换成JSON字符串。所以，理解
toArray()
的行为至关重要。
toArray()
方法会递归地将模型及其关联关系转换为一个纯粹的PHP数组。它会自动处理模型的属性，包括通过
$casts
定义的类型转换。比如，如果你有一个
User
模型，里面有个
email_verified_at
字段被
casts
为
datetime
，那么在
toArray()
时它就会被格式化成日期字符串。
更深一层看，JSON序列化，本质上就是数据结构的扁平化和标准化。PHP的
json_encode()
函数在处理数组和对象时，会遵循JSON规范：键值对、数组、字符串、数字、布尔值、null。它会遍历传入的数据，将PHP的数据类型映射到对应的JSON类型。例如，PHP的关联数组会变成JSON对象，索引数组会变成JSON数组，字符串、数字、布尔值、null则直接转换。
所以，当Laravel模型调用
toJson()
时，它首先构建了一个PHP数组（通过
toArray()
），这个数组里包含了模型自身的属性、通过
$appends
追加的访问器属性，以及它显式加载的关联模型数据。然后，这个庞大的PHP数组被
json_encode()
处理，最终成为我们API响应中看到的JSON字符串。这个过程看似一步到位，实则包含了模型属性筛选、类型转换、关联数据加载等多个环节的精心编排。
如何精确控制Laravel模型JSON输出的字段？
在实际开发中，我们很少需要把模型的所有字段都暴露给前端。出于安全、性能或者仅仅是数据简洁的考虑，控制JSON输出的字段显得尤为重要。Laravel在这方面提供了非常灵活的机制。
最直接的方式是使用
$hidden
和
$visible
属性。
$hidden
：顾名思义，就是隐藏。在模型中定义一个
$hidden
数组，里面列出你不想在JSON输出中出现的字段。比如，密码哈希值、内部标识符等，通常都会被隐藏。
class User extends Model{ protected $hidden = [ 'password', 'remember_token', ];}
这样一来，无论何时将
User
模型序列化为JSON，
password
和
remember_token
字段都不会出现。
$visible
：与
$hidden
相反，它定义了哪些字段应该被显示。如果你想采用白名单模式，只允许特定字段输出，
$visible
就派上用场了。
class Product extends Model{ protected $visible = [ 'id', 'name', 'price', ];}
这里只有
id
,
name
,
price
会被序列化，其他字段一概忽略。需要注意的是，
$hidden
和
$visible
是互斥的，通常我们只选择其中一个来使用。
此外，我们还可以动态地控制字段。比如，在查询之后，你可以使用
makeHidden()
或
makeVisible()
方法来临时调整模型的可见性。
$user = User::find(1);$user->makeHidden('email'); // 临时隐藏email字段return $user->toJson();
这种动态调整在某些特定API场景下非常有用，比如管理员接口可能需要更多信息，而普通用户接口则需要更少。
还有一种情况，我们可能需要将一些并非数据库字段，但由模型计算得出的值包含在JSON输出中。这时就得用到
$appends
属性和Accessors（访问器）。
class User extends Model{ protected $appends = ['full_name']; // 声明要追加的访问器 public function getFullNameAttribute() { return $this->first_name . ' ' . $this->last_name; }}
当模型被序列化时，
full_name
这个通过
getFullNameAttribute
方法计算出来的值，就会被自动添加到JSON输出中，就像它是一个真实的数据库字段一样。这对于构建更语义化、更方便前端消费的数据接口来说，是个很棒的特性。
自定义Laravel模型的JSON序列化逻辑有哪些高级技巧？
有时候，Laravel提供的
$hidden
、
$visible
和
$appends
可能还不够满足我们复杂的需求。比如，某个字段需要根据用户角色显示不同的值，或者某个关联关系需要以非常特定的结构输出。这时候，我们就需要更高级的自定义手段了。
一个常见的做法是直接重写模型的
toArray()
方法。这是最粗暴但也最灵活的方式。
class Post extends Model{ public function toArray() { $array = parent::toArray(); // 获取默认的数组表示 // 根据业务逻辑修改或添加字段 $array['author_name'] = $this->user->name ?? '未知作者'; unset($array['user_id']); // 移除原始的user_id字段 // 如果需要，可以条件性地添加关联数据 if (request()->has('include_comments')) { $array['comments_count'] = $this->comments()->count(); } return $array; }}
通过重写
toArray()
，你几乎可以完全掌控模型如何转换为数组，从而间接控制JSON输出。但这种方式也有缺点，它可能让模型变得臃肿，并且难以复用。
为了解决复用性和结构化问题，Laravel引入了API Resources。这是一种更优雅、更推荐的方式来构建复杂的JSON响应。Resources允许你将模型的转换逻辑封装到一个独立的类中，这使得API响应的结构定义变得清晰且可维护。
// app/Http/Resources/UserResource.phpnamespace AppHttpResources;use IlluminateHttpResourcesJsonJsonResource;class UserResource extends JsonResource{ /** * Transform the resource into an array. * * @param IlluminateHttpRequest $request * @return array */ public function toArray($request) { return [ 'id' => $this->id, 'name' => $this->name, 'email' => $this->email, 'created_at' => $this->created_at->format('Y-m-d H:i:s'), 'posts' => PostResource::collection($this->whenLoaded('posts')), // 条件性加载关联 'roles' => $this->when(auth()->user()->isAdmin(), $this->roles->pluck('name')), // 根据权限显示 ]; }}
在控制器中，你可以这样使用它：
use AppHttpResourcesUserResource;// ...public function show(User $user){ return new UserResource($user);}public function index(){ return UserResource::collection(User::all());}
Resources的强大之处在于它的条件性属性（
when
、
whenLoaded
），以及对关联资源的嵌套处理。它将表示层从模型中彻底分离出来，让你的API响应结构更加清晰，也更利于团队协作和长期维护。
此外，对于一些复杂的类型转换，你还可以自定义Cast类。这虽然不是直接控制JSON序列化，但它影响了模型属性的原始值，进而影响到
toArray()
的输出。比如，你可以创建一个
EncryptedStringCast
来自动加密/解密某个字段。
// app/Casts/EncryptedString.phpnamespace AppCasts;use IlluminateContractsDatabaseEloquentCastsAttributes;class EncryptedString implements CastsAttributes{ public function get($model, $key, $value, array $attributes) { return decrypt($value); } public function set($model, $key, $value, array $attributes) { return encrypt($value); }}// 在模型中使用class SensitiveData extends Model{ protected $casts = [ 'secret_info' => EncryptedString::class, ];}
这样，
secret_info
字段在模型内部始终是解密状态，但在保存到数据库时会自动加密，取出时自动解密。当模型被序列化时，
secret_info
将输出其解密后的值。这在处理敏感数据时非常有用，且对序列化过程是透明的。
JSON序列化过程中常见的性能陷阱与优化策略？
JSON序列化看似一个简单的转换过程，但在处理大量数据或复杂关联时，很容易成为性能瓶颈。我见过不少因为序列化不当导致API响应缓慢的案例，所以理解并规避这些陷阱非常关键。
1. N+1查询问题： 这是最经典的性能杀手之一。当你序列化一个模型集合，并且每个模型都需要加载一个关联关系时，如果没有进行预加载（Eager Loading），就会产生N+1次数据库查询（1次查询所有模型，N次查询每个模型的关联）。
// 糟糕的例子：N+1查询$posts = Post::all();foreach ($posts as $post) { echo $post->user->name; // 每次循环都会查询用户}return $posts->toJson(); // 如果PostResource里也加载了user，也会触发N+1
优化策略： 使用
with()
或
load()
进行预加载。
// 优化后的例子：预加载$posts = Post::with('user')->get();return $posts->toJson(); // 或者在PostResource里使用whenLoaded
预加载能将关联查询的数量大幅减少，显著提升性能。
2. 序列化不必要的数据： 有时模型包含大量字段，或者关联关系嵌套很深，但前端实际上只需要其中一小部分。将所有数据都序列化并传输
以上就是Laravel模型JSON序列化？JSON如何序列化？的详细内容，更多请关注php中文网其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/147619.html
微信扫一扫 
支付宝扫一扫 
