Как спроектируешь endpoint на Laravel?

Общие принципы проектирования endpoint в Laravel

Проектирование endpoint в Laravel — это процесс создания структурированных, безопасных и эффективных точек взаимодействия API с клиентскими приложениями. Я всегда начинаю с анализа требований и определения характера endpoint (RESTful, GraphQL, RPC). Для RESTful API в Laravel основными шагами будут:

1. Планирование ресурсов и маршрутов

Определяю, какие ресурсы (сущности: пользователи, статьи, продукты) будут представлены в API. Для каждого ресурса планирую стандартные маршруты (CRUD).

// В routes/api.php
Route::apiResource('users', UserController::class);
// Это автоматически создаст:
// GET /api/users (index)
// POST /api/users (store)
// GET /api/users/{user} (show)
// PUT/PATCH /api/users/{user} (update)
// DELETE /api/users/{user} (destroy)

Для нестандартных действий добавляю отдельные маршруты:

Route::post('/users/{user}/activate', [UserController::class, 'activate']);

2. Создание контроллера с четкой структурой

Каждый endpoint обрабатывается методом контроллера. Методы должны быть лаконичными и следовать шаблону:

• Валидация входящих данных (использую Form Request или validate())
• Бизнес-логика в сервисах (контроллер делегирует сложные операции сервисным классам)
• Возврат ответа в стандартизированном формате

<?php
// app/Http/Controllers/UserController.php

class UserController extends Controller
{
    public function store(UserStoreRequest $request, UserService $service)
    {
        // Валидация уже выполнена в UserStoreRequest
        $user = $service->createUser($request->validated());

        // Стандартизированный ответ
        return response()->json([
            'data' => new UserResource($user),
            'message' => 'User created successfully.'
        ], 201);
    }
}

3. Использование Form Request для валидации и авторизации

Это ключевой паттерн Laravel. Form Request объединяет проверку данных и проверку прав доступа.

<?php
// app/Http/Requests/UserStoreRequest.php

class UserStoreRequest extends FormRequest
{
    public function authorize()
    {
        // Проверка прав: только администраторы могут создавать пользователей
        return $this->user()->hasRole('admin');
    }

    public function rules()
    {
        return [
            'email' => ['required', 'email', 'unique:users'],
            'name' => ['required', 'string', 'max:255'],
            'password' => ['required', 'confirmed', 'min:8']
        ];
    }
}

4. Применение Eloquent Resources для трансформации данных

API Resources позволяют контролировать, какие поля будут возвращены, форматировать данные и добавлять мета-информацию.

<?php
// app/Http/Resources/UserResource.php

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'email' => $this->email,
            'full_name' => $this->name,
            'created_at' => $this->created_at->toIso8601String(),
            'links' => [
                'self' => route('users.show', $this->id)
            ]
        ];
    }
}

5. Реализация пагинации, фильтрации и сортировки

Для коллекций (index методы) обязательно добавляю пагинацию через paginate(). Фильтрацию и сортировку проектирую через параметры запроса и scope в модели.

public function index(UserIndexRequest $request)
{
    $query = User::query()
                ->when($request->has('role'), fn($q) => $q->whereRole($request->role))
                ->when($request->has('sort'), fn($q) => $q->orderBy($request->sort));

    $users = $query->paginate($request->get('per_page', 15));

    return UserResource::collection($users);
}

6. Обеспечение безопасности и Middleware

К каждому endpoint применяю соответствующие middleware:

• auth:api для защиты приватных маршрутов
• throttle для ограничения частоты запросов
• cors если API публичное

Route::middleware(['auth:api', 'throttle:60,1'])->group(function () {
    Route::apiResource('posts', PostController::class);
});

7. Документация и тестирование

Параллельно с разработкой endpoint я:

• Использую Swagger/OpenAPI или laravel-apidoc-generator для автоматической документации.
• Пишу Feature tests для каждого endpoint, проверяя статусы ответов, структуру JSON и бизнес логику.

<?php
// tests/Feature/UserEndpointTest.php

public function test_user_can_be_created()
{
    $admin = User::factory()->admin()->create();

    $response = $this->actingAs($admin)
                     ->postJson('/api/users', [
                         'email' => 'test@example.com',
                         'name' => 'Test User'
                     ]);

    $response->assertStatus(201)
             ->assertJsonStructure([
                 'data' => ['id', 'email', 'full_name']
             ]);
}

Ключевые выводы

Проектирование endpoint в Laravel — это не просто создание методов в контроллере. Это системный подход, включающий:

• Структурированную организацию (маршруты, контроллеры, запросы, ресурсы)
• Строгую валидацию и авторизацию через Form Request
• Отделение бизнес-логики в сервисы для поддержания thin controllers
• Стандартизированный формат ответов для клиентской стороны
• Комплексную безопасность через middleware и правильную работу с токенами
• Поддержку типичных операций (пагинация, фильтры) из коробки

Такой подход обеспечивает масштабируемость, тестируемость и удобство поддержки API в долгосрочной перспективе. Laravel предоставляет все необходимые инструменты для реализации этой архитектуры элегантно и эффективно.