README

此工具包提供各种工具，以在基于Symfony的RESTful API中以一致的方式处理错误。

为什么我应该使用它？

因为你很聪明，你不想重新发明轮子。此工具包为您提供了一个框架，以结构化方式构建令人愉悦的错误消息。您也可以不使用此工具包达到相同的结果，但您需要编写一些样板代码，而这正是此工具包已经包含的。不要浪费时间！

背景

一个优秀的错误响应应满足以下三个基本标准，才能真正有用：

1. 一个HTTP状态码，以便可以轻松确定问题的来源和领域。
2. 一个内部引用ID，用于对特定文档的错误进行注释。
3. 人类可读的消息，总结了错误的上下文、原因和一般解决方案。

RFC 7807旨在定义在HTTP响应中携带错误详细信息的标准方式，以避免为HTTP API定义新的错误响应格式。

此解决方案受到RFC 7807的启发，完全可自定义和可扩展。我可以告诉你，你可以在任何API项目中使用此工具包来以你喜欢的格式呈现错误消息。

安装

将以下依赖项添加到composer.json文件的要求部分：

"ped/api-error-bundle": "dev-master"

同样，在composer.json文件的仓库部分添加此存储库：

"repositories": [
	{
  		"type": "vcs",
		"url": "git@bitbucket.org:paneedesign/api-error-bundle.git"
	}
],

通过在bundles.php中添加以下行来启用工具包：

<?php

return [
    ...
    PED\ApiErrorBundle\PedApiErrorBundle::class => ['all' => true],
];

创建配置文件config/packages/ped_api_error.yml，并添加以下示例中的设置：

ped_api_error:
  mapping:
    fqcn:
      Symfony\Component\HttpKernel\Exception\NotFoundHttpException: NOT_FOUND
      Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException: METHOD_NOT_ALLOWED
      Assert\InvalidArgumentException:
        type: BAD_REQUEST
        forwardMessage: true
      InvalidArgumentException:
        type: BAD_REQUEST
        forwardMessage: true
      ErrorException:
        type: INTERNAL_SERVER_ERROR
        forwardMessage: false
      Symfony\Component\Debug\Exception\FatalThrowableError:
        type: INTERNAL_SERVER_ERROR
        forwardMessage: false
      Symfony\Component\HttpKernel\Exception\BadRequestHttpException:
        type: BAD_REQUEST
        forwardMessage: true
    errors:
      NOT_FOUND:
        title: Not found
        statusCode: 404
      METHOD_NOT_ALLOWED:
        title: Method not allowed
        statusCode: 405
      BAD_REQUEST:
        title: Bad request
        statusCode: 404
      INTERNAL_SERVER_ERROR:
        title: Internal server error
        statusCode: 500

基本用法

目前，该工具包允许将异常的完全限定类名映射到错误代码。此映射在配置文件的ped_api_error.mapping.fqcn部分定义。例如，查看以下从上一个示例中提取的片段：

ped_api_error:
  mapping:
    fqcn:
      Symfony\Component\HttpKernel\Exception\NotFoundHttpException: NOT_FOUND

此条目定义了NotFoundHttpException与NOT_FOUND错误类型的关联。根据RFC 7807，每个“问题详情”都必须有一个类型和一个标题。我们还需要将其映射到HTTP状态码。此映射在配置文件的ped_api_error.mapping.errors部分定义。例如，查看以下从上一个示例中提取的片段：

errors:
  NOT_FOUND:
	title: Not found
	statusCode: 404

此条目定义了NOT_FOUND错误类型与相关标题和状态码的关联。因此，每次抛出NotFoundHttpException时，将显示以下响应：

{
    "type": "NOT_FOUND",
    "title": "Not found"
}

请注意，类型可以是任何您想要的，您还可以通过扩展此工具包的默认行为来自定义其呈现方式。例如，您可以将类型呈现为一个URL，如下面的示例所示：

{
    "type": "https://example.com/probs/not-found",
    "title": "Not found"
}

有时您还会显示一些详细信息。该工具包为您提供了基本的方式来实现。您可以将forwardMessage设置为true，以告诉工具包必须将异常消息显示给客户端

ped_api_error:
  mapping:
    fqcn:
      App\Domain\OutOfCreditException:
        type: OUT_OF_CREDIT
        forwardMessage: true # Enables the exception message to be displayed
    errors:
       OUT_OF_CREDIT:
          title: You do not have enough credit
          statusCode: 400

生成的响应将类似于以下内容

{
    "type": "OUT_OF_CREDIT",
    "title": "You do not have enough credit",
    "detail": "Your current balance is 30, but that costs 50."
}

它是如何工作的