kennedy-osaze/laravel-api-response

为基于API的项目渲染一致的HTTP JSON响应

维护者

详细信息

github.com/kennedy-osaze/laravel-api-response

主页

源代码

问题

安装次数: 3,915

依赖: 0

建议者: 0

安全: 0

星级: 64

关注者: 2

分支: 8

公开问题: 2

v2.0 2023-03-19 23:37 UTC

Requires

Requires (Dev)

MIT 017eb5864160ce311173647a8aab12ddf9e81f32

  • Kennedy Osaze <me.osaze.woop@gmail.com>

jsonapiresponselaravel

This package is auto-updated.

Last update: 2024-09-03 18:29:34 UTC

README

Laravel API Response Logo

GitHub Workflow Status Latest Version on Packagist License Total Downloads

Laravel API Response 是一个帮助提供和渲染一致的HTTP JSON响应到API调用以及将异常转换为JSON响应的包。

版本兼容性

安装

您可以通过composer安装此包

composer require kennedy-osaze/laravel-api-response

您可以使用以下命令发布翻译文件

php artisan vendor:publish --tag="api-response-translations"

这将创建一个在项目 lang 文件夹中的供应商文件夹（如果不存在），并在其中创建一个 api-response/en 文件夹，该文件夹包含两个文件： errors.php 和 success.php。这两个文件都用于翻译发送出的JSON响应中的消息字符串。

可选地，您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="api-response-config"

使用

使用包特性

此包提供两个特性，可以导入到您的项目中；即

  • \KennedyOsaze\LaravelApiResponse\Concerns\RendersApiResponse 特性，可以导入到您的（基础）控制器类、中间件类或异常处理器类
  • \KennedyOsaze\LaravelApiResponse\Concerns\ConvertsExceptionToApiResponse 特性，应仅导入到您的异常处理器类。

因此，我们可以在基础控制器类（其他所有控制器都可能从它扩展）中

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;
use KennedyOsaze\LaravelApiResponse\Concerns\RendersApiResponse;

class Controller extends BaseController
{
    use AuthorizesRequests, DispatchesJobs, ValidatesRequests, RendersApiResponse;
}

或者某个随机控制器类

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use KennedyOsaze\LaravelApiResponse\Concerns\RendersApiResponse;

class RandomController extends Controller
{
    use RendersApiResponse;
}

无论如何，您都可以访问大量方法，可以调用以渲染数据。这包括

// Successful Responses
return $this->okResponse('This is a random message', $data = null, $headers = []);
return $this->createdResponse('This is a random message', $data = null, $headers = []);
return $this->acceptedResponse($message, $data, $headers);
return $this->noContentResponse();
return $this->successResponse($message, $data = null, $status = 200, $headers = []);

// Successful Responses for \Illuminate\Http\Resources\Json\JsonResource
return $this->resourceResponse($jsonResource, $message, $status = 200, $headers = []);
return $this->resourceCollectionResponse($resourceCollection, $message, $wrap = true, $status = 200, $headers = []);

// Error Responses
return $this->unauthenticatedResponse('Unauthenticated message');
return $this->badRequestResponse('Bad request error message', $error = null);
return $this->forbiddenResponse($message);
return $this->notFoundResponse($message);
return $this->clientErrorResponse($message, $status = 400, $error = null, $headers = []);
return $this->serverErrorResponse($message);
return $this->validationFailedResponse($validator, $request = null, $message = null);

$messages = ['name' => 'Name is not valid'];
$this->throwValidationExceptionWhen($condition, $messages);

还可以通过在异常处理器中使用 \KennedyOsaze\LaravelApiResponse\Concerns\ConvertsExceptionToApiResponse 特性来处理异常，该特性提供了 renderApiResponse 公共方法，可以使用如下方式使用

<?php

namespace App\Exceptions;

use App\Traits\HandleApiException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use KennedyOsaze\LaravelApiResponse\Concerns\ConvertsExceptionToApiResponse;
use Throwable;

class Handler extends ExceptionHandler
{
    use ConvertsExceptionToApiResponse;

    public function render($request, Throwable $e)
    {
        return $this->renderApiResponse($e, $request);
    }
}

您还可以使用处理器的 renderable 方法

<?php

namespace App\Exceptions;

use App\Traits\HandleApiException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use KennedyOsaze\LaravelApiResponse\Concerns\ConvertsExceptionToApiResponse;
use Throwable;

class Handler extends ExceptionHandler
{
    use ConvertsExceptionToApiResponse;

    public function register()
    {
        $this->renderable(function (Throwable $e, $request) {
            return $this->renderApiResponse($e, $request);
        });
    }
}

使用包类

上述方法的底层，有一个名为 ApiResponse 的类被调用，也可以按如下方式使用

use KennedyOsaze\LaravelApiResponse\ApiResponse;

$response = new ApiResponse($status = 200, $message = 'Hello world', $data = ['age' => 20], $header = []);

return $response->make();

// Result
{
    "success": true,
    "message": "Hello world",
    "data": {
        'age' => 20
    }
}

// OR
return ApiResponse::create(400, 'Error occurred');

// Result
{
    "success": false,
    "message": "Error occurred"
}

// We could also have
$validator = Validator::make([], ['name' => 'required']);
return ApiResponse::fromFailedValidation($validator);

// Result
{
    "success": true,
    "message": "Validation Failed.",
    "errors": [
        "name": {
            "message": "The name field is required",
            "rejected_value": null
        }
    ]
}

// Also

$response = response()->json(['hello' => 'world']);

return ApiResponse::fromJsonResponse($response, $message = 'Hello');

// Result
{
    "success": true,
    "message": "hello"
    "data": {
        "hello": "world"
    }
}

如果您想更改验证错误的格式，您可以在 App\Providers\AppServiceProvider 类的启动方法或任何其他您想要的服务提供者中调用 ApiResponse 类的静态方法 registerValidationErrorFormatter。您可以这样做

<?php

// App\Providers\AppServiceProvider

use Illuminate\Contracts\Validation\Validator;
use Illuminate\Http\Request;
use KennedyOsaze\LaravelApiResponse\ApiResponse;

public function boot()
{
    ApiResponse::registerValidationErrorFormatter(function (Validator $validator, Request $request) {
        return [
            'error_messages' => $validator->errors()->all(),
        ];
    });
}

响应数据

要渲染的成功响应的响应数据 $data 可以是以下任何类型

  • 数组，例如 ['name' => 'Dummy']
  • 标准对象，例如 new stdClass
  • 整数，例如 1
  • 布尔值，例如 true
  • 任何模型对象，instance of \Illuminate\Database\Eloquent\Model
  • 任何集合对象，instance of \Illuminate\Support\Collection
  • 任何JSON资源对象，instance of \Illuminate\Http\Resources\Json\JsonResource
  • 任何可序列化为JSON的对象，instance of \Illuminate\Contracts\Support\Jsonable
  • 任何实现了JsonSerializable接口的对象，instance of \JsonSerializable
  • 任何实现了Arrayable接口的对象，instance of \Illuminate\Contracts\Support\Arrayable

以上任何一种都可以存储为 $data 并按如下使用

use \KennedyOsaze\LaravelApiResponse\ApiResponse;

ApiResponse::create(200, 'A message', $data)

对于API资源 JsonResources ，您可以通过以下方式创建JSON响应

use App\Models\Book;
use App\Http\Resources\BookResource;
use App\Http\Resources\BookCollection;
use KennedyOsaze\LaravelApiResponse\ApiResponse;

$resource = new BookResource(Book::find(1));

return ApiResponse::fromJsonResponse($resource->response(), 'A book');

// Also

$collection = BookResource::collection(Book::all());

return ApiResponse:::fromJsonResponse($collection->response(), 'List of books');

// Also

$collection = new BookCollection(Book::paginate());

return ApiResponse::fromJsonResponse($collection->response, 'Paginated list of books')

响应消息

此软件包使用翻译文件来翻译在创建响应时定义的消息。正如之前所述，此软件包包含两个翻译文件：success.php 和 errors.php。其中，success.php 包含成功响应消息的翻译，而 errors.php 包含错误响应消息的翻译。

假设您有一个如下所示的 success.php 翻译文件

<?php

return [
    'Account Created' => 'User account created successfully',
    'invoice_paid' => 'Invoice with number :invoice_number has been paid.',
];

ApiResponse 类将能够按照以下方式翻译消息

<?php

use KennedyOsaze\LaravelApiResponse\ApiResponse;

return ApiResponse::create(200, 'Account Created');

// Result
{
    "success": true,
    "message": "User account created successfully"
}

// Also:

return ApiResponse::create(200, 'invoice_paid:invoice_number=INV_12345');

// OR

return ApiResponse::create(200, 'invoice_paid', [
    '_attributes' => ['invoice_number' => 'INV_12345']
]);

// Result
{
    "success": true,
    "message": "Invoice with number INV_12345 has been paid."
}

// Also:

return ApiResponse::create(200, 'invoice_paid', [
    '_attributes' => ['invoice_number' => 'INV_12345'],
    'name' => 'Invoice for Mr Bean',
    'amount' => 1000,
    'number' => 'INV_12345'
]);

// Result
{
    "success": true,
    "message": "Invoice with number INV_12345 has been paid.",
    "data": {
        "name": "Invoice for Mr Bean",
        "amount": 1000,
        "number": "INV_12345"
    }
}

这类似于错误响应消息的翻译方式，只是错误消息是从 errors.php 翻译文件中读取的（或者您在配置文件中指定的任何文件）。

此外，对于错误消息，您可以决定错误响应应该包含错误代码。您可以在响应中提供错误代码的几种方式

<?php

use KennedyOsaze\LaravelApiResponse\ApiResponse;

return ApiResponse::create(400, 'Error message comes here.', [
    'error_code' => 'request_failed' // The error code here is "request_failed"
]);

// Result
{
    "success": false,
    "message": "Error message comes here.",
    "error_code": "request_failed"
}

此外，您还可以使用 errors.php 翻译文件来翻译错误代码。以下是一个 errors.php 文件示例

return [

    'error_code' => [
        'example_code' => 'Just a failed error message',

        'error_code_name' => 'Example error message with status :status',
    ],
];

我们可以有一个包含错误代码的响应如下

<?php

use KennedyOsaze\LaravelApiResponse\ApiResponse;

return ApiResponse::create(400, 'error_code.example_code');

// Result

{
    "success": false,
    "message": "Just a failed error message",
    "error_code": "example_code"
}

// Also

return ApiResponse::create(400, 'error_code.error_code_name', [
    '_attributes' => ['status' => 'FAILED']
]);

// OR

return ApiResponse::create(400, 'error_code.error_code_name:status=FAILED');

// Result

{
    "success": false,
    "message": "Example error message with status FAILED",
    "error_code": "error_code_name"
}

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

如果您发现任何与安全相关的问题，请通过电子邮件 me.osaze@gmail.com 联系，而不是使用问题跟踪器。

致谢

许可

MIT 许可证 (MIT)。有关更多信息，请参阅许可文件。