什么是 API Resources？

Question

什么是 API Resources？

Accepted Answer

**API Resources** 是转换类，用于控制 Eloquent 模型（和集合）如何被**序列化为 JSON** 来用于 API 响应。它们让你精确地塑造 API 输出 — 选择要公开哪些字段、重命名字段、格式化值和包含相关数据 — 将 API 表示与数据库结构解耦。

## 问题：暴露原始模型

```php
// ❌ returning a model directly exposes ALL columns (maybe including sensitive ones)
return User::find($id);   // { id, name, email, password_hash, internal_notes, ... } 😱
```

## 解决方案：API Resource

```php
<?php
// php artisan make:resource UserResource
class UserResource extends JsonResource {
    public function toArray($request): array {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            // password and internal fields deliberately OMITTED
            'joined' => $this->created_at->toDateString(),   // format a value
            'is_admin' => (bool) $this->is_admin,
            // include related data (conditionally loaded)
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}
```

```php
// use it in a controller
return new UserResource($user);                  // a single model
return UserResource::collection(User::all());     // a collection
```

Resource 的 `toArray()` 定义了 JSON 的确切形状 — 你可以控制显示哪些字段、重命名并格式化它们，以及包含相关资源。敏感字段根本不会被包含。

## 条件和嵌套数据

```php
return [
    'id' => $this->id,
    'secret' => $this->when($request->user()->isAdmin(), $this->secret),  // conditional field
    'posts' => PostResource::collection($this->whenLoaded('posts')),       // only if eager-loaded
];
```

## 为什么这很重要

API Resources 对于在 Laravel 中构建设计良好、安全的 API 至关重要 — 它们让你对 JSON 输出有精确的控制，这对**安全性**和 API 设计都很重要。

最关键的优势是**防止数据泄露**：直接返回 Eloquent 模型会暴露它们的所有列（可能包括密码哈希值、内部标志或其他敏感数据 — 这是一个严重的安全漏洞），而 API Resources 让你明确选择要暴露哪些字段，确保敏感数据永远不会到达客户端。

除了安全性之外，它们还通过**将 API 表示与数据库模式解耦**实现了简洁的 API 设计 — 你可以重命名字段、格式化值（日期、布尔值）、构造嵌套/相关数据，以及基于权限条件地包含字段，所有这些都在一个专门的转换类中进行。

这使 API 契约保持稳定和有意而为之，而不是与内部表结构耦合。

理解 API Resources — 它们如何塑造 JSON 输出、显式字段控制的安全优势，以及条件字段和嵌套资源等功能 — 对于构建专业的 Laravel API 是重要的知识，因为暴露原始模型既不安全也不是良好的设计。

由于 REST/JSON API 是当今 Laravel 的主要用途，并且控制响应形状（安全而整洁）是一个常见的、重要的需求，API Resources 是一个经常使用、价值很高的工具，它区分了设计良好、安全的 API 和那些泄露数据或紧密耦合输出与数据库的 API。