[laravel] Resource的設計理念

更新於 2025/03/20發佈於 2025/03/20閱讀時間約 6 分鐘

在 Laravel 開發 API 時，直接在 Controller 內進行資料加工可能會讓程式碼變得雜亂且難以維護。因此，Laravel 提供 Resource (資源轉換器) 來解決這個問題，讓我們可以統一管理 API 的輸出格式，將模型model或模型集合collection轉換為適合 API 輸出的格式，並在需要時對資料進行處理。

為什麼 API 需要使用 Resource？

在 Web 開發中，前端通常透過 View + Presenter 來決定如何呈現資料。

Controller 負責處理請求並傳遞資料
View / Presenter 負責資料格式的轉換與顯示

但在 API 開發中，我們沒有 View 層，因此通常需要在 Controller 內處理資料轉換，這導致：

程式碼雜亂 - Controller 變得難以維護，業務邏輯與資料轉換混在一起。
重複的資料處理邏輯 - 多個 Controller 可能都需要處理相似的 API 輸出格式，造成重複程式碼。
缺乏統一性 - 如果 API 輸出格式不統一，前端開發者可能需要額外處理不同的 API 風格。

Laravel Resource 的應用

Laravel 提供了 Resource 來解決這個問題，它的作用類似於 Web 開發中的 Presenter。

用途

作為資料轉換層，將模型轉換為一致的 API 響應格式
控制輸出哪些屬性，格式化數據（如四捨五入、類型轉換）
處理關聯數據的輸出

優點

統一 API 輸出格式
數據轉換和格式化
條件性輸出控制
安全性（隱藏敏感數據）
關聯數據精確控制
簡化 Controller

實戰練習

1. 建立 Resource 類別

Laravel 提供 php artisan make:resource 指令來建立 Resource：

php artisan make:resource UserResource

這會在 app/Http/Resources 目錄下建立 UserResource.php。

2. 修改 Resource

開啟 UserResource.php，修改 toArray 方法來決定 API 的輸出格式：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at->toDateTimeString(),
            'profile' => new ProfileResource($this->whenLoaded('profile')), // 若有載入關聯，則回傳 Profile
        ];
    }
}

這樣，我們就能夠在 UserResource 內部處理資料的格式轉換，而不需要在 Controller 內部寫這些邏輯。

3. 在 Controller 中使用 Resource

在 UserController.php 中，我們可以直接使用 UserResource 來格式化輸出：

<?php

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

class UserController extends Controller
{
    public function show($id)
    {
        $user = User::with('profile')->findOrFail($id);
        return new UserResource($user);
    }
}

若是返回多筆資料，可以使用 Resource Collection：

<?php

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

class UserController extends Controller
{
    public function index()
    {
        $users = User::with('profile')->paginate(10);
        return UserResource::collection($users);
    }
}