痛點(diǎn)

你是否曾遇到過以下問題？

1.API錯誤碼形同虛設(shè)，無法提供有效幫助？

2.API錯誤碼文檔晦澀難懂，別說其他團(tuán)隊(duì)，連團(tuán)隊(duì)內(nèi)同事都看不明白？

3.API錯誤碼定義混亂，缺乏一致性？

4.鏈路上的錯誤碼信息無法正確傳遞？

API設(shè)計(jì)的重要性

在軟件架構(gòu)中，API（應(yīng)用程序編程接口）和數(shù)據(jù)庫（DB）的設(shè)計(jì)至關(guān)重要，因?yàn)樗鼈兎謩e代表了系統(tǒng)的外部交互界面和內(nèi)部數(shù)據(jù)存儲機(jī)制。良好的設(shè)計(jì)不僅能夠提高系統(tǒng)的穩(wěn)定性、可擴(kuò)展性和可維護(hù)性，而且在未來進(jìn)行代碼重構(gòu)或系統(tǒng)升級時，也能大大減少對上游服務(wù)和數(shù)據(jù)遷移的影響。

圖片

1）API設(shè)計(jì)的重要性

1.抽象層次：API作為系統(tǒng)與外界交互的接口，提供了一層抽象，隱藏了底層的業(yè)務(wù)邏輯和實(shí)現(xiàn)細(xì)節(jié)。這意味著，只要API的接口保持不變，系統(tǒng)內(nèi)部的實(shí)現(xiàn)可以自由變化而不影響外部調(diào)用者。

2.穩(wěn)定性與兼容性：良好設(shè)計(jì)的API應(yīng)該考慮到向后兼容性，即使在系統(tǒng)升級或重構(gòu)時，也能保證對現(xiàn)有客戶端的支持。這減少了上游服務(wù)調(diào)整的需要，使得系統(tǒng)的迭代更加平滑。

2）數(shù)據(jù)庫設(shè)計(jì)的重要性

1.擴(kuò)展性和可維護(hù)性：隨著系統(tǒng)的發(fā)展，數(shù)據(jù)量會增加，業(yè)務(wù)需求也會變化。一個設(shè)計(jì)良好的數(shù)據(jù)庫能夠更容易地進(jìn)行擴(kuò)展和維護(hù)，比如通過合理的索引設(shè)計(jì)、分表分庫等策略來提高性能。

2.數(shù)據(jù)遷移的便利性：在系統(tǒng)升級或重構(gòu)過程中，可能需要進(jìn)行數(shù)據(jù)遷移。如果數(shù)據(jù)庫設(shè)計(jì)考慮了未來可能的變化，那么數(shù)據(jù)遷移的工作會相對容易和安全。合理的數(shù)據(jù)版本控制和遷移腳本也是重要的一環(huán)。

總之，API和底層數(shù)據(jù)庫的設(shè)計(jì)是軟件架構(gòu)中的關(guān)鍵部分，它們的良好設(shè)計(jì)是確保系統(tǒng)長期健康發(fā)展的基石。通過投入足夠的時間和資源來設(shè)計(jì)和實(shí)現(xiàn)高質(zhì)量的API和數(shù)據(jù)庫，可以在系統(tǒng)的整個生命周期中節(jié)省大量的時間和成本。

在API接口設(shè)計(jì)中，定義接口錯誤碼是至關(guān)重要的一環(huán)。本文將重點(diǎn)討論API錯誤碼的設(shè)計(jì)，而不涉及API的其他方面。

什么是錯誤碼

根據(jù)亞馬遜官方文檔的定義，錯誤碼是通過對錯誤進(jìn)行抽象，幫助用戶或開發(fā)者識別和理解異常性質(zhì)的代號。錯誤碼與具體錯誤不是一對一的關(guān)系，而是錯誤類型的一種抽象表示。盡管錯誤碼在系統(tǒng)中只是一個小模塊，但它是不可或缺的。

錯誤消息應(yīng)該幫助用戶輕松并快速地理解并解決API 錯誤，以下是一些設(shè)計(jì)原則：

1. 不要假設(shè)用戶非常了解你的API。用戶可能是客戶端開發(fā)者、運(yùn)維人員、IT人員或者APP的普通用戶。

2. 不要假設(shè)用戶了解服務(wù)實(shí)現(xiàn)的細(xì)節(jié)或熟悉錯誤上下文（例如日志分析）。

3. 如果可能，應(yīng)構(gòu)建錯誤消息，以便技術(shù)用戶（但不一定是API的開發(fā)人員）可以對錯誤進(jìn)行響應(yīng)并更正。

4. 保持錯誤信息簡短。如果需要，提供鏈接以便用戶能夠提出問題或獲取更多信息。

錯誤碼的設(shè)計(jì)應(yīng)當(dāng)直接解答核心問題：錯誤碼的設(shè)計(jì)首要明確指出哪里出了問題（系統(tǒng)），其次細(xì)化到系統(tǒng)內(nèi)部具體的模塊或功能點(diǎn)。這種精細(xì)化的信息有助于快速定位和解決問題。

錯誤碼設(shè)計(jì)原則

錯誤碼的設(shè)計(jì)原則：快速追蹤溯源、簡單、描述清晰（客戶視角）。

1.快速追蹤溯源：一個好的錯誤碼應(yīng)該使開發(fā)者和運(yùn)維人員能夠迅速識別錯誤的根源（比如APP看到用戶提示錯誤信息，見名思意即可快速定位是ABCDEF哪個系統(tǒng)的什么問題），避免在不同系統(tǒng)或文檔之間來回查找。

2.簡單清晰易記：有效的錯誤碼設(shè)計(jì)需要考慮其可讀性和可比性，錯誤碼應(yīng)該有一個清晰的結(jié)構(gòu)和邏輯，方便在代碼中進(jìn)行比較和處理。

3.信息描述清晰：很多錯誤碼message描述連團(tuán)隊(duì)內(nèi)同事都看不懂，何況調(diào)用你API的開發(fā)人員呢，所以要把message描述的清晰明了。

這些設(shè)計(jì)原則有助于構(gòu)建一個高效、可靠且易于使用的錯誤碼。通過遵循這些原則，可以確保錯誤碼在實(shí)際應(yīng)用中發(fā)揮出最大的價(jià)值。

API--錯誤碼設(shè)計(jì)

在服務(wù)器接口設(shè)計(jì)中，定義接口錯誤碼是至關(guān)重要的一環(huán)。通常，服務(wù)端會設(shè)定一系列的錯誤碼，以便于指導(dǎo)接口調(diào)用者或用戶采取恰當(dāng)?shù)牟僮鳌＿@些錯誤碼可能涉及諸如參數(shù)非法、配置出錯、內(nèi)部異常等多種情況，為用戶提供明確的反饋。

1）Response響應(yīng)

在Response響應(yīng)方面，我們的 API 將返回一個結(jié)構(gòu)化的 JSON 對象，該對象包含以下三個關(guān)鍵屬性：

1.code（狀態(tài)碼）: 這是一個標(biāo)準(zhǔn)化的數(shù)字代碼，用于表明請求的處理結(jié)果。每個狀態(tài)碼都對應(yīng)一個特定的情況，使得客戶端可以快速識別請求的狀態(tài)。

2.message（狀態(tài)碼描述）: 該字段提供了一個簡短且清晰的描述，解釋了狀態(tài)碼的含義。這將幫助客戶端了解請求成功與否，如果出現(xiàn)問題，它將提供足夠的信息以指導(dǎo)進(jìn)一步的行動。

3.data（響應(yīng)數(shù)據(jù)）: 這是實(shí)際的響應(yīng)內(nèi)容，包含了請求成功時所需的數(shù)據(jù)。這個數(shù)據(jù)對象的結(jié)構(gòu)將根據(jù)具體的 API 調(diào)用而有所不同，但它總是以一種易于客戶端解析和使用的格式提供。

案例如下：

public class PromiseResponse<T> {
    /**
     * 錯誤編碼
     */
    private String code;


    /**
     * 提示信息
     */
    private String message;


    /**
     * 業(yè)務(wù)數(shù)據(jù)
     */
    private T data

{
  "code": 200,
  "message": "成功",
  "data": {
    "transferTime": "Mon Jul 29 00:01:00 CST 2024",
    "endOrderTime": "Mon Jul 29 18:00:00 CST 2024",
    "outStoreTime": "Tue Jul 30 00:00:00 CST 2024",
    "jitEndDate": "Tue Jul 30 00:00:00 CST 2024",
    "storeDeliveryHandoverTime": "Tue Jul 30 01:00:00 CST 2024",
    "deliveryTime": "Thu Aug 01 22:00:00 CST 2024",
    "routeProductionResult": {
      "ruleType": null,
      "ruleName": null
    },
    "promiseControlResult": {
      "controlResultCode": 2,
      "suspendReasonCode": 0,
      "suspendReason": null,
      "abnormalLink": 0,
      "abnormalLinkName": null,
      "abnormalReason": null
    }
  }
}

當(dāng)發(fā)生可以重試的錯誤碼時客戶端應(yīng)該以指數(shù)級增長的間隔來重試請求。除非文檔中進(jìn)行了說明。對于其他錯誤，重試操作可能并不可行，請先確保請求是冪等的并查看錯誤消息以獲得指引。

2）錯誤傳播

如果 API 服務(wù)依賴于其他服務(wù)，則不應(yīng)盲目地將這些服務(wù)中的錯誤傳播給客戶端。翻譯錯誤時，有如下建議：

• 錯誤碼轉(zhuǎn)換，比如下游返回錯誤碼A，需要轉(zhuǎn)換你對外的錯誤碼B
• 錯誤碼描述可追加下游錯誤碼描述信息，讓鏈路錯誤碼描述清晰可見
• 最終對用戶肯定是需要隱藏下游實(shí)現(xiàn)細(xì)節(jié)和機(jī)密信息，讓用戶體驗(yàn)良好的錯誤提示信息

3）?不合理案例

?不合理的API錯誤碼，不合理地方如下：

• 錯誤碼無規(guī)則：比較混亂。比如錯誤碼一會1，一會-50，-1等，沒有規(guī)則 
• 錯誤碼過細(xì)：錯誤碼定義過細(xì)過多、過度隨意，將會導(dǎo)致調(diào)用方對錯誤處理的邏輯復(fù)雜，無法很好的對錯誤碼進(jìn)行轉(zhuǎn)義或收斂。比如入?yún)㈠e誤定義了N個錯誤碼，其實(shí)定義一個入?yún)㈠e誤碼即可，錯誤碼描述可以描述具體的錯誤碼信息。
• 錯誤碼描述不清晰：一堆英文，他人看不懂

圖片

4）?行業(yè)案例

業(yè)界錯誤碼的規(guī)范很多，但是這些規(guī)范各不相同，甚至很多點(diǎn)相悖（比如Google緊密依賴于HTTP狀態(tài)碼）

4.1 京東云錯誤碼

圖片

圖片

4.2 谷歌 API 錯誤碼定義

谷歌API的錯誤碼設(shè)計(jì)緊密依賴于HTTP狀態(tài)碼，采用全數(shù)字的錯誤碼定義方式。然而，這種設(shè)計(jì)缺乏明確的錯誤分類體系，導(dǎo)致其快速識別和自解釋能力相對較弱。

圖片

錯誤碼傳遞

1）現(xiàn)在場景鏈路錯誤碼信息

現(xiàn)有應(yīng)用基本都是沒有錯誤碼傳遞功能，比如下圖 Y應(yīng)用出現(xiàn)故障，需要排查對應(yīng)的依賴服務(wù)ABC，服務(wù)B返回的是服務(wù)B自定義的錯誤碼B，但通過B是無法快速定位故障應(yīng)用是C2。服務(wù)B經(jīng)過各種排查，最終定位是服務(wù)B2的問題，服務(wù)B2通過錯誤碼B2也無法快速定位是故障應(yīng)用C2，繼續(xù)每個應(yīng)用排查，最終定位是服務(wù)C2錯誤。

圖片

2）錯誤碼傳遞（轉(zhuǎn)換）

接收下層模塊發(fā)來的錯誤碼A，錯誤碼A是當(dāng)下層模塊有故障分支時生成的；然后將自身生成的錯誤碼B和所接收到的錯誤碼A合成錯誤碼AB，將錯誤碼AB傳遞給上層模塊。

接收單元，用于接收下層模塊發(fā)來的錯誤碼A，錯誤碼A是當(dāng)下層模塊有故障分支時生成的；

合成單元，用于將自身生成的錯誤碼B和所接收到的錯誤碼A合成錯誤碼AB；

發(fā)送單元，用于將所述錯誤碼AB傳遞給上層模塊。

錯誤碼在傳遞的過程中攜帶各層模塊的故障分支信息，這樣，根據(jù)錯誤碼就可以確定錯誤碼的傳遞路徑，以便精確的定位故障錯誤原因，提高可維護(hù)性。

團(tuán)隊(duì)日常咨詢案例

?錯誤碼設(shè)計(jì)---未傳播錯誤碼 

案例：冷鏈外單無妥投時間，目前鏈路是A---->B---->C系統(tǒng)。但錯誤碼是各自封裝，沒有把根本原因傳播出去，而是各自加工，導(dǎo)致最終看到的原因跟真實(shí)的原因千差萬別。導(dǎo)致整個鏈路牽扯 業(yè)務(wù)方--->A研發(fā)---->B研發(fā)---->C研發(fā)---->C業(yè)務(wù)同事 總共5個環(huán)節(jié)，如下圖：

圖片

具體咨詢鏈路如下 ：

• 業(yè)務(wù)聯(lián)系A(chǔ)系統(tǒng)開發(fā)，告知系統(tǒng)異常提示如下
• 聯(lián)系B系統(tǒng)小蜜，小蜜根據(jù)訂單查詢調(diào)用純配接口出入?yún)⒉樵內(nèi)罩荆?/li>
• B系統(tǒng)聯(lián)系C系統(tǒng)研發(fā)，周知出入?yún)?
• C同事聯(lián)系 C業(yè)務(wù)，告知路線沒配，信息如下：{"code":0,"data":[],"message":"派送范圍維護(hù)->未查找到配置數(shù)據(jù)XXXXX","tid":44845519852540539}

現(xiàn)狀：整個鏈路牽扯ABCD系統(tǒng)研發(fā)業(yè)務(wù)，溝通成本大（技術(shù)&業(yè)務(wù)），效率低

改進(jìn)方案：?錯誤碼信息--傳播錯誤碼信息

推動錯誤碼封裝，錯誤信息傳遞功能，讓最終A系統(tǒng)用戶清晰明了根本原因（D系統(tǒng)）是什么。減少ABCD中間過程，A直接聯(lián)系D，直接可見即所得。

• 如果api在翻譯錯誤時，需要把底層根本原因返回上去，比如上面案例，把沒有妥投日期的根本原因【派送范圍維護(hù)->未查找到配置數(shù)據(jù)XXXX","tid":44845519852540539】周知 

改造后鏈路 A業(yè)務(wù)方---->C業(yè)務(wù)同事 總共2個環(huán)節(jié)（改造前5個環(huán)節(jié)），因?yàn)榻缑嫣崾惧e誤信息，所見即所得，減少了中間環(huán)節(jié)。提升了業(yè)務(wù)效率，減少了研發(fā)內(nèi)部中間環(huán)節(jié)的排查成本。

【探討】全鏈路錯誤碼系統(tǒng)設(shè)計(jì)

前面介紹了API的錯誤碼設(shè)計(jì)及錯誤碼傳遞，本章節(jié)探討全鏈路錯誤碼如何串聯(lián)起來，不一定對，只是個人的思考，并且實(shí)踐起來也是比較困難的不太現(xiàn)實(shí)

1）痛點(diǎn)：全鏈路排查問題慢

在京東復(fù)雜的系統(tǒng)架構(gòu)中，故障診斷往往像是在迷宮中尋路。想象一下，一個由多達(dá)20+個相互依賴的系統(tǒng)組成的服務(wù)鏈路，從入口到底層的第N個服務(wù)，每個系統(tǒng)都是潛在的故障點(diǎn)。當(dāng)前，一旦系統(tǒng)出現(xiàn)問題，都是上游拉群，定位問題拉下游N個系統(tǒng)，線上語音討論是哪個出現(xiàn)的問題故障導(dǎo)致的，整個流程可能需要耗費(fèi)長達(dá)1-2個小時甚至更長時間才能追蹤到問題實(shí)際出現(xiàn)在M系統(tǒng)上。這個過程不僅耗時，而且效率低下。

現(xiàn)狀故障處理流程：

圖片

現(xiàn)有系統(tǒng)交互圖如下：

圖片

在這種復(fù)雜系統(tǒng)架構(gòu)中，目前故障診斷的技術(shù)面臨多個挑戰(zhàn)和缺點(diǎn)，主要包括：

• 時間消耗長、效率低下：當(dāng)系統(tǒng)出現(xiàn)問題時，故障診斷需要逐個檢查各個系統(tǒng)，需要長時間才能定位到問題所在的系統(tǒng)，這直接影響了故障恢復(fù)時間和系統(tǒng)的整體可用性。
• 復(fù)雜性管理不足：在多個相互依賴的系統(tǒng)中，即使是小問題也可能迅速演變成復(fù)雜問題，現(xiàn)有的技術(shù)似乎沒有很好地管理這種復(fù)雜性。
• 信息孤島：系統(tǒng)間可能存在信息隔離，導(dǎo)致故障信息不能快速傳遞，增加了診斷時間。
• 依賴專業(yè)知識：可能過度依賴工程師的專業(yè)知識和經(jīng)驗(yàn)進(jìn)行故障排查，這不僅效率低，而且不利于知識傳承和團(tuán)隊(duì)協(xié)作。
• 缺乏自動化：聽起來這個過程很大程度上依賴于手動操作，缺乏自動化工具來快速識別和定位大概是哪個系統(tǒng)的問題。

API中如何設(shè)計(jì)一個號的錯誤碼，鏈路調(diào)用錯誤碼如何傳遞，線上故障如何通過錯誤碼快速定位鏈路某個系統(tǒng)或者某個功能問題點(diǎn)

2）設(shè)計(jì)思想

如下圖：如果服務(wù)C2有故障，則通過全鏈路traceId可快速查看Y的故障對應(yīng)的錯誤碼，根據(jù)錯誤碼定位是因?yàn)镃2應(yīng)用故障導(dǎo)致的。

圖片

日志錯誤碼架構(gòu)思路如下：

參考【京東基礎(chǔ)技術(shù)統(tǒng)一平臺XXX系統(tǒng)】--》【業(yè)務(wù)監(jiān)控】每個應(yīng)用無需接入錯誤碼Agent，錯誤碼Agent其實(shí)就是日志采集。跟業(yè)務(wù)監(jiān)控一樣，你只需要把你應(yīng)用的業(yè)務(wù)指標(biāo)錯誤信息打印到日志中即可，比如服務(wù)ABCDEF鏈路都打印日志，相關(guān)的應(yīng)用logbook接入TOPIC-1，則通過TOPIC-1可拿到整個鏈路traceId以及每個應(yīng)用的錯誤碼信息（如果有）。

日志格式：traceId|應(yīng)用錯誤碼|錯誤碼信息描述

1677474.49460.17235995037011944.3460091.193151.9140|WMS_10001|調(diào)用Promise（系統(tǒng)B）系統(tǒng)異常，缺少預(yù)計(jì)妥投時間

1677474.49460.17235995037011944.3460091.193151.9140|PROMIES_10002|Promise調(diào)用路由系統(tǒng)(系統(tǒng)C）異常，缺少預(yù)計(jì)妥投時間

1677474.49460.17235995037011944.3460091.193151.9140|ROUTE_20003|派送范圍維護(hù)->未查找到配置數(shù)據(jù)，請排查派送范圍維護(hù)，派送地址：四川-達(dá)州市-宣漢縣-龍泉土家族鄉(xiāng)，產(chǎn)品：生鮮特殊次晨，生鮮特惠次晨，生鮮標(biāo)快

這樣通traceId（17235995037011944.3460091.193151.9140）可拿到鏈路中的AB（B1,B2,B3)C系統(tǒng)的錯誤碼,其中B1/B2/B3等系統(tǒng)無錯誤，則可不打錯誤碼。

具體系統(tǒng)設(shè)計(jì)圖如下：

圖片

• 在應(yīng)用程序中，使用日志打印功能記錄接口對應(yīng)的錯誤碼及其詳細(xì)信息，確保每次接口調(diào)用出現(xiàn)錯誤時都能捕獲到相關(guān)數(shù)據(jù)。
• 錯誤碼Agent會從日志中收集這些錯誤碼信息，并將其發(fā)送到消息隊(duì)列中，以便后續(xù)的處理和分析。
• 消費(fèi)消息隊(duì)列中的錯誤碼信息，進(jìn)行深入的數(shù)據(jù)分析，包括但不限于錯誤碼的頻率、分布和趨勢等。
• 根據(jù)traceId，追蹤并收集整個鏈路的數(shù)據(jù)，并將其存儲到MySQL或Elasticsearch等數(shù)據(jù)庫中，以便進(jìn)行全鏈路的錯誤碼信息查詢和分析。
• 在應(yīng)用程序的界面上，用戶可以通過輸入對應(yīng)的traceId來查詢整個鏈路的錯誤碼信息，方便快速定位問題。
• 系統(tǒng)會自動對錯誤碼信息進(jìn)行實(shí)時的數(shù)據(jù)分析和趨勢預(yù)測，幫助團(tuán)隊(duì)及時發(fā)現(xiàn)和解決潛在的故障。
• 如果錯誤碼信息被識別為異?；蚋邇?yōu)先級事件，系統(tǒng)將自動觸發(fā)報(bào)警服務(wù)，通過多種方式（如咚咚、電子郵件、京Me等）通知相關(guān)干系人。對于緊急情況，系統(tǒng)還可以通過電話等方式直接聯(lián)系一線人員，確保問題得到及時處理。

3）挑戰(zhàn)性：鏈路改造范圍廣

全鏈路錯誤碼系統(tǒng)設(shè)計(jì)需要對現(xiàn)有系統(tǒng)進(jìn)行大范圍改造，確保每個系統(tǒng)都能記錄和傳遞錯誤碼。這不僅涉及大量的開發(fā)工作，還需要跨團(tuán)隊(duì)的協(xié)調(diào)和配合。此外，系統(tǒng)之間的日志格式和錯誤碼標(biāo)準(zhǔn)需要統(tǒng)一，確保數(shù)據(jù)的可追溯性和一致性。

總結(jié)

設(shè)計(jì)一個好的API錯誤碼是一個具有挑戰(zhàn)性的任務(wù)，但它對于提高系統(tǒng)的可維護(hù)性和用戶體驗(yàn)至關(guān)重要。本文拋磚引玉，希望提供的思路和實(shí)踐能夠幫助你在設(shè)計(jì)API錯誤碼時更加得心應(yīng)手。

如本文里面信息有誤請指正，如有更好的知識點(diǎn)，歡迎評論交流完善補(bǔ)充。謝謝！

參考內(nèi)容

1、京東云錯誤碼：https://docs.jdcloud.com/cn/face-compare/api/error-code

2、Google錯誤碼：https://cloud.google.com/apis/design/errors?hl=zh-cn