REST API 是否应该在响应正文中返回异常？

Question

使用 Web API 的 .NET 最佳实践是什么？特别是 Web REST API。当异常发生时，REST API 是否应该在响应正文中返回异常？

我肯定会返回 500 或类似的 HTTP 状态。但是，当我用此错误代码响应时，最佳实践是什么？或者更好的是关于此的规范或 REST API 是什么？

• 返回异常（我所做的）
• 返回空响应正文？ （是的，但是我们丢失了有助于调试的信息）
• 返回一个空的默认 JSON 对象？ （我觉得这很混乱）
• 还有什么吗？

Answer 1

返回异常（我所做的） -> 您不应按原样返回异常，因为： 1) 它可能包含您不希望向 REST API 用户公开的信息。例如，在 IO 异常的情况下考虑文件路径，在 sql 异常的情况下考虑 sql 服务器信息，等等。 2) 您将发送 REST API 客户端不需要的信息，从而浪费带宽并序列化不必要的信息。

返回空响应正文？ -> 没有。

返回一个空的默认 JSON 对象？ -> 没有。

还有别的事吗？ -> 返回一条非常具体的错误消息（以及您认为可能对集成 REST API 的开发人员有帮助的任何其他信息，以解决该错误，或者如果向您提供了该错误消息，则可以帮助您跟踪该错误。毕竟您必须在某个时候调查某些问题，因此请确保您传递的信息足以让您了解出了什么问题）。

Answer 2

我有这个建议。

• 错误需要由应用程序（API）中的某些过滤器来处理。此过滤器将收到意外错误，将错误转换为 JSON，http 状态代码等于 500。

• 返回的错误需要具有相同的JSON格式，如下所示：

  {
      code: 12321312,
      message: "A fatal error occurred",
      details: "An unexpected information was passed as parameter to the API."
  }
  

• 错误格式需要提供信息。当您在过滤器中收到错误时，您可以使用生成的代码（错误代码，如 UUID）将错误保存在数据库中，并以 JSON 形式返回

  code

  。要拥有一个好的 API，使用错误代码将是一个很好的功能，并且可以帮助您识别问题。

Answer 3

无论如何，是的，您应该在响应正文中包含异常的表示。异常将是对错误的最好解释，并且对于帮助用户纠正任何错误将是最有帮助的。我建议所有错误的响应代码为 400，但是 400 范围内的任何数字都是可接受的。

我做了一些研究，发现最常见/标准使用这种形式的 JSON 结构：

{
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

其中许多都是可选的，但以防万一您需要它们。这个结构的重要一点是错误是在成员“error”下的对象中描述的。

这是 OASIS 数据标准 OASIS OData 提出的格式，似乎是最标准的选项，但目前任何标准的采用率似乎都不高。

详细信息已在我的博客文章中讨论 - 我已删除该链接，因为管理员认为这是自我推销，并已删除带有博客文章链接的答案。如果你想找的话，自行Google搜索吧，在StackOverflow这里是找不到的。