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输出中，就像它是一个真实的数据库字段一样。这对于构建更语义化、更方便前端消费的数据接口来说，是个很棒的特性。
本文档主要讲述的是JSON.NET 简单的使用；JSON.NET使用来将.NET中的对象转换为JSON字符串（序列化），或者将JSON字符串转换为.NET中已有类型的对象（反序列化？）。希望本文档会给有需要的朋友带来帮助；感兴趣的朋友可以过来看看
自定义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 App\Http\Resources;
use Illuminate\Http\Resources\Json\JsonResource;
class UserResource extends JsonResource
{
/**
* Transform the resource into an array.
*
* @param \Illuminate\Http\Request $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 App\Http\Resources\UserResource;
// ...
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 App\Casts;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
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. 序列化不必要的数据： 有时模型包含大量字段，或者关联关系嵌套很深，但前端实际上只需要其中一小部分。将所有数据都序列化并传输
