调试是我们进行定位并修复由单个API调用或一系列调用引发的问题。通常，我们可以调试我们不能完全把握的代码，从而可以清晰地了解该部分代码。我们在使用API时，除了遇到意想不到的异常外，还有可能在解析输出或传递变量时出错。

当我们使用了一些由别人实现的API接口时，该如何进行调试呢？当我们使用的API返回一些意想不到错误时，该怎么办呢?这个问题可能是由于用户输入或者API本身，或者其他完全无关的内容等引起的。调试是我们进行定位并修复由单个API调用或一系列调用引发的问题。通常，我们可以调试我们不能完全把握的代码，从而可以清晰地了解该部分代码。我们在使用API时，除了遇到意想不到的异常外，还有可能在解析输出或传递变量时出错。

在本篇文章中，我们将深入研究快速地、可靠地调试REST API的方法和原则。

API debugging到底是什么

调试的目的是为了梳理清楚输入和输出之间的关系。通常都是基于可观察到的现象来定位问题的根本原因。但当我们同时使用了不同服务商提供的API或者不同的API资源时，就可能会加大我们调试的难度。

理想情况下，我们会使用一个稳定的测试和监控系统，当问题出现时，这个系统可以提醒我们，并且帮我们初步确定出现该问题的原因。同时即使您没有这种高级别的监控系统时，一些常见的有效的方法也可以帮助我们减少查找和修复问题所需的时间和精力。

下面列是一种定位问题的方法:

  • 先定位因为引起该问题的API

  • 检查状态信息

  • 更深入地检查数据

接下来，我将会使用Postman来演示这种调试方法，但这种方法同样可以适用于其他的开发工具的。

1、定位API

第一步就是定位出引起问题的API，并确定该问题确实是因为该API的调用，或者API本身，或API内部处理过程，或者是完全无关的东西导致的。重新复现问题并深入定位该问题，从而方便我们进一步分析问题，同时我们还可以调整传递给该API的输入参数，并分析输出信息。如果通过该方法依然无法辨别输入和输出之间的关系，那么问题可能不是出在API调用本身，而是其他原因导致的，比如第三方服务或基础架构的更改导致了这种意想不到的行为。

Figure 1 复现问题，从而进行深入分析

2、检测状态码

当我们通过API进行交互时，服务器会返回一个HTTP状态码，该代码表示我们API请求的状态。这个状态码和错误消息由API提供者确定，因此它们的意义和准确性各不相同。但是大多数API提供方通常会使用状态代码的第一个数字来反应响应类，如400表示客户端有问题，此时更新请求可以解决该问题；500表示服务器有问题，此时我们除了验证正在访问适当的资源并进行检查之外，没有什么可以做的了，除非是API的实现方。

服务器返回可靠的状态消息是我们追踪错误来源的第一线索。以下是一些常见的客户端错误代码，再此处我分别说明了对应的解决方法：

400表示请求参数错误，我们可以查找是否存在语法错误，如输入错误或畸形的JSON正文。

  • 401表示未经授权，我们需要确实是否有访问对应目标资源的有效认证凭证，同时确认没有语法问题。

  • 403表示服务器拒绝请求，此时可以检查我们具有的权限和范围，以确保能被授权访问资源。

  • 418表示我是茶壶(I 'm a Teapot)，可能表示请求是提供者不想处理的请求，例如自动查询。

  • 429表示太多的请求，此时我们可以检查文档，以便了解使用频率限制或着稍后再试。

Figure 2 用4开头的错误码来说明客户端存在异常

3、深入分析

下一步是深入挖掘并验证我们的假设。我们可以验证是否正确地发送了每个请求，并正确地解析了每个响应。当我们沿着API调用序列传递数据时，还可以验证变量的定义和引用是否正确。

以下是处理HTTP api时常见的问题:

  • 畸形的JSON：新手在发送JSON时会犯一些常见的错误。在JSON字符串中，单引号无效，因此请确保将字符串和属性名用双引号括起来。此外，JSON不支持注释，所以要么尽量简化，要么根本不添加它们。

  • 序列化数据：REST api经常以JSON对象的形式存储和发送数据。为了正确传输数据，请确保使用JSON.stringify()对数据进行编码，并使用JSON.parse()对其进行解码。此外，服务器可能要求您设置一个application/json类型的Content-Type头。进一步检查后，如果您看到像[object object]或Unexpected token这样的值，这表明我们非法的进行了序列化和反序列化。

  • 类型转换：在准备发送请求或解析响应时，可以将值从一种类型转换为另一种类型。根据编程语言的不同，对字符串执行数学计算可能会导致失败，但当我们将字符串转换为数字时，就可以处理转换后的数据了。

  • 提取信息：使用JSON.parse()反序列化JSON响应后，就可以使用点或括号符号访问所有信息。如果您试图访问一个复杂结构中的深层嵌套信息，您可能需要一步一步地将其分解，以精确地引用该信息，并确保您不会试图使用到一些未定义的东西中。

  • 身份验证与授权：身份验证是指验证用户的身份，而授权则确认用户拥有访问资源的权限。如果请求中包含了适当的授权头，但仍然不能访问资源，请仔细检查与凭据相关的权限和作用域。

  • Content type头：Content- type和Accept头有助于在客户端和服务器之间进行内容协商。Content-type请求头告诉服务器，客户端发送的信息类型。而Accept请求头告诉服务器，客户机可以理解什么类型的内容。一些api需要特定的请求头，并且只处理特定的内容类型。

对于这些常见的错误，可以依靠语法高亮显示、检查器和其他检查功能来帮我们来检查。同时我们可以利用开发人员控制台来查看应用程序的网络调用和日志语句，从而可以根据其提供的输入、输出和从一个调用到另一个调用传递数据来帮助我们定位问题，例如，如果您有一个同步或异步调用序列，记录关键结点的值或设置条件断点来进一步快速查明问题所在。在整个调用执行过程中使用console.log()这样的控制台语句可以进一步验证我们的假设解析输出。

Figure 3 使用控制台进行问题的定位

调整策略

许多调试策略有利于缩小问题的原因。这些策略大致可分为三类。

1、蛮力策略

如果您对系统的分析方法有限，这意味着您需要调整并记录所有内容。在整个API调用序列的某些点上添加战略日志语句可能会很有帮助。但是，大量的日志会降低性能，因为需要更多的时间来处理日志数据。

2、回溯策略

这种策略是指从第一次发现错误的地方向后移动，直到找到错误的根本原因。类似地，可以从显示预期行为的API调用开始，然后逐步执行后续调用，直到找到错误。当您对可能导致问题的原因有合理的假设时，这种策略很有效，否则这种策略就不那么有效了。

3、逐个各个击破

在复杂的系统中，将系统分解成更小的部分可能会让我们更容易发现问题。二进制搜索就是这种策略的一个例子，在这种情况下，您可以在一个较长的调用序列中输入一个日志语句或断点，假如直到该断点处时有没有出现缺陷，则对调用的后半部分重复该过程，以此类推。另一种策略是使用模拟服务器来隔离被测试的系统。您可以依赖模拟响应来获得外部依赖项，或者为您的场景提供一个起点。

保持调试的心态

一段时间后，专注于一个问题而没有取得进展可能会对自己丧失定位问题的信心，因为此时我们已经没有任何头绪了。下面的策略可以帮助您获得更有效的调试心态。

  • 橡皮鸭调试（Rubber duck debugging）:向别人阐明问题和假设可能会迫使你静下心来，明确地陈述你的假设，从而改变你自己的观点。

  • 从集中模式切换到分散模式(Switch from a focused to diffused mode):完全切换到不同的活动，比如徒步旅行，会让你的大脑进入一个不同的状态。扩散学习模式是当你的大脑被动地建立新的联系，并可能导致创造性的见解。这就是为什么你在洗澡的时候或者刚醒来的时候会有最好的想法的原因。

在调试时节省时间和精力

无论您是使用REST api的新手还是经验丰富的老手，一致和有条理的调试方法可以节省时间和精力。您选择的调试策略取决于系统的可观察性。如果您的系统使用预定义的日志和堆栈跟踪进行了广泛的监视，那么您可以迅速发现问题，并可能立即发现错误。如果这些措施没有到位，您可以简化问题以减少搜索区域，并利用其中一些调试策略来定位根因。

原文链接：

https://stackoverflow.blog/2022/02/28/debugging-best-practices-for-rest-api-consumers/