使用 Laravel Responsables 的标准 API 响应

介绍

想象一下，你正在开发一个应用程序，每个端点都以不同的方式返回成功和错误调用。如果它是一个由单个人维护的小型简单应用程序，这可能有点容易处理，但是如果应用程序开始增长，更多的人开始加入团队，那么在很短的时间内，维护和改进应用程序将变得混乱。

如果你的应用程序响应遵循标准化结构，这将极大帮助提高其质量和可维护性。在本文中，我们将学习如何使用 Laravel Responsable 类来简单地实现这一点。

什么是 Laravel Responsable 类？

Laravel 有一个接口：`Illuminate\Contracts\Support\Responsable`，可以用来创建可以被转换成 HTTP 响应 的类。这是一个非常简单的接口，只有一个方法

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

创建自定义响应类

创建自定义响应类给了我们很大的权力，但我们需要注意如何使用它。我已经看到很多代码库和文章解释了如何使用自定义响应类来格式化数据以及在发送之前在数据中应用一些逻辑，但就我个人而言，我不认为这是使用此功能的好方法。对我来说，代码格式化和逻辑应该在应用程序的另一个层次中。

利用这个功能，我们可以为我们的应用程序创建标准化的响应。在我们的应用程序中拥有这些响应可以极大地提高它们的质量和可维护性，因为您已经知道应用程序预期的结构。

在下面的部分中，我们将创建两个不同的自定义响应类，一个是用于 成功的API响应，另一个是用于 失败的API响应。

创建API成功响应

想象一下，在您的应用程序中，您的端点总是返回它所需的数据，但它也可以返回一些可以显示给用户的 元数据，例如消息或通知、分页信息等。基于这一点，我们可以创建一个简单的自定义 Response 类，该类将始终返回两个属性：data 和 metadata。自定义 Response 类可能看起来像这样

<?php

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错误响应

想象一下，在您的应用程序中，当发生错误时，您希望总是返回一个 错误消息，但是您想要添加一些调试信息，如果调试设置为 true。基于这一点，我们可以创建另一个简单的自定义 Response 类，可以做到这一点

<?php

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
            );
        }
    }
}