Laravel模型序列化？模型数据怎样序列化？

畫卷琴夢

发布时间：2025-09-03 09:35:01

989人浏览过

来源于php中文网

原创

Laravel模型序列化常用方法包括toArray()、toJson()及PHP原生serialize()。toArray()将模型转为数组，支持$hidden、$visible控制字段，自动处理访问器和关联关系；toJson()基于toArray()生成JSON字符串，适用于API响应；serialize()用于队列、缓存等场景，需注意__sleep()和__wakeup()魔术方法的使用。为避免性能问题，应预加载关联（with）、选择必要字段（select），并用API资源精细控制输出结构，防止N+1查询和数据泄露。API资源提供条件字段（when、whenLoaded）、格式化、嵌套关联等高级功能，实现关注点分离与响应优化。1. toArray()：转数组，递归处理属性、关联、访问器，遵循$hidden/$visible规则。2. toJson()：调用toArray()后json_encode，可传JSON选项。3. serialize()：用于队列/缓存，触发__sleep__/__wakeup__，慎用关联延迟加载。优化建议：预加载防N+1，select减字段，分页或游标处理大数据；用$hidden防泄露，API资源实现细粒度输出控制。

laravel模型序列化？模型数据怎样序列化？

Laravel模型序列化，说白了，就是把一个Eloquent模型对象，转换成可以存储、传输或者在不同进程间传递的格式。最常见的需求是把模型数据变成JSON字符串用于API响应，或者变成PHP原生序列化格式存入缓存、队列，甚至有时候是Session。核心目的就是把内存中的对象状态固化下来，以便后续重建或使用。模型数据怎样序列化？Laravel提供了几种非常方便的途径，让我们能灵活地处理这个过程。

解决方案

模型数据序列化，在Laravel里我们通常有几个选择，每种都有其适用场景和一些需要注意的地方。最直接的是

toArray()

和

toJson()

方法，它们是处理模型数据输出到前端或API的利器。而如果涉及到PHP内部的存储，比如队列任务或者某些缓存驱动，PHP原生的

serialize()

和

unserialize()

机制就会介入，这时模型内部的一些魔术方法就显得挺重要了。

当我们调用一个模型实例的

toArray()

方法时，它会递归地将模型及其加载的关联关系转换为一个PHP数组。这个数组会尊重模型上定义的

$hidden

和

$visible

属性，自动过滤掉不希望暴露的字段。我个人觉得，这个方法是构建API响应或者进行数据转换的基础。它给了我们一个原始的、可操作的数组结构，之后你可以对这个数组进行任意的加工。

toJson()

方法则更进一步，它本质上是先调用了

toArray()

，然后将得到的数组通过

json_encode()

函数转换成JSON字符串。对于RESTful API的开发来说，这几乎是标配。它简化了我们构建JSON响应的流程，而且同样会遵循

$hidden

和

$visible

规则，确保敏感数据不会被意外泄露。

当然，还有PHP原生的序列化。当你把一个Eloquent模型实例直接扔进Laravel的队列系统（例如Redis或Database驱动）或者某些缓存驱动时，PHP会尝试使用

serialize()

函数将其转换为一个字符串。这时，模型类如果定义了

__sleep()

和

__wakeup()

这两个魔术方法，就能在序列化和反序列化过程中执行一些自定义逻辑。

__sleep()

可以让我们指定哪些属性需要被序列化，这对于避免序列化一些不必要的、可能导致问题的资源句柄或者大型对象非常有用。而

__wakeup()

则可以在反序列化后，重新建立一些必要的连接或恢复状态。这里有个小坑，如果模型在序列化时没有加载某些关联关系，反序列化后直接访问这些关系可能会触发N+1查询问题，甚至在某些情况下，如果关联模型被删除，反序列化后可能会导致数据不一致。所以，对于队列任务，我通常会倾向于只传递模型ID，然后在任务内部重新查询模型，这样可以保证获取到最新状态的数据。

Laravel模型数据序列化有哪些常用方法？

在Laravel中，序列化模型数据主要有以下几种常用方法，每种都有其独特之处和最佳实践场景。

toArray()

方法

这是将Eloquent模型转换为PHP数组的核心方法。它会递归地处理模型的所有属性和已加载的关联关系。

如何使用：

$user = App\Models\User::find(1);
$userData = $user->toArray();
// $userData 现在是一个PHP关联数组

控制输出：
- $hidden
  属性：在模型中定义
```
protected $hidden = ['password', 'remember_token'];
```
  ，这些字段在
```
toArray()
```
  输出时会被自动排除。这对于防止敏感信息泄露至关重要。
- $visible
  属性：如果你只想暴露极少数字段，可以使用
```
protected $visible = ['id', 'name'];
```
  ，那么只有这些字段会被包含。
- makeHidden()
  /
  makeVisible()
  ：运行时动态调整隐藏/可见字段。
```
$user->makeHidden(['email_verified_at'])->toArray();
```
关联关系： 如果模型加载了关联关系（例如
```
$user->load('posts')
```
），
```
toArray()
```
也会将这些关联模型一并转换为数组。
访问器（Accessors）： 模型中定义的访问器（
```
getFooAttribute()
```
）在
```
toArray()
```
时会被自动调用，并将其结果作为字段包含在输出数组中。这非常方便，可以用来格式化数据或添加派生属性。

toJson()

方法

这是将Eloquent模型转换为JSON字符串的便捷方法。它内部会先调用

toArray()

，然后将结果通过

json_encode()

转换为JSON。

如何使用：

$user = App\Models\User::find(1);
$jsonString = $user->toJson();
// $jsonString 是一个JSON格式的字符串

与
toArray()
的关系：
```
toJson()
```
是
```
toArray()
```
的封装，所以
```
$hidden
```
、
```
$visible
```
、访问器等规则同样适用。
JSON选项：
```
toJson()
```
方法可以接受
```
json_encode()
```
的第二个参数，允许你传递JSON编码选项，比如
```
JSON_PRETTY_PRINT
```
用于美化输出。
```
$user->toJson(JSON_PRETTY_PRINT);
```

3. PHP原生

serialize()

/
unserialize()

当Laravel需要将整个模型对象存储到非结构化介质中时，比如队列任务、一些文件或Redis缓存（如果不是以JSON形式存储），就会用到PHP的内置序列化机制。

使用场景：
- 队列任务： 当你将一个模型实例作为参数传递给一个可序列化的任务类时，Laravel会尝试序列化这个模型。
- Session / Cache： 某些驱动可能会将整个对象序列化后存储。
魔术方法
__sleep()
和
__wakeup()
：
- __sleep()
  ：在对象被序列化之前调用。它必须返回一个包含对象中所有需要被序列化的属性名的数组。这可以用来清理不必要的资源，或者避免序列化大型、复杂或无法序列化的属性。
- __wakeup()
  ：在对象被反序列化之后调用。它通常用于重建在序列化过程中被关闭的数据库连接、文件句柄等资源，或者重新初始化一些瞬态属性。
注意事项： 使用原生序列化时，要特别小心延迟加载的关联关系。如果模型被序列化时某个关联关系没有加载，反序列化后尝试访问它可能会触发数据库查询。更糟糕的是，如果关联模型在序列化后被删除，反序列化可能会导致引用一个不存在的资源，引发错误或不一致。所以，我个人在队列任务中更倾向于传递模型ID而不是整个模型，让任务内部重新查询，这样可以保证数据的实时性和准确性。

处理Laravel模型序列化时，如何避免性能问题或数据泄露？

模型序列化虽然方便，但如果不加注意，很容易引入性能瓶颈或安全漏洞。这方面，我有一些实践经验可以分享。

避免性能问题：

N+1 查询问题： 这是最常见的性能杀手。当你序列化一个模型集合时，如果每个模型都包含需要延迟加载的关联关系，那么在序列化每个模型时，都会单独执行一次数据库查询来获取其关联数据。这会导致大量不必要的查询。
- 解决方案： 始终使用
```
with()
```
  方法进行预加载（Eager Loading）。
```
// 避免N+1
$users = App\Models\User::with('posts')->get();
// 此时 $users 及其所有关联的 posts 都已加载
$users->toJson(); // 序列化时不会再触发额外查询
```
  预加载能够一次性获取所有关联数据，显著减少数据库往返次数。
只选择必要的字段： 如果你只需要模型中的几个字段，而不是所有字段，就不要加载所有字段。
- 解决方案： 使用
```
select()
```
  方法。
```
$users = App\Models\User::select('id', 'name', 'email')->get();
$users->toJson();
```
  这可以减少从数据库传输的数据量，尤其是在处理大量记录时效果显著。
分页和惰性加载： 对于大型数据集，一次性加载所有模型并序列化是不现实的。
- 解决方案： 使用
```
paginate()
```
  或
```
cursor()
```
  方法。
  - ```
  paginate()
```
  ：用于Web分页，只加载当前页的数据。
- ```
cursor()
```
    ：用于处理大量记录而不需要分页时，它会一次只从数据库加载一条记录，减少内存占用。
```
$users = App\Models\User::cursor(); // 惰性加载
foreach ($users as $user) {
// 处理并序列化单个用户
echo $user->toJson();
}
```

避免数据泄露：

```
$hidden
```
和
$visible
属性：这是Laravel提供最直接、最基础的防范措施。在模型中明确定义哪些字段不应该被序列化输出。

序列猴子开放平台
具有长序列、多模态、单模型、大数据等特点的超大规模语言模型

下载
```
class User extends Model
{
    protected $hidden = [
        'password',
        'remember_token',
        'two_factor_secret', // 敏感信息
        'two_factor_recovery_codes',
    ];
}
```
这是一个好习惯，几乎所有模型都应该有这个属性。
API 资源（API Resources）： 对于复杂的API响应，仅仅依靠
```
$hidden
```
可能不够灵活。API资源提供了一个更强大、更细粒度的控制层。它允许你完全自定义模型的JSON输出结构，包括哪些字段被包含、如何格式化，甚至基于条件包含字段。
- 使用场景： 当你的API响应需要与模型内部结构有所不同，或者需要根据用户角色、请求参数等条件动态调整输出时，API资源是我的首选。我会在下一个副标题详细讲讲这个。
自定义 Accessor： 如果你需要对某个字段进行格式化或者在输出时进行一些逻辑判断，可以使用Accessors。
```
class User extends Model
{
    public function getIsAdminAttribute()
    {
        return $this->attributes['role'] === 'admin';
    }
}
// 当序列化时，会包含 'is_admin' 字段
```
但要注意，不要在Accessor中引入敏感逻辑或暴露不该暴露的数据。
避免在客户端存储敏感序列化数据： 无论你做了多少防护，如果将完整的序列化模型（即使是经过过滤的）存储在客户端（例如LocalStorage、Cookie），总是有潜在风险。只存储必要的、非敏感的数据，或者只存储模型ID，让客户端通过API按需获取最新数据。

Laravel API资源如何优化模型序列化输出？

在我看来，当你的应用逐渐复杂，特别是构建API时，Laravel的API资源（API Resources）几乎是不可或缺的。它提供了一个专门的层来转换模型数据到JSON响应，远比直接使用

toArray()

或

toJson()

来得优雅和强大。它解决了模型序列化输出的许多痛点，让你的API响应更清晰、更可控。

为什么需要API资源？

想象一下，你的

User

模型有很多字段，比如

password

、

email_verified_at

、

created_at

、

updated_at

等等。在不同的API接口中，你可能需要展示不同的信息：

用户列表可能只需要
```
id
```
、
```
name
```
、
```
email
```
。
用户详情可能需要更多字段，比如
```
address
```
、
```
phone
```
，以及关联的
```
posts
```
。
管理员接口可能需要所有字段，包括
```
email_verified_at
```
。

如果仅仅依赖

$hidden

和

$visible

，你可能需要创建多个模型或者在每个控制器中手动处理数组，这很快就会变得混乱和难以维护。API资源就是为了解决这个痛点而生。

API资源的核心优势：

关注点分离： 将模型数据转换的逻辑从模型本身或控制器中剥离出来，放在专门的资源类中。这让代码更清晰，模型专注于数据存储，控制器专注于请求处理。
细粒度控制： 你可以精确地定义每个字段如何呈现，包括字段名、格式化、甚至计算新字段。
条件性字段： 轻松实现根据条件（如用户权限、请求参数）包含或排除某些字段。
关联关系嵌套： 优雅地处理关联模型的序列化，甚至可以为关联模型使用不同的资源类。
可复用性： 创建一次资源类，可以在多个API端点中复用。

如何使用API资源？

创建资源类：

php artisan make:resource UserResource

这会在

app/Http/Resources

目录下创建一个

UserResource.php

文件。

定义资源结构： 在

UserResource

类的

toArray()

方法中，定义你希望输出的JSON结构。

// 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|\Illuminate\Contracts\Support\Arrayable|\JsonSerializable
     */
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'is_admin' => (bool) $this->when($this->role === 'admin', true), // 条件性字段
            'created_at' => $this->created_at->format('Y-m-d H:i:s'), // 格式化日期
            'posts_count' => $this->whenLoaded('posts', $this->posts->count()), // 仅在 posts 被加载时包含
            'posts' => PostResource::collection($this->whenLoaded('posts')), // 嵌套关联资源
        ];
    }
}

这里我用了

$this->when()

和

$this->whenLoaded()

，它们是API资源中非常强大的工具：

$this->when(condition, value)

：当

condition

为真时，包含

value

。

```
$this->whenLoaded(relation, value)
```
：当指定的
```
relation
```
被预加载时，包含
```
value
```
。这对于避免N+1问题和动态调整响应非常有用。

在控制器中使用：

单个模型：

use App\Http\Resources\UserResource;
use App\Models\User;

public function show(User $user)
{
    return new UserResource($user);
}

模型集合：

use App\Http\Resources\UserResource;
use App\Models\User;

public function index()
{
    $users = User::with('posts')->paginate(10);
    return UserResource::collection($users);
}