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

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

API debugging到底是什么

調(diào)試的目的是為了梳理清楚輸入和輸出之間的關(guān)系。通常都是基于可觀察到的現(xiàn)象來定位問題的根本原因。但當(dāng)我們同時(shí)使用了不同服務(wù)商提供的API或者不同的API資源時(shí)，就可能會(huì)加大我們調(diào)試的難度。

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

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

• 先定位因?yàn)橐鹪搯栴}的API
• 檢查狀態(tài)信息
• 更深入地檢查數(shù)據(jù)

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

1、定位API

第一步就是定位出引起問題的API，并確定該問題確實(shí)是因?yàn)樵揂PI的調(diào)用，或者API本身，或API內(nèi)部處理過程，或者是完全無關(guān)的東西導(dǎo)致的。重新復(fù)現(xiàn)問題并深入定位該問題，從而方便我們進(jìn)一步分析問題，同時(shí)我們還可以調(diào)整傳遞給該API的輸入?yún)?shù)，并分析輸出信息。如果通過該方法依然無法辨別輸入和輸出之間的關(guān)系，那么問題可能不是出在API調(diào)用本身，而是其他原因?qū)е碌模热绲谌椒?wù)或基礎(chǔ)架構(gòu)的更改導(dǎo)致了這種意想不到的行為。

Figure 1 復(fù)現(xiàn)問題，從而進(jìn)行深入分析

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

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

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

400表示請(qǐng)求參數(shù)錯(cuò)誤，我們可以查找是否存在語法錯(cuò)誤，如輸入錯(cuò)誤或畸形的JSON正文。

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

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

3、深入分析

下一步是深入挖掘并驗(yàn)證我們的假設(shè)。我們可以驗(yàn)證是否正確地發(fā)送了每個(gè)請(qǐng)求，并正確地解析了每個(gè)響應(yīng)。當(dāng)我們沿著API調(diào)用序列傳遞數(shù)據(jù)時(shí)，還可以驗(yàn)證變量的定義和引用是否正確。

以下是處理HTTP api時(shí)常見的問題:

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

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

Figure 3 使用控制臺(tái)進(jìn)行問題的定位

調(diào)整策略

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

1、蠻力策略

如果您對(duì)系統(tǒng)的分析方法有限，這意味著您需要調(diào)整并記錄所有內(nèi)容。在整個(gè)API調(diào)用序列的某些點(diǎn)上添加戰(zhàn)略日志語句可能會(huì)很有幫助。但是，大量的日志會(huì)降低性能，因?yàn)樾枰嗟臅r(shí)間來處理日志數(shù)據(jù)。

2、回溯策略

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

3、逐個(gè)各個(gè)擊破

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

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

一段時(shí)間后，專注于一個(gè)問題而沒有取得進(jìn)展可能會(huì)對(duì)自己喪失定位問題的信心，因?yàn)榇藭r(shí)我們已經(jīng)沒有任何頭緒了。下面的策略可以幫助您獲得更有效的調(diào)試心態(tài)。

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

在調(diào)試時(shí)節(jié)省時(shí)間和精力

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

原文鏈接：

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