HTTP API 在协调软件应用程序之间无缝价值交换方面发挥着关键作用。这些无形的数据高速公路是我们日常使用的服务（从社交媒体平台到移动银行应用）的基础。然而，与任何形式的通信一样，清晰度和结构至关重要，尤其是在传达“坏消息”时，例如错误。不幸的是，API 交互中有效的错误通信是一个经常被忽视的领域，导致诊断和解决问题时出现混淆、挫败感和效率低下。
这是关于问题详情（Problem Details）的两部分系列文章中的第一部分。如需阅读第二部分，请点击此处。
有效传递坏消息
有效传递坏消息（例如 API 错误）的精髓不仅在于传递本身，还在于确保消息结构化、信息丰富，最重要的是，可操作。从历史上看，API 传达错误的方式差异很大，导致错误格式杂乱无章，每种格式都有其假设和特性。这种不一致性不仅让错误处理成为开发人员的噩梦，还阻碍了不同系统之间的互操作性。随着我们在这个不断增长的 API 迷宫中穿梭，挑战也随之增加。错误响应缺乏标准化不仅仅是一个小麻烦；它是一个障碍。它延长了集成时间，增加了集成成本，并将持续维护变成了真正的总拥有成本 (TCO) 问题。随着新一波 API 消费者（例如 AI 机器人和模型）的出现，这一挑战只会进一步放大。这些消费者要求当前混乱的错误消息无法提供的精确性和清晰度。
认识到这一痛点，互联网工程任务组 (IETF) 引入了 RFC 7807 [1]，《HTTP API 问题详情》，为以更结构化和有用的方式表达错误创建了标准。
随着数字景观的不断演变，标准必须适应新的挑战和见解。因此，RFC 7807 已被 RFC 9457 [2] 取代，这标志着我们如何传达 API 错误的重大演变。此次更新不仅完善了原始标准，还引入了新功能以进一步增强错误报告。本质上，RFC 9457 旨在完善传递坏消息的艺术，确保 API 错误不仅被传达，而且以一种消除假设、帮助快速诊断并促进机器之间更流畅交互的方式进行。
当我们深入探讨 RFC 9457 带来的进步时，理解为什么改进 API 错误报告方法至关重要。这不仅仅是为了让开发人员的工作更轻松；更是为了创建更具弹性、更易理解和更用户友好的数字服务。
API 错误处理反模式
尽管错误处理很重要，但它常常被视为次要考虑，导致一系列反模式，使 API 使用和集成变得复杂。
以下是一些常见的反模式
- 不提供有用的错误反馈：任何 API 的基本期望之一是它能通过提供有意义的反馈来指导消费者解决错误。当 API 未能提供有用的错误消息时，开发人员就会一无所知，被迫依赖猜测、试错和调试来理解出了什么问题。这不仅减慢了开发速度，还增加了集成时间和成本。
- 发明自定义错误通信方式：我们希望提供者在解决 API 问题方面具有创造力，但也许不希望他们在错误通信方面如此。发明独特的错误报告方法，偏离既定标准，会导致缺乏一致性，从而使 API 消费者不得不适应他们使用的每个 API 的不同错误处理机制。这种可变性使通用错误处理例程的开发变得复杂，使集成更加繁琐和容易出错。
- 在成功响应中隐藏错误：有时，API 会在看似成功的响应中隐藏错误，例如将错误详细信息嵌入到 200 OK 状态中。这种做法会误导消费者，让他们认为请求已成功，而实际上并非如此，从而使错误检测和处理变得复杂。它模糊了交互的真实性质，导致误解和有缺陷的应用程序逻辑。
- 泄露堆栈跟踪信息：错误处理不仅影响开发人员体验。糟糕的选择还可能导致安全问题。某些 API 在其错误响应中无意中暴露了过多信息，例如详细的堆栈跟踪。虽然这可能是为了辅助调试，但它会带来重大的安全风险，让潜在攻击者深入了解 API 的底层实现和结构。这种信息泄露可被利用来创建更有针对性的攻击，从而使整个应用程序面临风险。
- 每个 API 响应错误的方式不同：缺乏统一的错误报告方法意味着每个 API 可能选择以不同的方式（在结构和内容方面）传达错误。这种不一致性是 API 消费者面临的最大挑战之一，尤其是在将多个 API 集成到单个应用程序时。它需要为每个 API 定制错误处理，从而增加应用程序的复杂性和维护开销。随着您扩展以提供更多 API，如何处理错误应成为您的 API 治理职责的一部分。
不良 API 错误处理的影响
上述反模式导致了一系列问题，这些问题不仅仅是不便，还会影响 API 的成功。
- 增加开发时间和成本：开发人员花费过多的时间来解读错误并为每个 API 实现自定义处理程序，然后才能确信工作已完成。集成平均时间的增加会增加摄取 API 以及持续维护的总成本。
- 糟糕的开发人员体验：缺乏清晰、一致的错误响应会挫败开发人员，可能会阻止他们使用 API。
- 安全漏洞：通过错误泄露实现细节可能使 API 暴露于安全漏洞。这不是会不会发生的问题，而是何时发生的问题！
- 集成复杂性：不同的错误报告标准增加了集成的复杂性和脆弱性。这很可能导致消费者流失，转而选择更稳定的 API。
什么是 HTTP API 的问题详情（Problem Details）？
最初由 RFC 7807 引入，最近在 RFC 9457 中进一步完善的“HTTP API 问题详情”（Problem Details for HTTP APIs）是一个标准，为以结构化、一致且机器可读的格式表达错误详情提供了蓝图。它旨在使错误响应更具信息性和可操作性，不仅适用于人类开发人员，也适用于在运行时消费 API 的系统。随着 RFC 9457 的发布，该标准已得到增强，以方便包含更多上下文和元数据，从而帮助诊断和解决问题，并提供一个用于托管常见问题类型 URI 的IANA 注册表 [3]。
问题详情（Problem Details）对象结构以一种可以在不同系统和技术之间普遍理解的方式封装了错误信息。
type：一个 URI 引用，用于标识问题类型。它旨在为人工操作员提供一个查找更多错误信息的场所。如果不存在或不适用，则假定为“about:blank”。status：此问题发生时由源服务器生成的 HTTP 状态码。title：问题类型的简短、人类可读的摘要。除本地化目的外，它不应随问题的每次出现而改变。detail：针对此问题发生情况的人类可读解释。与标题不同，此字段的内容可能因每次出现而异。instance：一个 URI 引用，用于标识问题的特定发生情况。如果解除引用，它可能提供或不提供更多信息。- 扩展：可以添加任何字段以向消费客户端提供附加信息或上下文。建议使用扩展而不是要求客户端解析 `detail` 属性。还建议在此处采用“必须忽略”模式，即客户端应如何消费信息，因此它们应忽略任何未明确支持的附加字段。
这是一个包含两个扩展属性（代码和错误数组）的示例问题详情响应 [4]。
{
"type":"https://problems-registry.smartbear.com/missing-body-property",
"status":400,
"title":"Missing body property",
"detail":"The request is missing an expected body property.",
"code":"400-09",
"instance":"/logs/regisrations/d24b2953-ce05-488e-bf31-67de50d3d085",
"errors":[
{
"detail":"The body property {name} is required",
"pointer":"/name"
}
]
}
查看第二部分：问题详情 (RFC 9457)：API 错误处理实战
结论
问题详情（Problem Details）是实现有效 API 错误通信的重要机制。通过解决长期困扰 HTTP API 的常见反模式，该标准为更可靠、安全和用户友好的 API 生态系统铺平了道路。展望未来，采用此类标准化实践的重要性只会继续增长，尤其是在我们日益互联的世界中。