В предыдущей статье по работе с API ресурсами в Laravel была затронута тема изменения бизнес-потребностей в области формирования внешнего вида объекта ответа на запрос к API приложения.
В этой мы пойдём дальше и введём новую бизнес‑потребность под названием «нотификации». Их суть в том, чтобы вместе с ответом на запрос добавлять информацию о каких‑либо действиях.
Бизнес-потребность
При любых изменениях в базе данных, а также ошибках запросов к некоторым внешним сервисам необходимо «записывать» эти действия с целью их последующего вывода в ответ на запрос к API.
Выглядеть это будет примерно так:
{ "data": { "id": 123, "title": "Some title" }, "notifications": [ { "title": "Изменения успешно сохранены", "text": "Запись #123 \"Some title\" успешно обновлена.", "type": "OK" }, { "title": "Изменено отображение информации", "text": "Запись #456 \"Another title\" была деактивирована.", "type": "WARNING" }, { "title": "Упс! Что-то пошло не так!", "text": "Не удалось получить информацию с сервиса \"<name>\".", "type": "ERROR" } ], "status": "OK" }Мысли
На вид просто добавить их вывод в ресурс при помощи метода additional да и всё. Но нет. Вспоминаем что мы — ленивые) Поэтому нужно сделать так, чтобы впредь не приходилось ничего трогать руками и «оно само» работало.
Если подумать, то на ум приходит лишь два способа реализации — прямой и магический.
В «прямом» в нужных местах вместе с ответом отдаём какую-нибудь DTO где будет содержаться информация. Минус этого метода в том, что эту DTO придётся пробрасывать везде и вся, ломая логику и жёстко завязываясь на соседние DTO, вследствие чего придётся ещё и объединять результаты. Зачем? Вот и я говорю что не за чем. Поэтому пойдём простым путём ибо нам — лень (помним, да?).
Магический метод основан на использовании Singleton в Laravel и позволяет хранить состояние от и до. Минус в том, что способ не совместим с Laravel Octane и требует доработки, но так как у меня октан не используется, проблема решилась даже не начавшись ?
Архитектура
Итак, что нам нужно для реализации? Правильно! Глобальный объект, который будет храниться в фреймворке в инициализированном состоянии. При наступлении событий будем в него писать всё что нам нужно, а на выходе получать его состояние. Звучит легко, но как пойдёт на деле — разберёмся по ходу дела.
Подготовка
Сперва создадим Enum класс для хранения типа сообщения:
<?php namespace App\Enums; enum NotificationTypeEnum: string { case Ok = 'OK'; case Warning = 'WARNING'; case Error = 'ERROR'; }Далее создадим простейший DTO для хранения элемента:
<?php namespace App\Data; use App\Enums\NotificationTypeEnum; class NotificationData { public function __construct( public NotificationTypeEnum $type, public ?string $title, public ?string $text ) {} }Этот объект согласует нам единый формат элементов массива. И также нам нужен будет класс API ресурса для трансформации объектов:
<?php namespace App\Http\Resources; use App\Dto\NotificationData; use App\Enums\NotificationTypeEnum; use App\Http\Resources\Resource; use Illuminate\Http\Request; /** @mixin NotificationData */ class NotificationResource extends Resource { public function toArray(Request $request): array { return [ 'title' => $this->title(), 'text' => $this->text, 'type' => $this->type->value, ]; } protected function title(): string { return $this->title ?? match ($this->type) { NotificationTypeEnum::Success => __('The changes have been successfully saved'), NotificationTypeEnum::Warning => __('Information display has been changed'), NotificationTypeEnum::Error => __('Whoops! Something wrong'), }; } } Идея такая, что если передан заголовок элемента, выводим его, иначе дефолтный.
С этим разобрались и теперь можно перейти к созданию управляющего класса.
Сервис
<?php namespace App\Services; use App\Data\NotificationData; use Illuminate\Contracts\Support\Arrayable; class NotificationService implements Arrayable { protected array $items = []; public function toArray(): array { return $this->items; } protected function add(NotificationTypeEnum $type, ?string $title, ?string $text): void { $this->items[] = new NotificationData($type, $title, $text); } }Мы подготовили динамическую часть класса для работы с состоянием и, чтобы каждый раз не вызывать инициализированный класс используя хелпер app(), добавим статический метод, обращающийся к нему для добавления записи в память:
<?php namespace App\Services; use App\Data\NotificationData; use Illuminate\Contracts\Support\Arrayable; class NotificationService implements Arrayable { protected array $items = []; public static function push(NotificationTypeEnum $type, ?string $text, ?string $title = null): void { app(static::class)->add($type, $title, $text); } public function toArray(): array { return $this->items; } protected function add(NotificationTypeEnum $type, ?string $title, ?string $text): void { $this->items[] = new NotificationData($type, $title, $text); } }Вновь вспоминаем что мы ленивые и каждый раз вызывать один метод с передачей типизации, такой себе вариант. Поэтому добавляем три метода по количеству типов сообщений: success, warning и error:
<?php namespace App\Services; use App\Data\NotificationData; use App\Enums\NotificationTypeEnum; use Illuminate\Contracts\Support\Arrayable; class NotificationService implements Arrayable { protected array $items = []; public static function success(?string $text = null, ?string $title = null): void { static::push(NotificationTypeEnum::Success, $text, $title); } public static function warning(?string $text = null, ?string $title = null): void { static::push(NotificationTypeEnum::Warning, $text, $title); } public static function error(?string $text = null, ?string $title = null): void { static::push(NotificationTypeEnum::Error, $text, $title); } protected static function push(NotificationTypeEnum $type, ?string $text, ?string $title = null): void { app(static::class)->add($type, $title, $text); } public function toArray(): array { return $this->items; } protected function add(NotificationTypeEnum $type, ?string $title, ?string $text): void { $this->items[] = new NotificationData($type, $title, $text); } }Далее добавим оставшуюся часть — вывод в ресурсы. Вспоминаем потребность что выводим список только в том случае, если есть что выводить. Поэтому необходимо использовать проверку на пустоту и, в случае обнаружения таковой, возвращать null. Это позволит проще управлять данными. Что ж, добавляем:
<?php namespace App\Services; use App\Data\NotificationData; use App\Enums\NotificationTypeEnum; use App\Http\Resources\NotificationResource; use Illuminate\Contracts\Support\Arrayable; class NotificationService implements Arrayable { protected array $items = []; public static function success(?string $text = null, ?string $title = null): void { static::push(NotificationTypeEnum::Success, $text, $title); } public static function warning(?string $text = null, ?string $title = null): void { static::push(NotificationTypeEnum::Warning, $text, $title); } public static function error(?string $text = null, ?string $title = null): void { static::push(NotificationTypeEnum::Error, $text, $title); } protected static function push(NotificationTypeEnum $type, ?string $text, ?string $title = null): void { app(static::class)->add($type, $title, $text); } public static function toResource(): ?Collection { if ($items = app(static::class)->toArray()) { return collect($items)->mapInto(NotificationResource::class); } return null; } public function toArray(): array { return $this->items; } protected function add(NotificationTypeEnum $type, ?string $title, ?string $text): void { $this->items[] = new NotificationData($type, $title, $text); } }Также в методе toResource сразу производим проброс элементов массива в ресурсы с целью устранения дубляжа кода снаружи.
Итак, мы получили готовый класс, который в приложении можно использовать в абсолютно любом месте без какой-либо жёсткой привязки.
Например, в сервисе при выполнении определённых проверок, в интеграциях при ошибках запросов к внешним сервисам или при прослушивании эвентов по созданию, изменению или удалению данных из определённых моделей. В этом ограничений нет.
<?php use App\Services\NotificationService; NotificationService::success('Обновили запись №1.'); NotificationService::success('Обновили запись №2.', 'Что-то пишем'); NotificationService::warning('Не могу обновить запись №3.'); NotificationService::warning('Не могу обновить запись №4.', 'Что-то пишем'); NotificationService::error('Ошибка запроса к сервису Foo.'); NotificationService::error('Ошибка запроса к сервису Bar.', 'Ошибка получения данных');Инициализация сервиса
НО сам по себе такой метод не будет сохранять состояние. Нужно инициализировать сервисный класс и для этого сходим в сервис-провайдер AppServiceProvider, добавив нужный вызов в его метод register:
<?php namespace App\Providers; use App\Services\NotificationService; use Illuminate\Support\ServiceProvider; class AppServiceProvider extends ServiceProvider { public function register(): void { $this->notifications(); } protected function notifications(): void { $this->app->singleton(NotificationService::class, fn() => new NotificationService()); } } И последнее что нам осталось сделать, это добавить получение данных для вывода в ресурс.
API Resource
Помните как в прошлой статье формировали класс ResourceResponseService? Вернёмся к нему и добавим обращение к нашему классу:
<?php namespace App\Services\Resources; use App\Concerns\Resources\HasJsonDates; use App\Concerns\Resources\HasJsonOptions; use App\Services\NotificationService; use Illuminate\Contracts\Pagination\LengthAwarePaginator; use Illuminate\Contracts\Support\Responsable; use Illuminate\Database\Eloquent\Model; use Illuminate\Http\JsonResponse; use Illuminate\Http\Resources\Json\JsonResource; use Illuminate\Http\Resources\MissingValue; use Illuminate\Support\Arr; use Illuminate\Support\Collection; use Symfony\Component\HttpFoundation\Response; class ResourceResponseService implements Responsable { use HasJsonDates; use HasJsonOptions; protected array $with = [ 'status' => 'OK', ]; public function __construct( protected JsonResource $resource, protected ?string $wrap, ?string $dateFormat ) { static::$dateFormat = $dateFormat; } public function with(array $data): static { $this->with = array_merge($this->with, $data); return $this; } public function toResponse($request): JsonResponse { return tap( response()->json( data: $this->wrap( $this->resource->resolve($request), $this->resource->with($request), $this->resource->additional ), status: $this->status(), options: $this->jsonOptions() ), function ($response) use ($request) { $response->original = $this->resource->resource; $this->resource->withResponse($request, $response); } ); } protected function wrap(mixed $data, array $with, array $additional): array { Arr::set($result, $this->wrapper(), $this->resolveData($data)); return array_merge($result, $additional, $this->withPagination(), $this->withNotifications(), $this->with, $with); } protected function resolveData(mixed $data): array { if ($data instanceof Collection) { $data = $data->all(); } return $this->resolveDates($data); } protected function withNotifications(): array { if ($items = NotificationService::toResource()) { return ['notifications' => $items]; } return []; } protected function wrapper(): string { return 'data' . ($this->wrap ? '.' . $this->wrap : ''); } protected function status(): int { if ($this->resource->resource instanceof Model && $this->resource->resource->wasRecentlyCreated) { return Response::HTTP_CREATED; } return Response::HTTP_OK; } protected function isPagination(): bool { return $this->resource->resource instanceof LengthAwarePaginator; } protected function withPagination(): array { return $this->isPagination() ? $this->paginationInformation($this->resource->resource) : []; } protected function paginationInformation(LengthAwarePaginator $paginated): array { return [ 'pagination' => [ 'total' => $paginated->total(), 'perPage' => $paginated->perPage(), 'currentPage' => $paginated->currentPage(), 'lastPage' => $paginated->lastPage(), ], ]; } }На строке 78 примера выше добавлен новый метод, получающий массив готовых ресурсов с объектами нотификаций, а на 66-й строке вызываем его при сборке данных.
В конечном итоге получим следующие виды ответа для единичной записи и для их массива:
{ "data": { "id": 123, "title": "Some title", "createdAt": "2024-03-16T18:54" }, "notifications": [ { "title": "The changes have been successfully saved", "text": "Обновили запись №1.", "type": "SUCCESS" }, { "title": "Что-то пишем", "text": "Обновили запись №2.", "type": "SUCCESS" }, { "title": "Information display has been changed", "text": "Не могу обновить запись №3.", "type": "WARNING" }, { "title": "Что-то пишем", "text": "Не могу обновить запись №4.", "type": "WARNING" }, { "title": "Whoops! Something wrong", "text": "Ошибка запроса к сервису Foo.", "type": "ERROR" }, { "title": "Ошибка получения данных", "text": "Ошибка запроса к сервису Bar.", "type": "ERROR" } ], "status": "OK" }{ "data": { "somes": [ { "id": 123, "title": "Some title", "createdAt": "2024-03-16T18:54", "category": { "id": 1, "title": "Category name" } }, { "id": 456, "title": "Another title", "createdAt": "2024-03-16T18:55", "category": null } ] }, "pagination": { "total": 2, "perPage": 2, "currentPage": 1, "lastPage": 2 }, "notifications": [ { "title": "The changes have been successfully saved", "text": "Обновили запись №1.", "type": "SUCCESS" }, { "title": "Что-то пишем", "text": "Обновили запись №2.", "type": "SUCCESS" }, { "title": "Information display has been changed", "text": "Не могу обновить запись №3.", "type": "WARNING" }, { "title": "Что-то пишем", "text": "Не могу обновить запись №4.", "type": "WARNING" }, { "title": "Whoops! Something wrong", "text": "Ошибка запроса к сервису Foo.", "type": "ERROR" }, { "title": "Ошибка получения данных", "text": "Ошибка запроса к сервису Bar.", "type": "ERROR" } ], "status": "OK" }И пример объекта без отправки уведомлений:
{ "data": { "id": 123, "title": "Some title", "createdAt": "2024-03-16T18:54" }, "status": "OK" }Вот и всё. При получении новых бизнес-потребностей можно будет очень легко прокидывать любые данные в любом формате в ответ на запрос и/или использовать данный принцип в других областях приложения.
ссылка на оригинал статьи https://habr.com/ru/articles/800723/
Добавить комментарий