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.php namespace 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.php namespace 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如何序列化？的详细内容，更多请关注laravel php word js 前端 json app access ai 敏感数据 键值对 php laravel json 数据类型 NULL 关联数组 封装 标识符 字符串 递归 数据结构 接口 Accessors 访问器 类型转换 对象 数据库