REST API 的错误响应

Question

以下是我的 API 返回给客户端的错误响应：

{
    "statusCode": "400",
    "errors": [
         {
             "errorCode": "50009",
             "fieldName": "bookingDate",
             "errorMsg": "Input bookingDate must lie in the bracket: 20 Jan - 27 Jan, 2018"
         }
     ]
}

客户端无法在 UI 中显示 API 返回的 errorMsg，但它需要括号信息，即（2018 年 1 月 20 日 - 2018 年 1 月 27 日），同时形成一些更有意义的 errorMsg。因此，客户端必须从 API 响应中提取括号信息。

但是，如果更改了 errorMsg 的文本，这可能会破坏客户端的功能。 所以，为了让客户的生活更轻松，我想稍微改变一下错误响应：

{
    "statusCode": "400",
    "errors": [
         {
             "errorCode": "50009",
             "fieldName": "bookingDate",
             "errorMsg": "Input bookingDate must lie in the bracket: 20 Jan - 27 Jan, 2018",
             "startDate": "20 Jan 2018",
             "endDate": "27 Jan 2018"
         }
     ]
}

那么，将 startDate 和 endDate 添加到错误响应中是正确的方法（只是为了客户的利益）还是有其他更好的方法？

提前致谢。

Answer 1

您可以随意添加任何想要添加到错误响应中的信息。如果它对你真的有用，没有理由不这样做。 Facebook 就是这样做的。另一方面，我会尽量不让错误响应膨胀。

一个设计良好且解耦的 REST API暗示借助 HTTP 错误代码的标准定义来解决大部分错误原因，这些错误代码仍应记录在 API 文档中。鉴于此，客户端的开发人员只有通过解析错误状态才能知道确切的错误。

这也意味着客户端开发人员需要立即检查所有可以检查的内容，而无需向后端发送任何请求。例如，如果给定的日期范围是有效的。

说明这一点，如果无法使用返回的错误代码来找出请求的确切问题，则 API 接口的设计可能不是最佳的。

虽然 REST 只是一个概念，但几乎不可能实现完美的 RESTfull API，因此总是有例外，恕我直言。

Answer 2

虽然这个问题往往会吸引基于意见的答案，但我会尝试提供一些可能有用的提示。

您的 API 似乎可以验证用户输入。此输入可能因各种原因无效（例如，没有可解析的日期、过去的日期等）。这永远不能仅通过 HTTP 状态代码反映出来，因此，返回 HTTP 400 和验证错误消息，就像您已经做的那样，是一种很好的做法。

此验证错误消息应该是人类可读的，并且客户端应该可以将其显示给用户。如果包含字段名称（如您的示例中所示），客户端甚至可以突出显示关联的输入字段并在其旁边显示错误消息。

如果您的 API 的使用者不是 UI，而是某种自动化服务，那么与错误相关的技术领域可能更适合需求。 （这就是意见发挥作用的地方：许多人说 API 应该与消费客户端类型无关）。但我认为在您的情况下，您应该调查为什么客户端无法显示 errorMsg - 这应该是将来添加额外验证的最佳和最灵活的方法。