[laravel] Resource的設計理念

Photo by Christopher Gower on Unsplash

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

為什麼 API 需要使用 Resource？

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

1. 程式碼雜亂 - Controller 變得難以維護，業務邏輯與資料轉換混在一起。
2. 重複的資料處理邏輯 - 多個 Controller 可能都需要處理相似的 API 輸出格式，造成重複程式碼。
3. 缺乏統一性 - 如果 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);
    }
}

總結

• Resource 可用來處理 API 輸出格式，避免在 Controller 內部寫過多的資料轉換邏輯。
• 類似於 Web 開發中的 Presenter，讓 API 的輸出變得更有結構且易於維護。
• 透過 Resource Collection 處理多筆資料，確保 API 回應的統一性。

這樣的設計不僅讓 API 更加清晰，也提升了可讀性與擴展性！