PHP Academy · 课时

API 资源与 JSON 响应

使用 Eloquent API Resources 和 ResourceCollections 构造 JSON 输出。

API 资源与 JSON 响应 是 CoddyKit 上的免费 PHP Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 PHP Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 PHP Academy 课程共包含 4 节课。

什么是 API 资源？

Eloquent API Resources 可将模型和集合转换为可直接生成 JSON 的数组，让您完全控制 API 响应的结构。

生成资源

使用 Artisan 创建资源类。

$ php artisan make:resource UserResource
# For collections:
$ php artisan make:resource UserCollection

基本资源

重写 toArray() 以定义 JSON 结构。

<?php
namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            "id"         => $this->id,
            "name"       => $this->name,
            "email"      => $this->email,
            "created_at" => $this->created_at->toISOString(),
        ];
    }
}

返回资源

从控制器返回资源——它会自动将模型包装在 data 键中。

<?php
public function show(User $user): UserResource
{
    return new UserResource($user);
}
// Response: {"data": {"id": 1, "name": "Alice", ...}}

资源集合

使用 ::collection() 包装模型集合。

<?php
public function index(): AnonymousResourceCollection
{
    return UserResource::collection(User::paginate(15));
}

条件字段

使用 when()，仅在满足条件时包含字段。

<?php
return [
    "id"    => $this->id,
    "email" => $this->when($request->user()?->isAdmin(), $this->email),
    "token" => $this->whenLoaded("tokens", $this->tokens->first()->plainTextToken),
];

whenLoaded()

仅当关联已经加载时才有条件地包含该关联，从而避免资源响应中的 N+1 问题。

<?php
return [
    "id"      => $this->id,
    "posts"   => PostResource::collection($this->whenLoaded("posts")),
    "profile" => new ProfileResource($this->whenLoaded("profile")),
];

嵌套资源

将资源嵌套在其他资源中，以构建内容丰富且类型明确的响应结构。

<?php
return [
    "id"     => $this->id,
    "author" => new UserResource($this->author),
    "tags"   => TagResource::collection($this->tags),
];

附加元数据

通过重写 with() 向响应添加元数据。

<?php
public function with($request): array
{
    return [
        "meta" => ["version" => "1.0"],
    ];
}

包装

默认情况下，资源会包装在 data 键中。使用 JsonResource::withoutWrapping() 可以全局禁用包装。

<?php
// In AppServiceProvider::boot():
JsonResource::withoutWrapping();

资源中的分页

将分页器传递给资源集合时，分页元数据会自动包含在内。

<?php
return UserResource::collection(User::paginate(15));
// Response includes: data[], links{}, meta{}

测试资源

在测试中使用 assertJson() 或 assertJsonStructure() 断言资源结构。

<?php
$response->assertJsonStructure([
    "data" => ["id", "name", "email"]
]);

总结

API 资源控制 JSON 输出结构。使用 when() 和 whenLoaded() 处理条件字段。使用嵌套资源表示关联关系。使用 ::collection() 处理多个模型。

快速检查

哪个方法仅在关联已经加载时才有条件地包含该关联？

常见问题解答

「API 资源与 JSON 响应」课时是免费的吗？

是的 — 「API 资源与 JSON 响应」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 PHP Academy 课程的其余内容，请升级到 CoddyKit PRO。 PHP Academy 课程共包含 4 节课。

「API 资源与 JSON 响应」这节课中我会学到什么？

使用 Eloquent API Resources 和 ResourceCollections 构造 JSON 输出。你通过在浏览器中直接运行的动手代码来练习 PHP Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 PHP Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 PHP Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「API 资源与 JSON 响应」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 PHP Academy 课中编写并运行代码吗？

能。每节 PHP Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 PHP Academy