Laravel API Resources: A Standard Response Envelope (Guide)

Siri: Setiap Projek Laravel Perlu Ada Blok Binaan Ini Bahagian: 33 daripada 35 Tahap: Pemula–Pertengahan Prasyarat: Controller nipis

Apa yang Anda Akan Pelajari

  • Kenapa mengembalikan model Eloquent mentah daripada API adalah kesilapan
  • Sampul respons standard: {“success”: bool, “message”: string, “data”: {}}
  • Membina BaseApiResource untuk struktur yang konsisten
  • Resource Collections dan pagination
  • Nested resources dan relationship
  • Helper ApiResponse untuk respons bukan resource

Masalah dengan Model Eloquent Mentah

Ini ada dalam codebase setiap pemula:

// ❌ Never do this
public function show(Order $order): JsonResponse
{
return response()->json($order);
}

Apa masalahnya?

  1. Mendedahkan skema pangkalan data anda – nama lajur menjadi sebahagian daripada kontrak API anda. Tukar nama satu lajur, semua klien akan rosak.
  2. Membocorkan data sensitif – password, remember_token, stripe_customer_id semuanya disertakan kecuali anda menyembunyikannya secara eksplisit.
  3. Tiada kawalan versi – anda tidak boleh menambah medan baharu pada model tanpa ia muncul dalam API.
  4. Bentuk tidak konsisten – endpoint berbeza kembalikan struktur berbeza tanpa sampul standard.

API Resources menyelesaikan keempat-empat masalah ini.

Sampul Standard

Setiap respons API dalam projek-projek ini mengikut bentuk berikut:

{
"success": true,
"message": "Order retrieved successfully.",
"data": {
"id": 123,
"status": "pending",
"total": "$250.00"
}
}

Untuk senarai:

{
"success": true,
"message": "Orders retrieved successfully.",
"data": [...],
"meta": {
"current_page": 1,
"last_page": 5,
"per_page": 15,
"total": 74
}
}

Untuk ralat:

{
"success": false,
"message": "Order not found.",
"data": null
}

BaseApiResource

Kelas asas yang menguatkuasakan sampul pada setiap resource:

// app/Http/Resources/BaseApiResource.php

declare(strict_types=1);

namespace App\Http\Resources;

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

abstract class BaseApiResource extends JsonResource
{
/**
* The success message for this resource.
*/
protected string $message = 'Data retrieved successfully.';

/**
* Subclasses define the actual resource fields here.
*
* @return array
*/
abstract protected function fields(Request $request): array;

/**
* The bare fields, without the envelope (used by collections).
*
* @return array
*/
final public function fieldsFor(Request $request): array
{
return $this->fields($request);
}

/**
* @return array
*/
final public function toArray(Request $request): array
{
return [
'success' => true,
'message' => $this->message,
'data' => $this->fields($request),
];
}
}

Resource konkrit:

// app/Http/Resources/OrderResource.php
final class OrderResource extends BaseApiResource
{
protected string $message = 'Order retrieved successfully.';

protected function fields(Request $request): array
{
return [
'id' => $this->id,
'status' => $this->status->value,
'status_label' => $this->status->label(),
'total' => $this->total_formatted,
'item_count' => $this->items_count ?? $this->items->count(),
'created_at' => $this->created_at->toISOString(),
'customer' => [
'name' => $this->customer_name,
'email' => $this->email,
],
];
}
}

Perhatikan apa yang TIDAK ada dalam fields(): password, remember_token, jumlah integer mentah — hanya apa yang diperlukan oleh pengguna API.

Guna Resources dalam Controller

public function show(Order $order): OrderResource
{
Gate::authorize('view', $order); // $this->authorize() needs AuthorizesRequests on Laravel 11+

$order->loadMissing(['items', 'user']);

return new OrderResource($order);
}

public function store(StoreOrderRequest $request): JsonResponse
{
$order = $this->createOrder->execute(
$request->user(),
OrderCustomerData::fromArray($request->validated())
);

return (new OrderResource($order))
->response()
->setStatusCode(201);
}

Resource Collections dengan Pagination

Untuk endpoint senarai:

// app/Http/Resources/OrderCollection.php
final class OrderCollection extends ResourceCollection
{
// Untyped on purpose: ResourceCollection declares `public $collects;`,
// and redeclaring it as `public string` is a fatal error.
public $collects = OrderResource::class;

public function toArray(Request $request): array
{
return [
'success' => true,
'message' => 'Orders retrieved successfully.',
// Bare fields per item: OrderResource::toArray() would wrap
// every row in its own success/message envelope
'data' => $this->collection->map(
fn (OrderResource $order): array => $order->fieldsFor($request)
),
// `meta` and `links` are added automatically for paginated results
];
}
}

Dalam controller:

public function index(Request $request): OrderCollection
{
$orders = Order::with(['items'])
->forUser($request->user())
->latest()
->paginate(15);

return new OrderCollection($orders);
}

Nested Resources – Relationship dalam Resource

Apabila resource mengandungi model berkaitan, gunakan resource berkaitan:

// app/Http/Resources/OrderResource.php
protected function fields(Request $request): array
{
return [
'id' => $this->id,
'status' => $this->status->value,
'total' => $this->total_formatted,

// Only include when the relationship is loaded
'items' => OrderItemResource::collection(
$this->whenLoaded('items')
),

'customer' => new UserResource(
$this->whenLoaded('user')
),
];
}

$this->whenLoaded(‘items’) hanya menyertakan relationship jika ia dimuat secara eager. Ini mengelakkan masalah N+1 yang tidak disengajakan akibat pengguna API yang tidak memuat relationship.

Helper ApiResponse untuk Respons Bukan Resource

Untuk respons yang tidak melibatkan model (mesej pengesahan, hasil tindakan):

// app/Http/Responses/ApiResponse.php
final class ApiResponse
{
public static function success(string $message, mixed $data = null, int $status = 200): JsonResponse
{
return response()->json([
'success' => true,
'message' => $message,
'data' => $data,
], $status);
}

public static function error(string $message, mixed $data = null, int $status = 422): JsonResponse
{
return response()->json([
'success' => false,
'message' => $message,
'data' => $data,
], $status);
}

public static function notFound(string $message = 'Resource not found.'): JsonResponse
{
return self::error($message, status: 404);
}

public static function unauthorized(string $message = 'Unauthenticated.'): JsonResponse
{
return self::error($message, status: 401);
}

public static function forbidden(string $message = 'Forbidden.'): JsonResponse
{
return self::error($message, status: 403);
}
}

Penggunaan:

public function destroy(Order $order): JsonResponse
{
Gate::authorize('delete', $order);
$order->delete();

return ApiResponse::success('Order deleted successfully.');
}

Soalan Lazim

Kenapa guna API Resources berbanding mengembalikan model? Model mentah membocorkan lajur yang anda tambah kemudian dan merosakkan kontrak anda; Resource ialah whitelist eksplisit dan sampul yang stabil.

Bagaimana saya menambah meta pagination pada respons API Laravel? Kembalikan ResourceCollection – meta pagination (links, total, per_page) ditambah secara automatik.

Pengajaran Utama

  • Jangan sesekali kembalikan model Eloquent mentah daripada API – guna Resources untuk kawal dengan tepat apa yang didedahkan.
  • Format sampul piawai: {“success”: bool, “message”: string, “data”: {}} . Setiap endpoint, setiap respons.
  • BaseApiResource menguatkuasakan format sampul secara automatik. Subkelas hanya perlu takrifkan fields() .
  • $this->whenLoaded(‘relation’) mengelakkan masalah N+1 dalam resources bersarang.
  • OrderCollection extends ResourceCollection menambah data meta pagination pada respons senarai.
  • Helper ApiResponse untuk mesej pengesahan dan respons bukan model.

Tips dan Perangkap

⚠️ Amaran: $this->whenLoaded(‘items’) akan memulangkan MissingValue apabila relationship tidak dimuatkan – bukan null, bukan juga array kosong. Ini memang disengajakan: key tersebut dihilangkan sepenuhnya daripada respons. Jika API client anda mengharapkan key itu sentiasa ada, guna $this->items ?? [] sebagai ganti, dengan eager loading dikuatkuasakan di controller. 💡 Tip: Guna return type Resource pada method controller ( public function show(Order $order): OrderResource ) berbanding JsonResponse. Return type itu mendokumentasikan apa yang endpoint pulangkan, dan alat analisis statik boleh mengesahkan bentuknya sepadan dengan definisi Resource. 🔥 Nota Pakar: Jangan sesekali tambah logik bersyarat yang mengubah struktur respons berdasarkan pengguna yang disahkan di dalam Resource. Resource dengan logik “jika admin, tunjukkan field tambahan” tidak boleh diuji dan menghasilkan kontrak API yang tidak konsisten. Guna Resources berasingan ( AdminOrderResource extends OrderResource ) untuk paras kebenaran yang berbeza.

Bacaan Lanjut

  • Dokumen Laravel: Eloquent Resources
  • Dokumen Laravel: Resource Collections
  • Dokumen Laravel: whenLoaded()
  • Spesifikasi JSON:API – format sampul piawai yang layak diketahui walaupun anda tidak menggunakannya sepenuhnya

← Strategi Pengujian | Laravel Pipeline Pattern →


Sumber Rujukan:

  • Artikel asal: Dev.to PHP
  • Diterjemah daripada artikel asal ke Bahasa Melayu oleh AI Editorial – haqis.com
Comments

Similar Posts