README

Syndra 是一个 Laravel 扩展包。它为你提供预定义的 JSON 响应，以便在 API 中使用。

概述

当构建 API 时，您需要标准化它，以便您可以始终期望对类似请求返回相同的响应。

当使用资源控制器时，这些方法通常是： index、store、update、destroy。

索引

对于 index 方法，您想输出数据。这可以通过 Syndra::respond($data) 实现。默认情况下，状态码是 200，但您可以使用 Syndra::setStatusCode($statusCode)->respond($data) 手动更改它。Syndra 与 Fractal 结合得很好。要了解如何一起使用它们，请阅读 Laravel API 101。

您可能还想启用 CORS。这可以通过设置适当的头信息实现。

return Syndra::setHeaders([
        'Access-Control-Allow-Origin' => '*',
    ])
    ->setStatusCode($statusCode)
    ->respond($data);

存储

在 store 方法中，您希望返回资源已创建。Syndra 允许您使用 Syndra::respondCreated() 容易地完成此操作。这会生成以下响应

{
    "message": "Created",
    "status_code": 201
}

您可以通过传递消息作为参数来自定义消息 Syndra::respondCreated('The resource has been created!')。

更新

您几乎可以猜到，当资源被更新时，我们使用的方法是 Syndra::respondUpdated()。默认情况下，它返回消息 Updated，状态码为 202。与 respondCreated 一样，您可以通过将消息作为参数传递给 respondUpdated 来设置消息。

销毁

对于 destroy 方法，我喜欢返回状态码 200 和消息 Ok。这可以通过 Syndra::respondOk() 完成。

通过应用您到目前为止所学到的知识，您现在可以轻松地构建您想要的 API 响应，并且它们将在您的整个 API 中保持一致。

高级用法

在本章中，我将向您展示如何处理您应用程序中最常见的情况。

处理验证错误

如果您正在使用控制器中的 $this->validate($request, $rules) 验证数据，那么当验证失败时，您希望 Syndra 返回验证错误。要实现这一点，请转到 app/Exceptions/Handler.php 并在 render 方法中添加以下代码块

if ($e instanceof ValidationException) {
    return \Syndra::respondValidationError(
        $e->validator->errors()->getMessages()
    );
}

如果验证失败，则响应将与下面的响应类似，但消息不同

{
    "error" : {
        "message": {
            "email": [
				"The email format is invalid."
			]
		},
		"status_code": 422
    }
}

处理模型未找到错误

与处理验证错误类似，未找到模型错误也是以同样的方式处理的。前往 app/Exceptions/Handler.php 文件，并在 render 方法中添加以下代码块

if ($e instanceof ModelNotFoundException) {
    return \Syndra::respondNotFound();
}

现在，每次你在控制器中使用 Model::findOrFail($id) 时，如果找不到任何内容，你将得到以下 JSON 响应

{
    "error" : {
        "message": "Not Found",
		"status_code": 404
    }
}

处理身份验证与授权错误

从你的 AuthController 中，如果身份验证尝试失败，你可以返回 Syndra::respondUnauthorized()，或者如果认证用户缺乏执行某些操作的权限，你可以返回 Syndra::respondForbidden()。这两种方法都接受消息作为第一个参数。

提示！ 你甚至可以用数组代替字符串作为消息。

处理服务器错误

如果发生严重错误，你可以羞愧地使用 Syndra::respondInternalError() 进行响应。

安装

从命令行

composer require laravelista/syndra

在 config/app.php 中包含服务提供者

'providers' => [
    ...,
    Laravelista\Syndra\SyndraServiceProvider::class
];

并将外观别名添加到同一文件的底部

'aliases' => [
    ...,
    'Syndra' => Laravelista\Syndra\Facades\Syndra::class
];

API

有两种方式可以使用 Syndra。作为外观 Syndra::respond($data) 或作为注入的依赖项 $this->syndra->respond($data)

use Laravelista\Syndra\Syndra;

protected $syndra;

public function __construct(Syndra $syndra)
{
    $this->syndra = $syndra
}

常见响应

respond

这对于 index 和 show 方法非常有用。当你想要返回自定义 JSON 输出时，如从 Fractal 获取的输出时，请使用此方法。

Syndra::respond(array $data)

respondWithMessage

使用此方法进行带有消息的响应。这返回一个预定义的 message JSON 模板，其中包含消息和状态码。

Syndra::respondWithMessage($message='Ok')

响应

{
    "message": "Ok",
    "status_code": 200
}

respondWithError

使用此方法进行带有错误消息的响应。这返回一个预定义的 error JSON 模板，其中包含消息和状态码，封装在 error 中。

Syndra::respondWithError($message='Error')

响应

{
    "error": {
        "message": "Error",
        "status_code": 200
    }
}

HTTP 状态码 2xx

respondOk

使用此方法以消息 (200) 进行响应。

Syndra::respondOk($message='Ok')

respondCreated

当资源已创建时 (201)，请使用此方法。

Syndra::respondCreated($message='Created')

respondUpdated

当资源已更新时 (202)，请使用此方法。

Syndra::respondUpdated($message='Updated')

HTTP 状态码 4xx

respondUnauthorized

当用户需要授权才能执行某些操作时 (401)，请使用此方法。

Syndra::respondUnauthorized($message='Unauthorized')

respondForbidden

当用户没有执行某些操作的权限时 (403)，请使用此方法。

Syndra::respondForbidden($message='Forbidden')

respondNotFound

当找不到资源时 (404)，请使用此方法。

Syndra::respondNotFound($message='Not Found')

respondValidationError

当验证失败时 (422)，请使用此方法。

Syndra::respondValidationError($message='Validation Error')

HTTP 状态码 5xx

respondInternalError

用于通用服务器错误 (500)。

Syndra::respondInternalError($message='Internal Error')

respondNotImplemented

用于 HTTP 未实现错误 (501)。

Syndra::respondNotImplemented($message='Not Implemented')

修改状态码

setStatusCode

手动设置状态码。此方法可以与其他方法链式（组合）使用。

Syndra::setStatusCode($statusCode)

示例

Syndra::setStatusCode(200)->respond($data);

修改头部信息

setHeaders

设置响应的头部信息。此方法可以与其他方法链式（组合）使用。

Syndra::setHeaders(array $headers)

示例

Syndra::setHeaders($headers)->respondWithMessage('Hello World!');

致谢

特别感谢

@delatbabel 为 notImplemented 方法及默认消息值做出的贡献

laravelista / syndra

维护者

详细信息