API請求失敗後發生了什麼？

{"type":"doc","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"當一個API請求沒能成功的時候，客戶端最好能收到一個正確的HTTP錯誤狀態，例如409或500，這會是一個好的開始。不幸的是，儘管400 Bad Request可能就足夠讓我們知道錯誤出在哪裏，但常見的情況是我們沒有充足的信息來理解或解決實際遇到的問題。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"許多API會在響應正文中爲你提供更多細節，但令人遺憾的是，每個API都有自己的定製風格，不同的API，甚至在各個端點使用的報告樣式都不一樣。這就需要定製的邏輯或者人工干預才能理解報告的內容。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"但這種情況並非無可避免。先不用急着否定我。試着想象一個更好的世界，其中每個API都以相同的標準格式返回錯誤信息。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"我們可以用一致的標識符來識別各種類型的錯誤，並能在任何地方輕鬆獲得清晰的描述和元數據。你的通用HTTP客戶端可以自動爲任何錯誤提供詳盡細節，你的客戶端錯誤處理機制則能輕鬆可靠地過濾出你所關心的特定錯誤，並且你能使用單組共享邏輯來處理多種API的常見錯誤。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"IETF提出的RFC 7807標準希望定義一個HTTP API錯誤響應的標準格式，從而實現上述目標。它已經開始在現實世界中得到應用了。人們可以很容易地用它來支持現有的API和客戶端，對於構建或使用HTTP API的人來說，這個標準值得關注。"}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"標準錯誤格式爲什麼這麼有用？"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/a9\/a95598c1b2d1e1c3f6e0b1b3dc759dfa.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":"center","origin":null},"content":[{"type":"text","text":"請不要這樣做"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"談這個問題前，讓我們先退一步思考問題。HTTP的一個關鍵特性是標準的響應狀態代碼，例如200或404。正確使用這些代碼可確保客戶端自動理解響應的總體狀態，並根據對應狀態採取適當措施。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"狀態代碼對錯誤處理來說特別有用。當請求收到意外的500狀態時，幾乎所有標準的HTTP客戶端都會自動爲你拋出一個錯誤，並不需要自定義規則來解析和解釋各處的所有響應，從而確保意外錯誤能被可靠地報告，並可以在任何位置輕鬆處理。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"這是很好的機制，但它也有很大的侷限性。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"實際上，一個HTTP 400響應可能表示以下任何一種情況："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求格式錯誤，無法解析"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求意外爲空，或缺少一些必需的參數"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求有效，但仍然模棱兩可，因此無法處理"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求有效，但由於服務器錯誤，服務器認爲請求無效"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求有效，但請求的是完全不可能的內容"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求已啓動，但服務器拒絕了你提供的參數值"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求已啓動，但服務器拒絕了你提供的每個參數值"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求已啓動，但你的銀行拒絕了其中包含的銀行卡資料"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"你的請求完成了一項購買操作，但請求的其他部分在稍後階段被拒絕"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"這些全是錯誤，看起來都是由一個“壞”請求觸發的400錯誤，但它們的內容卻大相徑庭。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"狀態代碼可幫助我們區分錯誤和成功狀態，但沒法區分得太細緻。因此，HTTP客戶端庫不能在拋出的錯誤中包含任何有用的細節，每個API客戶端都必須編寫自定義的處理機制來解析每個失敗的響應，並自行找出可能的原因和下一步應該做的操作。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"如果失敗的HTTP請求自動拋出的異常消息不僅僅是"},{"type":"codeinline","content":[{"type":"text","text":"HTTP Error: 400 Bad Request"}]},{"type":"text","text":"，而是Credit card number is not valid，這樣豈不更好？"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"只要錯誤有一套標準格式，上面提到的每個錯誤就都可以有自己的唯一標識符，幷包含標準化的說明內容和指向更多細節的鏈接。好處是："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"通用工具可以爲你解析和解釋錯誤的詳細信息，而無需事先了解任何與API相關的信息。"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"API能更安全地發起錯誤響應，因爲它知道這些錯誤類型標識符意味着即使解釋消息發生了更改，客戶端也會一直按同一種理解方式識別錯誤。"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"自定義API客戶端可以檢查錯誤類型以輕鬆處理特定情況，所有操作都以一種標準方式進行，適用於你所使用的每個API，而無需從頭開始編寫API包裝程序，也用不着每次都和API文檔大戰三百回合。"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"提案的錯誤格式長什麼樣？"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"爲此，RFC7807提出了一組用於返回錯誤的標準字段，以及兩種將其格式化爲JSON或XML的內容類型。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"格式如下："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"{\n \"type\": \"https:\/\/example.com\/probs\/out-of-credit\",\n \"title\": \"You do not have enough credit.\",\n \"detail\": \"Your current balance is 30, but that costs 50.\",\n \"instance\": \"\/account\/12345\/transactions\/abc\"\n}"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"對於XML的等效格式："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"\n\n https:\/\/example.com\/probs\/out-of-credit\n