Как называются инструменты для стандартизации формата ответа в Laravel?

API Resources (Ресурсы) и API Resources Collections (Коллекции ресурсов) в Laravel

В Laravel стандартными инструментами для форматирования и стандартизации ответа API являются API Resources и API Resources Collections. Эти инструменты введены с версии Laravel 5.5 и представляют собой элегантный трансформационный слой между моделями Eloquent и JSON-ответами вашего API.

Основные компоненты системы

API Resources — это классы, которые преобразуют отдельные модели в массивы. Создаются командой:

php artisan make:resource UserResource

Пример класса ресурса:

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at->format('Y-m-d H:i:s'),
            'profile' => new ProfileResource($this->whenLoaded('profile')),
        ];
    }
}

API Resource Collections используются для форматирования коллекций моделей (пагинированных или обычных):

php artisan make:resource UserCollection --collection

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    public function toArray($request)
    {
        return [
            'data' => $this->collection,
            'meta' => [
                'total' => $this->total(),
                'per_page' => $this->perPage(),
                'current_page' => $this->currentPage(),
            ],
        ];
    }
}

Ключевые возможности и преимущества

Условные атрибуты и отношения

return [
    'name' => $this->name,
    'secret' => $this->when($request->user()->isAdmin(), 'secret-value'),
    'profile' => new ProfileResource($this->whenLoaded('profile')),
];

Добавление метаданных

public function with($request)
{
    return [
        'meta' => [
            'version' => '1.0.0',
            'api_docs' => url('/docs'),
        ],
    ];
}

Пагинация "из коробки"

return new UserCollection(User::paginate(20));
// Автоматически добавляет meta и links для пагинации

Практическое использование в контроллерах

<?php

namespace App\Http\Controllers;

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

class UserController extends Controller
{
    // Одиночный ресурс
    public function show(User $user)
    {
        return new UserResource($user->load('profile', 'roles'));
    }
    
    // Коллекция с пагинацией
    public function index()
    {
        return new UserCollection(
            User::with('profile')->paginate(20)
        );
    }
    
    // Коллекция без пагинации
    public function all()
    {
        return UserResource::collection(User::all());
    }
}

Дополнительные инструменты и практики

1. Обертывание ответов — можно отключить автоматическое обертывание в data, настроив в AppServiceProvider:

JsonResource::withoutWrapping();

1. Трансформеры для сложной логики — для случаев, когда нужна более сложная трансформация, чем позволяют Resources.

2. Fractal библиотека — хотя Laravel предоставляет встроенные Resources, некоторые разработчики предпочитают использовать библиотеку Fractal через пакет spatie/laravel-fractal для более продвинутых сценариев.

3. Ресурсы для ошибок — стандартизация формата ошибок:

return response()->json([
    'error' => [
        'code' => 422,
        'message' => 'Validation failed',
        'errors' => $validator->errors()
    ]
], 422);

Важность стандартизации в современных API

Использование API Resources обеспечивает консистентность формата ответов, что критически важно для:

• Клиентских приложений (мобильных, веб, десктопных)
• Межсервисного взаимодействия в микросервисной архитектуре
• Документирования API (совместимость с OpenAPI/Swagger)
• Версионирования API (легко менять форматы между версиями)

Эти инструменты позволяют отделить структуру ответа от структуры базы данных, что следует принципам чистой архитектуры и упрощает поддержку и развитие API. Ресурсы также обеспечивают безопасность, скрывая чувствительные данные и предоставляя только то, что явно объявлено в методе toArray().

В экоcистеме Laravel эти инструменты являются стандартом де де-факто для построения качественных, предсказуемых и хорошо структурированных RESTful API.