收集结果的 RESTful API 中应该如何处理异常？

Posted 2023-03-31

【中文标题】收集结果的 RESTful API 中应该如何处理异常？

【英文标题】：How should exceptions be handled in a RESTful API for collection results?

【发布时间】：2013-04-16 16:21:42

【问题描述】：

我们正在设计一个 RESTful API 来返回文档集合。我们的初始实现使用 HTTP 状态代码来指示请求是否无法完成。这似乎是一种被广泛接受的最佳实践（例如参见here）。

我们最近遇到了用户提取 1000 个文档的问题。其中一个文档检索失败，因此我们返回了 HTTP 500 状态代码。

另一种方法是返回一个 HTTP 200 状态代码，其中包含我们能够检索到的 999 个文档的有效负载，然后是一个错误集合，指示失败的那个。

这种替代方法是否违反了 RESTful 原则？这种情况应该如何处理？除了这两种方法，还有其他选择吗？

【参考方案1】：

是的，我认为这是完全可以接受的，只要您记录您返回的数据可以包含“错误”集合。这意味着无论您使用什么语义媒体类型来描述此文档集合，都应该具有描述文档集合应该是什么样子以及错误集合应该是什么样子的文档。然后，客户可以决定如何处理这些信息。

例如，如果您将其返回为 JSON（只是一个示例），则您可能有一个类似 application/json+documents 的媒体类型，可能看起来像这样：

 data : 
    documents: [ ... ], //document objects
    errors: [ ... ] //error objects

然后，您将获得描述文档外观和错误外观的文档。在真正的 RESTful API 中，记录的是媒体类型而不是调用，因为在真正的 RESTful API 中只有一个端点，其他所有内容都是通过该初始端点以及语义媒体类型“发现”的。因此，只要您记录了可能发生的错误，并描述了错误将被传递的格式，就应该没问题。

这也不是“异常”情况，因为在您的情况下，可以预见客户可能无法检索所有文档。因此，可以将这一事实告知客户。

【讨论】：

感谢 Vivin 的输入。所以我想一个可能的分界线是这种情况是否被认为是“例外”。如果是，则应返回 HTTP 500 状态。如果情况并非例外，并且可以预期作为 API 正常使用的一部分定期发生，那么 HTTP 200 可能更合适，在（有据可查的！）有效负载内容中发送错误信息。

@JoeAlfano 正确。如果这是他们用户无法真正恢复的实际异常，那么 HTTP 500 就可以了。否则，您可以提供您拥有的任何部分数据以及错误，用户可以决定如何处理。

【参考方案2】：

在这样的特殊情况下，有时您必须跨越一条界限：让用户参与进来。

通知用户payload过大并返回内部服务器错误并非没有道理。