Введение
Представьте себе, что вы работаете с приложением, в котором каждая конечная точка возвращает данные об успешных и ошибочных вызовах по-разному. Если это маленькое и простое приложение, поддерживаемое одним человеком, это может быть немного проще, но если приложение начнет расти и к команде начнет присоединяться все больше людей, то за небольшой промежуток времени поддержка и улучшение приложения станет полным хаосом. приложение.
Наличие стандартизированной структуры ответов вашего приложения может очень помочь в повышении его качества и удобства сопровождения. В этой статье мы узнаем простой способ сделать это с помощью классов 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 для наших приложений, чтобы улучшить их качество и удобство обслуживания. Примеры в этой статье предназначены только для того, чтобы показать, как использовать эту функцию, но вы можете настроить собственные классы ответов в соответствии с потребностями ваших проектов.