README

API响应

一个帮助你保持API响应标准化的包。

安装

composer require treblle/api-responses

使用方法

这个包易于使用，它被设计成在控制器中使用，以返回简单和标准化的API响应。

使用配置

您可以使用以下Artisan命令发布此包的配置：

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

这将返回此包的配置文件。目前，配置仅涵盖响应中使用的标题。

return [
    'headers' => [
        'default' => [
            'Content-Type' => 'application/vnd.api+json',
        ],
        'error' => [
            'Content-Type' => 'application/problem+json',
        ],
    ],
];

响应类中使用的 HeaderFactory 将根据您是返回错误还是响应来使用 HeaderFactory::default() 或 HeaderFactory::error()。

您可以使用配置文件覆盖可用的标题。这将在您可能使用的任何中间件之外执行 - 它将根据需要合并相关的标题，例如您可能设置的速率限制和缓存标题。

返回单个模型

某些API端点只需要返回单个模型，在这种情况下，您应使用 ModelResponse，它接受您模型的 JsonResource 表示。

final class ShowController
{
    public function __invoke(Request $request, User $user): Responsable
    {
        return new ModelResponse(
            data: new UserResource(
                resource: $user,
            ),
        );
    }
}

返回模型集合

其他API端点希望返回模型集合，在这些情况下，您应使用 CollectionResponse，它接受 AnonymousResourceCollection，这是一个通过API资源转换后的模型集合。

final class IndexController
{
    public function __invoke(Request $request): Responsable
    {
        return new CollectionResponse(
            data: UserResource::collection(
                resource: User::query()->get(),
            ),
        );
    }
}

当出现问题

在您的API中出现问题时，最好的方法是允许异常处理程序捕获它，并在一个中心位置管理响应。

final class Handler extends ExceptionHandler
{
    public function register(): void
    {
        $this->renderable(fn (ModelNotFoundException $exception, Request $request) => new ErrorResponse(
            data: new ApiError(
                title: 'Not Found',
                detail: $exception->getMessage(),
                instance: $request->path(),
                code: ErrorCode::NOT_FOUND->value,
                link: 'https://docs.domain.com/errors/not-found',
            ),
            status: Status::NOT_FOUND,
        ));
    }
}

发送简单的消息响应

有时您只需要通过您的API发送一个简单的消息。也许您正在将逻辑推送到后台任务。

final class StoreController
{
    public function __invoke(StoreRequest $request): Responsable
    {
        dispatch(new RegisterProvider($request->payload()));
        
        return new MessageResponse(
            data: 'We have accepted your request, and are processing this action.',
            status: Status::ACCEPTED,
        )
    }
}

发送更复杂的消息响应

有时您希望传递消息以及一些数据，可能表示需要采取的操作。

final class LoginController
{
    public function __invoke(Request $request): Responsable
    {
        return new \Treblle\ApiResponses\Responses\ExpandedResponse(
            message: __('auth.login'),
            data: [
                'type' => 'login',
                'attributes' => [
                    'mfa' => __('auth.mfa_required'),
                ]
            ],
        )
    }
}

通用使用

该包目前包含以下响应：

ModelResponse：用于响应单个模型资源。
CollectionResponse：用于响应资源中的模型集合。
ErrorResponse：当您遇到错误时使用。
MessageResponse：当您需要返回简单消息时使用。
ExpandedResponse：当您想发送消息和在响应中包含一些数据时使用。

请注意，ErrorResponse 不是一个理想的 400 响应，因为这些是用户错误，例如错误的资源或验证问题。

社区 💙

首先和最重要的是：给此仓库加星标并关注 以保持最新。

此外，关注我们的博客和 Twitter。

您可以在 Discord 上与团队和其他成员聊天，并在 YouTube 上关注我们的教程和其他视频材料。

如何贡献

以下是一些为使 Treblle 更好的贡献方式

试用 Treblle，并让我们知道如何使 Treblle 对您更好。在 Discord 上告诉我们。
加入我们的 Discord，与其他成员建立联系并共享学习。
向我们的任何开源仓库发送拉取请求。请查看您想贡献的仓库中的贡献指南，了解更多关于如何贡献的详细信息。我们期待您的贡献！

测试

运行测试套件

composer run test

致谢

许可协议

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

treblle / api-responses

维护者

详细信息