📖 13주차 01강: 모바일 RESTful API 설계, Eloquent API 리소스 & 직렬화(Serialization)

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Book extends Model
{
    /**
     * JSON 직렬화 시 자동으로 숨길 민감 속성들
     */
    protected $hidden = [
        'cost_price',      // 도서 원가 (서점 영업 비밀)
        'internal_memo',   // 관리자 전용 내부 메모
        'deleted_at',
    ];

    /**
     * JSON 직렬화 시 자동으로 계산되어 포함될 가상 속성
     */
    protected $appends = [
        'discount_rate_text',
        'is_new_release',
    ];

    /**
     * 가상 속성 접근자: 할인율 텍스트 (예: "15% 할인")
     */
    public function getDiscountRateTextAttribute(): ?string
    {
        if ($this->original_price && $this->price < $this->original_price) {
            $rate = round((($this->original_price - $this->price) / $this->original_price) * 100);
            return "{$rate}% 할인";
        }
        return null;
    }

    /**
     * 가상 속성 접근자: 출간 30일 이내 신간 여부
     */
    public function getIsNewReleaseAttribute(): bool
    {
        return $this->published_at && $this->published_at->gt(now()->subDays(30));
    }
}

<?php

namespace App\Http\Resources;

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

class AuthorResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'profile_photo_url' => $this->profile_photo_url ? url($this->profile_photo_url) : null,
        ];
    }
}

<?php

namespace App\Http\Resources;

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

class BookResource extends JsonResource
{
    /**
     * 모델 데이터를 JSON 응답 배열로 변환
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'isbn' => $this->isbn,
            'title' => $this->title,
            'summary' => $this->summary,
            'cover_image' => $this->cover_image ? url($this->cover_image) : null,
            'pricing' => [
                'original_price' => (int) $this->original_price,
                'price' => (int) $this->price,
                'discount_badge' => $this->discount_rate_text,
                'currency' => 'KRW',
            ],
            'stock' => [
                'quantity' => (int) $this->stock,
                'is_in_stock' => $this->stock > 0,
            ],
            'flags' => [
                'is_new' => $this->is_new_release,
                'is_bestseller' => (bool) $this->is_bestseller,
            ],
            // 관계가 컨트롤러에서 Eager Loading(with) 되었을 때만 포함
            'authors' => AuthorResource::collection($this->whenLoaded('authors')),
            'publisher' => $this->whenLoaded('publisher', fn () => [
                'id' => $this->publisher->id,
                'name' => $this->publisher->name,
            ]),
            // 관리자 권한이 있는 요청자에게만 조건부로 상세 메트릭 노출
            'admin_metrics' => $this->when($request->user()?->is_admin, [
                'total_sales_count' => (int) $this->sales_count,
                'view_count' => (int) $this->views,
            ]),
            'published_at' => $this->published_at?->format('Y-m-d'),
        ];
    }
}

<?php

namespace App\Http\Controllers\Api\v1;

use App\Http\Controllers\Controller;
use App\Http\Resources\BookResource;
use App\Models\Book;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

class BookApiController extends Controller
{
    /**
     * 도서 목록 조회 (검색, 카테고리 필터링, 페이지네이션)
     * GET /api/v1/books
     */
    public function index(Request $request): AnonymousResourceCollection
    {
        $books = Book::with(['authors', 'publisher'])
            ->when($request->category_id, fn ($q, $id) => $q->where('category_id', $id))
            ->where('is_sold_out', false)
            ->latest('published_at')
            ->paginate($request->input('per_page', 15));

        return BookResource::collection($books);
    }

    /**
     * 도서 단건 상세 조회
     * GET /api/v1/books/{book}
     */
    public function show(Book $book): BookResource
    {
        $book->load(['authors', 'publisher', 'reviews.user']);

        return new BookResource($book);
    }
}

use App\Http\Controllers\Api\v1\BookApiController;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')->group(function () {
    Route::get('/books', [BookApiController::class, 'index']);
    Route::get('/books/{book}', [BookApiController::class, 'show']);
});

use Illuminate\Http\Resources\Json\JsonResource;

public function boot(): void
{
    JsonResource::withoutWrapping();
}