當我們使用了一些由別人實現的API接口時，該如何進行調試呢？當我們使用的API返回一些意想不到錯誤時，該怎么辦呢?這個問題可能是由于用戶輸入或者API本身，或者其他完全無關的內容等引起的。調試是我們進行定位并修復由單個API調用或一系列調用引發(fā)的問題。通常，我們可以調試我們不能完全把握的代碼，從而可以清晰地了解該部分代碼。我們在使用API時，除了遇到意想不到的異常外，還有可能在解析輸出或傳遞變量時出錯。

在本篇文章中，我們將深入研究快速地、可靠地調試REST API的方法和原則。

API debugging到底是什么

調試的目的是為了梳理清楚輸入和輸出之間的關系。通常都是基于可觀察到的現象來定位問題的根本原因。但當我們同時使用了不同服務商提供的API或者不同的API資源時，就可能會加大我們調試的難度。

理想情況下，我們會使用一個穩(wěn)定的測試和監(jiān)控系統(tǒng)，當問題出現時，這個系統(tǒng)可以提醒我們，并且?guī)臀覀兂醪酱_定出現該問題的原因。同時即使您沒有這種高級別的監(jiān)控系統(tǒng)時，一些常見的有效的方法也可以幫助我們減少查找和修復問題所需的時間和精力。

下面列是一種定位問題的方法:

• 先定位因為引起該問題的API
• 檢查狀態(tài)信息
• 更深入地檢查數據

接下來，我將會使用Postman來演示這種調試方法，但這種方法同樣可以適用于其他的開發(fā)工具的。

1、定位API

第一步就是定位出引起問題的API，并確定該問題確實是因為該API的調用，或者API本身，或API內部處理過程，或者是完全無關的東西導致的。重新復現問題并深入定位該問題，從而方便我們進一步分析問題，同時我們還可以調整傳遞給該API的輸入參數，并分析輸出信息。如果通過該方法依然無法辨別輸入和輸出之間的關系，那么問題可能不是出在API調用本身，而是其他原因導致的，比如第三方服務或基礎架構的更改導致了這種意想不到的行為。

Figure 1 復現問題，從而進行深入分析

2、檢測狀態(tài)碼

當我們通過API進行交互時，服務器會返回一個HTTP狀態(tài)碼，該代碼表示我們API請求的狀態(tài)。這個狀態(tài)碼和錯誤消息由API提供者確定，因此它們的意義和準確性各不相同。但是大多數API提供方通常會使用狀態(tài)代碼的第一個數字來反應響應類，如400表示客戶端有問題，此時更新請求可以解決該問題；500表示服務器有問題，此時我們除了驗證正在訪問適當的資源并進行檢查之外，沒有什么可以做的了，除非是API的實現方。

服務器返回可靠的狀態(tài)消息是我們追蹤錯誤來源的第一線索。以下是一些常見的客戶端錯誤代碼，再此處我分別說明了對應的解決方法：

400表示請求參數錯誤，我們可以查找是否存在語法錯誤，如輸入錯誤或畸形的JSON正文。

• 401表示未經授權，我們需要確實是否有訪問對應目標資源的有效認證憑證，同時確認沒有語法問題。
• 403表示服務器拒絕請求，此時可以檢查我們具有的權限和范圍，以確保能被授權訪問資源。
• 418表示我是茶壺(I 'm a Teapot)，可能表示請求是提供者不想處理的請求，例如自動查詢。
• 429表示太多的請求，此時我們可以檢查文檔，以便了解使用頻率限制或著稍后再試。

Figure 2 用4開頭的錯誤碼來說明客戶端存在異常

3、深入分析

下一步是深入挖掘并驗證我們的假設。我們可以驗證是否正確地發(fā)送了每個請求，并正確地解析了每個響應。當我們沿著API調用序列傳遞數據時，還可以驗證變量的定義和引用是否正確。

以下是處理HTTP api時常見的問題:

• 畸形的JSON：新手在發(fā)送JSON時會犯一些常見的錯誤。在JSON字符串中，單引號無效，因此請確保將字符串和屬性名用雙引號括起來。此外，JSON不支持注釋，所以要么盡量簡化，要么根本不添加它們。
• 序列化數據：REST api經常以JSON對象的形式存儲和發(fā)送數據。為了正確傳輸數據，請確保使用JSON.stringify()對數據進行編碼，并使用JSON.parse()對其進行解碼。此外，服務器可能要求您設置一個application/json類型的Content-Type頭。進一步檢查后，如果您看到像[object object]或Unexpected token這樣的值，這表明我們非法的進行了序列化和反序列化。
• 類型轉換：在準備發(fā)送請求或解析響應時，可以將值從一種類型轉換為另一種類型。根據編程語言的不同，對字符串執(zhí)行數學計算可能會導致失敗，但當我們將字符串轉換為數字時，就可以處理轉換后的數據了。
• 提取信息：使用JSON.parse()反序列化JSON響應后，就可以使用點或括號符號訪問所有信息。如果您試圖訪問一個復雜結構中的深層嵌套信息，您可能需要一步一步地將其分解，以精確地引用該信息，并確保您不會試圖使用到一些未定義的東西中。
• 身份驗證與授權：身份驗證是指驗證用戶的身份，而授權則確認用戶擁有訪問資源的權限。如果請求中包含了適當的授權頭，但仍然不能訪問資源，請仔細檢查與憑據相關的權限和作用域。
• Content type頭：Content- type和Accept頭有助于在客戶端和服務器之間進行內容協(xié)商。Content-type請求頭告訴服務器，客戶端發(fā)送的信息類型。而Accept請求頭告訴服務器，客戶機可以理解什么類型的內容。一些api需要特定的請求頭，并且只處理特定的內容類型。

對于這些常見的錯誤，可以依靠語法高亮顯示、檢查器和其他檢查功能來幫我們來檢查。同時我們可以利用開發(fā)人員控制臺來查看應用程序的網絡調用和日志語句，從而可以根據其提供的輸入、輸出和從一個調用到另一個調用傳遞數據來幫助我們定位問題，例如，如果您有一個同步或異步調用序列，記錄關鍵結點的值或設置條件斷點來進一步快速查明問題所在。在整個調用執(zhí)行過程中使用console.log()這樣的控制臺語句可以進一步驗證我們的假設解析輸出。

Figure 3 使用控制臺進行問題的定位

調整策略

許多調試策略有利于縮小問題的原因。這些策略大致可分為三類。

1、蠻力策略

如果您對系統(tǒng)的分析方法有限，這意味著您需要調整并記錄所有內容。在整個API調用序列的某些點上添加戰(zhàn)略日志語句可能會很有幫助。但是，大量的日志會降低性能，因為需要更多的時間來處理日志數據。

2、回溯策略

這種策略是指從第一次發(fā)現錯誤的地方向后移動，直到找到錯誤的根本原因。類似地，可以從顯示預期行為的API調用開始，然后逐步執(zhí)行后續(xù)調用，直到找到錯誤。當您對可能導致問題的原因有合理的假設時，這種策略很有效，否則這種策略就不那么有效了。

3、逐個各個擊破

在復雜的系統(tǒng)中，將系統(tǒng)分解成更小的部分可能會讓我們更容易發(fā)現問題。二進制搜索就是這種策略的一個例子，在這種情況下，您可以在一個較長的調用序列中輸入一個日志語句或斷點，假如直到該斷點處時有沒有出現缺陷，則對調用的后半部分重復該過程，以此類推。另一種策略是使用模擬服務器來隔離被測試的系統(tǒng)。您可以依賴模擬響應來獲得外部依賴項，或者為您的場景提供一個起點。

保持調試的心態(tài)

一段時間后，專注于一個問題而沒有取得進展可能會對自己喪失定位問題的信心，因為此時我們已經沒有任何頭緒了。下面的策略可以幫助您獲得更有效的調試心態(tài)。

• 橡皮鴨調試（Rubber duck debugging）:向別人闡明問題和假設可能會迫使你靜下心來，明確地陳述你的假設，從而改變你自己的觀點。
• 從集中模式切換到分散模式(Switch from a focused to diffused mode):完全切換到不同的活動，比如徒步旅行，會讓你的大腦進入一個不同的狀態(tài)。擴散學習模式是當你的大腦被動地建立新的聯系，并可能導致創(chuàng)造性的見解。這就是為什么你在洗澡的時候或者剛醒來的時候會有最好的想法的原因。

在調試時節(jié)省時間和精力

無論您是使用REST api的新手還是經驗豐富的老手，一致和有條理的調試方法可以節(jié)省時間和精力。您選擇的調試策略取決于系統(tǒng)的可觀察性。如果您的系統(tǒng)使用預定義的日志和堆棧跟蹤進行了廣泛的監(jiān)視，那么您可以迅速發(fā)現問題，并可能立即發(fā)現錯誤。如果這些措施沒有到位，您可以簡化問題以減少搜索區(qū)域，并利用其中一些調試策略來定位根因。

原文鏈接：

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