当作为后端开发人员在团队中工作时，保持 API 响应的单一格式并非易事。
但是开发 API 时的最佳实践之一是就是标准化响应和错误信息，以方便使用和理解 API……
在本文中，我将与您分享如何标准化您的 API 响应，以便在整个项目中保持一致，并避免使用 Laravel 框架重复不同的响应格式。
我们将使用的技术
- Laravel：它将有助于构建 REST API
您将学到什么
- 我们将学习如何创建 Trait 来封装你的 API 响应格式，并通过你的 Laravel 项目使用它们来返回 API 响应。
对于本文的其余部分，我假设您熟悉 Laravel。
在继续之前，让我先给出 Trait 的定义，以及为什么我选择使用它来管理 Laravel 项目中的响应
PHP Trait 是 PHP OOP 的重要概念之一。
Trait 用于声明可在多个类中使用的方法，并且这些方法可以具有任何访问修饰符（public、private 或 protected）。
由于我们可以从不同的文件和类（例如控制器、服务等）返回 API 的响应信息，因此使用 Trait 来标准化响应格式是最佳选择，因为所有这些类可以同时共享此特性来返回响应。
现在，我们了解了 Trait 是什么以及为什么我们选择使用它，接下来让我们将所有这些付诸实践。
初始化项目
首先，让我们创建一个新的项目，我们将其称为standardized-api-response（这只是个示例，您可以随意命名）。通过 composer 这一切都很简单，您只需运行下面的 composer 命令即可，这里我使用的是 laravel 10.3.3 和 PHP 8.2 版本。
composer create-project laravel/laravel:^10.0 standardized-api-response创建 JsonResponseTrait
Laravel 初始化项目中不包含默认的 Traits 文件夹，因此我们要在项目根目录下手动创建 Traits 文件夹，然后添加JsonResponseTrait.php文件：
<?php
namespace App\Traits;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Response;
/**
* ***`JsonResponseTrait`***
*
* This trait provides reusable methods for creating JSON responses with different structures such as success responses,
* error responses, and validation error responses. It abstracts away the common logic of creating JSON responses,
* making it easier and more consistent to handle responses in your application.
*
* */
trait JsonResponseTrait
{
/**
* Create a JSON response.
*
* @param array $data The data to be included in the response.
* @param int $status_code The HTTP status code.
* @param array|null $headers Additional headers for the response.
* @param int|null $options JSON encoding options.
* @return \Illuminate\Http\JsonResponse
*/
public static function response(array $data, $status_code = Response::HTTP_OK, $headers = [], $options = null): JsonResponse
{
return response()->json($data, $status_code, $headers, $options);
}
/**
* Create a `success` JSON response.
*
* @param mixed $data The data to be included in the response.
* @param int $statusCode The HTTP status code.
* @param array|null $headers Additional headers for the response.
* @param int|null $options JSON encoding options.
* @return \Illuminate\Http\JsonResponse
*/
public static function success($message = null, $data = null, int $status_code = Response::HTTP_OK, $headers = [], $options = null): JsonResponse
{
$responseData = [
'status' => true,
'message' => $message,
'data' => $data,
'status_code' => $status_code
];
return static::response($responseData, $status_code, $headers, $options);
}
/**
* Create an `error` JSON response.
*
* @param string $message The error message.
* @param int $status_code The HTTP status code.
* @param array|null $headers Additional headers for the response.
* @param int|null $options JSON encoding options.
* @return \Illuminate\Http\JsonResponse
*/
public static function error($message = null, $status_code = Response::HTTP_INTERNAL_SERVER_ERROR, $errors = null, $headers = [], $options = null): JsonResponse
{
$responseData = [
'status' => false,
'message' => $message,
'errors' => $errors,
'status_code' => $status_code
];
return static::response($responseData, $status_code, $headers, $options);
}
}如您所见，我首先创建了 reponse 函数，它使用基本的 Laravel 响应函数在应用程序中返回响应。
然后我们分别创建了 success、error 和 validationError 函数，它们依次使用在开始创建的响应函数并在三种常见的情况下格式化响应数据，当然您也可以随意格式化您的响应，我注意使用最广泛和最易理解的响应格式包含以下几项：
status_code：表示响应状态的代码
status：总是返回 true 或 false，如果响应成功，则返回 true，否则返回 false。
message：最好从后台返回响应信息
data：主要项，应显示的数据
error：发生错误时的错误信息
现在，我们将使用这个 Trait 通过您的项目返回标准化（格式化）响应信息。
<?php
namespace App\Http\Controllers;
use App\Models\User;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;
use App\Traits\JsonResponseTrait;
use Illuminate\Http\Request;
class Controller extends BaseController
{
use AuthorizesRequests, ValidatesRequests, JsonResponseTrait;
public function index()
{
$users = User::get();
return JsonResponseTrait::success('Get users', $users);
}
public function show(Request $request)
{
$user = User::where('email', $request->email)->first();
if (!is_null($user)) {
return JsonResponseTrait::success('User found', $user);
}
return JsonResponseTrait::error('User not found', Response::HTTP_NOT_FOUND);
}
}如您所见，在示例中，index函数检索用户列表并使用 JsonResponseTrait 的success函数返回响应，其中“Get users”作为 messsage 参数并以 $users 作为 data 参数。
我们还可以使用error函数返回项目中的验证错误等信息：
关于验证错误，我们可以通过Exceptions文件夹的Handler.php文件返回，以便全局捕获我们的应用程序的异常。
public function register(): void
{
$this->reportable(function (Throwable $exception) {
if ($exception instanceof ValidationException) {
return JsonResponseTrait::error('Validation errors',Response::HTTP_UNPROCESSABLE_ENTITY, errors: $exception->validator->getMessageBag());
}
});
}在此代码中，当我们的应用程序捕获到 ValidationException 类型的异常时，它将通过错误函数JsonResponseTrait返回带有验证错误的响应。
