PCon全球产品创新大会最新日程一览,这里直达 了解详情
写点什么

API 请求失败后发生了什么?

  • 2021 年 2 月 01 日
  • 本文字数:3243 字

    阅读完需:约 11 分钟

API请求失败后发生了什么?

当一个 API 请求没能成功的时候,客户端最好能收到一个正确的 HTTP 错误状态,例如 409 或 500,这会是一个好的开始。不幸的是,尽管 400 Bad Request 可能就足够让我们知道错误出在哪里,但常见的情况是我们没有充足的信息来理解或解决实际遇到的问题。


许多 API 会在响应正文中为你提供更多细节,但令人遗憾的是,每个 API 都有自己的定制风格,不同的 API,甚至在各个端点使用的报告样式都不一样。这就需要定制的逻辑或者人工干预才能理解报告的内容。


但这种情况并非无可避免。先不用急着否定我。试着想象一个更好的世界,其中每个 API 都以相同的标准格式返回错误信息。


我们可以用一致的标识符来识别各种类型的错误,并能在任何地方轻松获得清晰的描述和元数据。你的通用 HTTP 客户端可以自动为任何错误提供详尽细节,你的客户端错误处理机制则能轻松可靠地过滤出你所关心的特定错误,并且你能使用单组共享逻辑来处理多种 API 的常见错误。


IETF 提出的 RFC 7807 标准希望定义一个 HTTP API 错误响应的标准格式,从而实现上述目标。它已经开始在现实世界中得到应用了。人们可以很容易地用它来支持现有的 API 和客户端,对于构建或使用 HTTP API 的人来说,这个标准值得关注。

标准错误格式为什么这么有用?



请不要这样做


谈这个问题前,让我们先退一步思考问题。HTTP 的一个关键特性是标准的响应状态代码,例如 200 或 404。正确使用这些代码可确保客户端自动理解响应的总体状态,并根据对应状态采取适当措施。


状态代码对错误处理来说特别有用。当请求收到意外的 500 状态时,几乎所有标准的 HTTP 客户端都会自动为你抛出一个错误,并不需要自定义规则来解析和解释各处的所有响应,从而确保意外错误能被可靠地报告,并可以在任何位置轻松处理。


这是很好的机制,但它也有很大的局限性。


实际上,一个 HTTP 400 响应可能表示以下任何一种情况:


  • 你的请求格式错误,无法解析

  • 你的请求意外为空,或缺少一些必需的参数

  • 你的请求有效,但仍然模棱两可,因此无法处理

  • 你的请求有效,但由于服务器错误,服务器认为请求无效

  • 你的请求有效,但请求的是完全不可能的内容

  • 你的请求已启动,但服务器拒绝了你提供的参数值

  • 你的请求已启动,但服务器拒绝了你提供的每个参数值

  • 你的请求已启动,但你的银行拒绝了其中包含的银行卡资料

  • 你的请求完成了一项购买操作,但请求的其他部分在稍后阶段被拒绝


这些全是错误,看起来都是由一个“坏”请求触发的 400 错误,但它们的内容却大相径庭。


状态代码可帮助我们区分错误和成功状态,但没法区分得太细致。因此,HTTP 客户端库不能在抛出的错误中包含任何有用的细节,每个 API 客户端都必须编写自定义的处理机制来解析每个失败的响应,并自行找出可能的原因和下一步应该做的操作。


如果失败的 HTTP 请求自动抛出的异常消息不仅仅是HTTP Error: 400 Bad Request,而是 Credit card number is not valid,这样岂不更好?


只要错误有一套标准格式,上面提到的每个错误就都可以有自己的唯一标识符,并包含标准化的说明内容和指向更多细节的链接。好处是:


  • 通用工具可以为你解析和解释错误的详细信息,而无需事先了解任何与 API 相关的信息。

  • API 能更安全地发起错误响应,因为它知道这些错误类型标识符意味着即使解释消息发生了更改,客户端也会一直按同一种理解方式识别错误。

  • 自定义 API 客户端可以检查错误类型以轻松处理特定情况,所有操作都以一种标准方式进行,适用于你所使用的每个 API,而无需从头开始编写 API 包装程序,也用不着每次都和 API 文档大战三百回合。


提案的错误格式长什么样?


为此,RFC7807 提出了一组用于返回错误的标准字段,以及两种将其格式化为 JSON 或 XML 的内容类型。


格式如下:


{    "type": "https://example.com/probs/out-of-credit",    "title": "You do not have enough credit.",    "detail": "Your current balance is 30, but that costs 50.",    "instance": "/account/12345/transactions/abc"}
复制代码


对于 XML 的等效格式:


<?xml version="1.0" encoding="UTF-8"?><problem xmlns="urn:ietf:rfc:7807">    <type>https://example.com/probs/out-of-credit</type>    <title>You do not have enough credit.</title>    <detail>Your current balance is 30, but that costs 50.</detail>    <instance>/account/12345/transactions/abc</instance></problem>
复制代码


这些 RFC 为此定义了两种新的对应内容类型:application/problem+jsonapplication/problem+xml。返回错误的 HTTP 响应应在其Content-Type响应标头中包含适当的内容类型,并且客户端可以检查该标头以确认格式。


这个示例包括规范定义的一些标准化字段。完整列表是如下:


  • type:标识错误类型的 URI。在浏览器中加载这个 URI 应该转向这个错误的文档,但这不是严格要求的。此字段可用于识别错误类。理论上讲,将来站点甚至可以为常见情况共享标准化的错误 URI,以使通用客户端自动检测到它们。

  • title:错误的简短可读摘要。这是明确的指引,客户端必须使用 type 作为识别 API 错误类型的主要方式。

  • detail:较长的人类可读解释,带有完整的错误详细信息。

  • status:错误使用的 HTTP 状态代码。它必须与实际状态匹配,但可以包含在这里的 body 中以便参考。

  • instance:标识该特定故障实例的 URI。它可以作为发生的这个错误的 ID,和/或到特定故障更多详细信息的链接,例如显示失败的信用卡交易细节的页面。


所有这些字段都是可选的(不过type是强烈建议使用的)。内容类型允许自由包含其他数据,只要它们不与这些字段冲突即可,因此你也可以在此处添加自己的错误元数据,并包含所需的其他任何数据。实例 URI 和类型 URI 都可以是绝对 URI,也可以是相对 URI。


这里的思想是:


  • 通过返回带有合适Content-Type标头的错误响应,API 能很容易地表明它们正在遵循这一标准。

  • 这是一组简单的字段,可以轻松添加到大多数现有的错误响应顶部(如果还没有添加的话)。

  • 客户端只需在请求中包含Accept: application/problem+json(和/或+xml)标头,即可轻松表明支持状态,从而在必要时进行迁移。

  • 客户端逻辑可以轻松识别这些响应,并使用它们来显著改善通用和按 API 区分的 HTTP 错误处理操作。

怎样开始使用它呢?

目前,这是一个提案的标准,因此它尚未普及,并且在理论上可能会发生变化。


不过它已经用在很多地方,包括 5G 标准之类中,并且有了适用于大多数语言和框架的一些便捷工具,包括:



也就是说,它已经渗透到了大多数主流生态系统中站稳了脚跟,并且即将更进一步:让更多 API 和客户端开始使用,直到实现大规模的普及状态,即大多数 API 的错误格式都遵循其标准,使它成为所有场景的默认值,让我们大家都能从中受益。


我们该如何做到这一点呢?

如果你在构建或维护一个 API:

  • 如果可以的话,请尝试使用适当的Content-Type响应标头以RFC 7807格式返回错误。

  • 如果你有了一种错误格式,并且需要维护该格式以保证兼容性,请检查是否可以在格式顶部添加这些字段,并对其进行扩展以符合标准。

  • 如果不能,请尝试检测传入的Accept标头中的支持,并在可能的情况下使用它来将原有的错误格式切换为标准格式。

  • 使用你的 API​​框架(比如这个框架)记录错误,表明它们将来会转向标准错误格式。

如果你在使用一个 API:

  • 检查这些内容类型的错误响应,并用那里提供的数据改进你的错误报告和处理工作。

  • 考虑在请求中包含带有这些内容类型的Accept标头,以表明支持状态并在可用时启用标准错误。

  • 向你使用的 API 提出抱怨,希望它们以这种标准格式返回错误,就像抱怨那些不会费心返回正确状态代码的 API 一样。

至于大家:

  • 参与其中!这是 IETF 新的“HTTP API 的构建块”工作组旗下的规范。你可以加入邮件列表以阅读并参与有关该规范和其他可行 API 标准规范规范的讨论,包括速率限制API弃用等。

  • 向你的同事和开发者朋友做宣传,并帮助大家简化错误处理的工作。


原文链接:


https://httptoolkit.tech/blog/http-api-problem-details/

2021 年 2 月 01 日 13:311764
用户头像
王强 技术是文明进步的力量

发布了 651 篇内容, 共 245.7 次阅读, 收获喜欢 1430 次。

关注

评论

发布
暂无评论
发现更多内容

图解堆排序

Silently9527

Java 排序算法 堆排序

Oracle Sql性能优化

大数据技术指南

oracle 大数据 28天写作 3月日更

JDK8新特性 Fork/Join 的优化

Java小咖秀

Java java8 jdk8 forkjoin fork

拍乐云创始人&CEO赵加雨:深耕18载,打造全景式音视频服务

拍乐云Pano

音视频 WebRTC 在线教育 RTC 实时通信

寻找被遗忘的勇气(十七)

Changing Lin

3月日更

C语言中“野指针”、“悬空指针”是什么?

不脱发的程序猿

c 指针 编程之路 bug 3月日更

朋友,你听说过跨域吗

河磨

spring CORS 跨域

有道技术沙龙 | AI 语音交互技术在语言学习场景的实践

有道技术团队

人工智能

数据驱动业务:一张大屏掌控城市运行,效率提高95%

一只数据鲸鱼

物联网 数据可视化 智慧城市 智慧园区 智慧交通

带你走进与千万数据通信者共成长的“家园”

华为云开发者社区

华为 开发者 网络 华为数据通信 社区

【LeetCode】不同的子序列Java题解

HQ数字卡

算法 LeetCode 28天写作 3月日更

架构师训练营第十一周作业 - 命题作业

阿德儿

沙龙报名 | 云计算进入多元架构,云原生时代的挑战与机遇

京东科技开发者

云计算 云原生

跟公司新招的这个“同事”搭档,工作搬砖太“自动化”了

华为云开发者社区

华为 AI RPA 自动化 员工

电商千万级交易的金手指:分布式事务管理

华为云开发者社区

微服务 事务 华为云 分布式事务管理 DTM

你遇到过哪些质量很高的 Java 面试?

张小方

Java 面试 阿里 薪资

看故事学Redis:再不懂,我怀疑你是假个开发

华为云开发者社区

MySQL 数据库 redis 缓存 数据

第8周大作业

八达鸟

SDK 是如何存储事件数据的?

神策技术社区

ios 大数据 存储 数据采集 神策数据

阿里P8大牛亲自教你!一个三非渣本的Android校招秋招之路,满满干货指导

欢喜学安卓

android 程序员 面试 移动开发

多端框架开发 | 拼团商城项目开发说明

APICloud

小程序云开发 大前端 移动终端 APP开发 多端开发

OpenKruise v0.8.0 核心能力解读:管理 Sidecar 容器的利器

阿里巴巴云原生

容器 微服务 云原生 k8s 应用服务中间件

TcaplusDB君 · 行业新闻汇编(3月17日)

TcaplusDB

数据库 nosql 后端 TcaplusDB Tcaplus

私藏干货 | 实现分布式锁的三种方案对比

架构精进之路

分布式锁 3月日更

一招让Kafka达到最佳吞吐量

万俊峰Kevin

kafka go-zero Go 语言

智慧公安二维码定位报警系统开发,微警务平台解决方案

源中瑞-龙先生

二维码定位报警系统开发 智慧公安 智慧公安扫码

区块链数字版权管理,区块链赋能知识产权保护

13530558032

区块链数字版权管理,区块链赋能知识产权保护

13530558032

EGG公链生态项目——EFTalk上的巴莱特定律

币圈那点事

区块链

LeetCode题解:647. 回文子串,动态规划,JavaScript,详细注释

Lee Chen

算法 大前端 LeetCode

阿里P8大牛亲自讲解!2021年Android网络编程总结篇,醍醐灌顶!

欢喜学安卓

android 程序员 面试 移动开发

API请求失败后发生了什么?-InfoQ