Руководство по структуре
Используется Service–Eloquent
Архитектурный стандарт определяет разделение ответственности между слоями приложения: Controller, Service, Eloquent Model и API Resource.
Соблюдение этих правил обеспечивает предсказуемость, тестируемость и согласованность API.
Структура:
Основные принципы
Слой Controller отвечает только за приём запроса и возврат API-ответа через Resource.
Слой Service инкапсулирует бизнес-логику и работает с Eloquent-моделями напрямую.
Слой Model (Eloquent) изолирует работу с БД: отношения, скоупы, мутаторы.
Слой Resource формирует финальный JSON:API-ответ.
Каждый слой имеет чёткую роль и не нарушает границы зоны ответственности.
Repository не используется. Сервис обращается к Eloquent напрямую.
1. Eloquent Model
Model служит точкой доступа к данным через Eloquent. Определяет отношения, скоупы и правила заполнения.
Правила
Model не содержит бизнес-логику — только ORM-конфигурацию.
Model определяет $fillable, отношения и кастомные скоупы.
Для фильтрации и сортировки используйте трейты Filterable и Sortable.
Пример модели
2. Service Layer
Service реализует бизнес-логику и работает с Eloquent-моделями напрямую. Контроллер общается только с сервисом.
Правила
Сервис не должен знать о структуре API-ответа.
Сервис никогда не возвращает JsonResponse или Resource.
Сервис содержит только предметную логику (вычисления, доменные операции, работа с отношениями).
Пример сервиса
3. API Resources
Resource отвечает за финальное преобразование данных модели в JSON:API-ответ. Контроллер возвращает только Resource или коллекцию Resource.
Все ресурсы наследуют JsonApiResource и реализуют четыре метода.
Правила
Resource не вызывает модели или сервисы.
Resource получает подготовленную сущность и сериализует её.
Отношения объявляются в toRelationships(), ссылки — в toLinks().
Пример ProductResource
4. Controller Layer
Контроллер получает запрос через Form Request, вызывает методы сервиса и упаковывает результат в Resource. Контроллер не взаимодействует с Eloquent и не возвращает «сырые» массивы.
Правила
Контроллер не вызывает модель напрямую (исключение — Route Model Binding).
Контроллер возвращает только Resource или AnonymousResourceCollection.
Контроллер не содержит бизнес-логики.
Валидация выносится в Form Request.
Пример контроллера
Как слои взаимодействуют
Запрос маршрутизируется в Controller.
Controller валидирует данные через Form Request.
Controller вызывает Service.
Service работает с Eloquent-моделями и БД.
Service возвращает модель или коллекцию контроллеру.
Controller возвращает Resource в ответ.
Частые ошибки
Ошибка 1: Контроллер работает с моделью напрямую
Правильно:
Ошибка 2: Сервис возвращает Resource
Правильно:
Ошибка 3: Валидация в контроллере
Правильно: создать отдельный Form Request (php artisan make:request).
Ошибка 4: Resource выполняет запросы в БД
Resource должен сериализовать только то, что уже загружено. Загружайте отношения в контроллере через loadMissing() или в сервисе через with().
Золотое правило
Controller формирует ответ.
Service формирует смысл.
Model формирует данные.
Resource формирует JSON.
Каждый слой отвечает только за свой участок.
Соблюдение этого правила делает API предсказуемым, расширяемым и простым в сопровождении.