HTTP 响应的标准化错误格式

 

HTTP 使用状态代码来指示服务器尝试满足请求的结果。如果服务器无法处理请求，我们可以从各种HTTP错误代码中进行选择。

遗憾的是，仅靠状态代码通常无法为 API 客户端提供足够的信息。例如，服务器可能使用状态代码 400（错误请求）进行响应，以指示客户端发送了无效请求。如果响应机构能告诉我们请求的哪个特定部分是无效的，或者如何解决问题，那不是很好吗？

状态代码用于定义更高级别的错误类，而错误详细信息通常是响应正文的一部分。许多 API 对响应正文使用自定义错误格式来提供其他问题信息。但是，还有一个标准可以帮助我们，在RFC 2707中定义。

FC 7807 定义了 JSON 和 XML 中问题详细信息的数据模型。在为API提出新的通用故障或错误响应格式之前，可能值得研究RFC 7807。但是，如果更适合您的应用程序，则使用自己的特定域的格式是绝对可以的。

 

RFC 7807：HTTP API 的问题详细信息

使用 RFC 7807 的 HTTP 响应可能如下所示：

​

像往常一样，HTTP状态代码（400，错误请求）为我们提供了问题的广泛指示。请注意响应 应用程序/问题+json 的内容类型。这告诉我们响应包含符合 RFC 7807 的正文。当使用 XML 而不是 JSON 时，将使用内容类型应用程序/问题 + xml。

问题详细信息 JSON 响应可以具有以下成员：

• 类型（字符串） – 标识问题类型的 URI 引用。
• title（字符串）– 问题类型的简短、人类可读的摘要。它不应在同一问题类型的多次出现之间更改，除非出于本地化目的。
• 状态（数字）– 源服务器生成的 HTTP 状态代码。
• detail（字符串）– 此特定问题发生的人类可读描述。
• 实例（字符串）– 标识与此特定问题事件相关的资源的 URI。

所有字段都是可选的。但是，您至少应提供一个类型值，因为使用者使用它来标识特定的问题类型。使用者不应解析标题或详细信息字段。

问题类型

问题类型用于标识特定问题。问题类型必须记录：

• 类型 URI（在响应的类型字段中使用）。
• 描述问题的标题（在响应的标题字段中使用）。
• 与之一起使用的 HTTP 状态代码。

 

类型 URI 应解析为人类可读的问题文档（例如 HTML 文档）。此 URI 应受您的控制，并且随时间推移而稳定。

问题类型还可以指定使用“重试后”响应标头（如果适用）。

RFC 7807 保留一个特殊的 URI 作为问题类型：关于：空白。如果问题除了 HTTP 状态代码的语义之外没有其他语义，则可以使用关于：blank 的问题类型。在这种情况下，标题应与该代码的 HTTP 状态短语相同（例如，HTTP 状态 400 的错误请求）。

扩展成员

问题类型可能会使用其他成员扩展问题详细信息对象，以提供其他信息。

上面显示的示例响应中的字段成员是此类扩展成员的示例。它属于必填字段缺失问题类型，并指示缺失字段。使用者可能会分析此成员，以便为最终用户构造适当的错误消息。

结论

仅靠 HTTP 状态代码通常不足以提供有意义的问题描述。

RFC 7807 定义了一种标准化格式，用于在 HTTP 响应正文中进行更详细的问题描述。在提出另一种自定义错误响应格式之前，最好先查看 RFC 7807 问题格式。

 

新的问题

更详细的错误消息对开发人员来说很好，但对生产站点来说很糟糕。生产中的详细错误消息为攻击者（“不良行为者”）提供的信息将使他们能够更快地调整失败为成功攻击的攻击请求。

例如，如果攻击者尝试访问 /admin（或其他敏感）目录，而您返回了 401 或 403，则攻击者现在知道存在这样的目录。并且根据尝试的d目录名称，可能能够确定您正在使用php，dnn或其他应用程序（您通过“告诉”用户该目录存在而无意中泄露了有关您网站的信息...），或者有一个您不希望他们输入的目录...你正在将目标画在他们接下来将要处理的东西上。相反，如果您为所有错误返回一般错误消息（来自具有相同文本的同一URL的相同相同错误消息 -），则对手不知道接下来要尝试什么。

失败可能是404（但他们不知道...您提供了一个通用（“不起作用”错误，其中没有提到“404”，还记得吗？因此，用户将尝试不同的目录（在这种情况下，您的 /admin 目录是安全的，或者在接下来的一个小时里尝试其他方法来访问可能在那里但隐藏的 /admin 目录）。如果对所有错误使用相同的错误消息，则对手不知道要“修复”什么才能使攻击成功。

这将使开发人员处于不利地位 ,但他们可以使用其他工具（“调试”，Web日志等）来确定出了什么问题，以便他们可以“修复”它。