Стандартные ответы API с использованием интерфейса Responsable

Стандартные ответы API с использованием интерфейса Responsable

Введение

Представьте себе, что вы работаете с приложением, в котором каждая конечная точка возвращает данные об успешных и ошибочных вызовах по-разному. Если это маленькое и простое приложение, поддерживаемое одним человеком, это может быть немного проще, но если приложение начнет расти и к команде начнет присоединяться все больше людей, то за небольшой промежуток времени поддержка и улучшение приложения станет полным хаосом. приложение.


Наличие стандартизированной структуры ответов вашего приложения может очень помочь в повышении его качества и удобства сопровождения. В этой статье мы узнаем простой способ сделать это с помощью классов Laravel Responsable.


Что такое ответственные классы Laravel?

У Laravel есть интерфейс: Illuminate\Contracts\Support\Responsable его можно использовать для создания классов, которые можно преобразовать в HTTP-ответы. Это действительно простой интерфейс, имеющий только один метод:


namespace Illuminate\Contracts\Support;

interface Responsable
{
    /**
     * Create an HTTP response that represents the object.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function toResponse($request);
}


Создание пользовательских классов ответов

Создание пользовательских классов Response дает нам много возможностей, но нам нужно быть осторожными в том, как их использовать. Я уже видел множество баз кода и множество статей, объясняющих, как использовать пользовательские классы Response для форматирования данных и применения некоторой логики к данным перед их отправкой, но лично я не думаю, что это хороший способ использования этой функции. По моему мнению, форматирование кода и логика должны находиться на другом уровне приложения.


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


В разделах ниже мы создадим два разных класса пользовательских ответов: один для успешных ответов API, а другой — для неудачных ответов API.


Создание ответа об успехе API

Представьте, что в вашем приложении ваши конечные точки всегда возвращают необходимые для этого данные, но они также могут возвращать некоторые метаданные, которые могут содержать сообщение или уведомление для отображения пользователю, информацию о нумерации страниц и т. д. Имея это в виду, мы можем создать простой пользовательский класс Response, который всегда будет возвращать два свойства в ваших ответах: dataи metadata. Пользовательский класс Response будет выглядеть примерно так:


namespace App\Http\Responses;

use Illuminate\Contracts\Support\Responsable;
use Illuminate\Http\Response;

class ApiSuccessResponse implements Responsable
{
    /**
     * @param  mixed  $data
     * @param  array  $metadata
     * @param  int  $code
     * @param  array  $headers
     */
    public function __construct(
        private mixed $data,
        private array $metadata,
        private int $code = Response::HTTP_OK,
        private array $headers = []
    ) {}

    /**
     * @param  $request
     * @return \Symfony\Component\HttpFoundation\Response|void
     */
    public function toResponse($request)
    {
        return response()->json(
            [
                'data' => $this->data,
                'metadata' => $this->metadata,
            ],
            $this->code,
            $this->headers
        );
    }
}


С помощью этого класса мы можем гарантировать, что:


  • Ответ всегда будет в формате JSON.
  • Мы всегда будем возвращать свойства data и metadata.
  • При необходимости мы можем настроить HTTP-код и заголовки.


Теперь вы можете использовать этот ответ для своих конечных точек:


class UserController extends Controller
{
    public function store(CreateUserRequest $request): JsonResponse
    {
        $user = $this->service->create($request->all());
        return new ApiSuccessResponse(
            $user,
            ['message' => 'User was created successfully'],
            Response::HTTP_CREATED
        );
    }
}



Создание ответа об ошибке API

Представьте, что в вашем приложении вы хотите всегда возвращать сообщение об ошибке, если что-то идет не так, но вы также хотите добавить некоторую отладочную информацию, если для параметра debug установлено значение true. Имея это в виду, мы можем создать еще один простой собственный класс Response, который будет делать это:


namespace App\Http\Responses;

use Illuminate\Contracts\Support\Responsable;
use Illuminate\Http\Response;
use Throwable;

class ApiErrorResponse implements Responsable
{
    public function __construct(
        private string $message,
        private ?Throwable $exception = null,
        private int $code = Response::HTTP_INTERNAL_SERVER_ERROR,
        private array $headers = []
    ) {}

    /**
     * @param  $request
     * @return \Symfony\Component\HttpFoundation\Response|void
     */
    public function toResponse($request)
    {
        $response = ['message' => $this->message];

        if (! is_null($this->exception) && config('app.debug')) {
            $response['debug'] = [
                'message' => $this->exception->getMessage(),
                'file'    => $this->exception->getFile(),
                'line'    => $this->exception->getLine(),
                'trace'   => $this->exception->getTraceAsString()
            ];
        }

        return response()->json($response, $this->code, $this->headers);
    }
}


С помощью этого класса мы можем гарантировать, что:


  • Ответ всегда будет в формате JSON.
  • Мы всегда вернем messageимущество.
  • Информация об отладке будет добавлена ​​при необходимости.
  • При необходимости мы можем настроить HTTP-код и заголовки.


Теперь вы можете использовать этот ответ для своих конечных точек:


class UserController extends Controller
{
    public function store(CreateUserRequest $request): JsonResponse
    {
        try {
            $user = $this->service->create($request->all());
            return new ApiSuccessResponse(
                $user,
                ['message' => 'User was created successfully'],
                Response::HTTP_CREATED
            );
        } catch (Throwable $exception) {
            return new ApiErrorResponse(
                'An error occurred while trying to create the user',
                $exception
            );
        }
    }
}


Заключение

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