💁 作者：小瓦匠
💖 歡迎關注我的個人公眾號：小瓦匠學編程。微信號：xiaowajiangxbc

---

錯誤碼的制定原則：快速溯源、溝通標準化。 – 阿里巴巴《Java 開發手冊》

前言

在項目開發中，你有沒有吃過錯誤碼定義混亂的虧，比如：錯誤碼定義無標準，導致無序擴張；錯誤碼語義表述不清晰；錯誤定位不精準等問題。

在團隊開發中，如果能夠制定一套合理科學的錯誤碼規約，就可以有效地避免這些問題，從而降低溝通成本以及程序的維護成本。

需求說明

設計錯誤碼規約前，首先要弄清我們的需求：

• 讓客戶端能夠感知到 HTTP 請求是否成功，以便客戶端決定下一步該如何處理。
• 錯誤返回時需要攜帶錯誤碼和出錯信息，可以讓開發者通過錯誤碼快速定位問題原因。

錯誤碼設計建議

錯誤碼主要是為了體現業務系統的報錯位置及原因，因此在設計時需要給它賦予一定的業務屬性。

誰的錯？錯在哪？

程序開發人員拿到錯誤碼后，必須能夠快速知曉錯誤來源，判斷是誰的問題。這也就要求我們設計的錯誤碼首先要具有一定的識別度，方便記憶和對比，并且要有利于團隊快速對錯誤原因達到一致認知。

內容格式統一

錯誤碼應該是統一長度，且內容格式也應該固定的，而不應該是隨機編碼產生的。其內容可以是一個整數，也可以是一個字符串，但它必須是錯誤的唯一標識。
通過研究對比各個平臺的錯誤碼，我總結出了一個比較實用的錯誤碼設計方案：使用字符數字組合表示，一共有4段組成，不同段表示不同含義。

合理的內容格式，更便于錯誤碼的管理和使用，一方面我們可以根據業務需求有規則的自行擴展；另一方面通過錯誤碼能夠精準地定位到具體是哪里出現的什么錯誤。

錯誤語義信息

錯誤碼之外的業務獨特信息應由 message 來承載，而不是讓錯誤碼本身涵蓋過多的具體業務屬性。通常在請求出現錯誤時，我們需要返回的錯誤描述一般包括：錯誤碼，錯誤說明以及參考文檔（可選）
需要注意的是，錯誤說明是展示給用戶的，最好直接告訴用戶“該怎么做”而不是“哪里錯了”，并且錯誤說明中不應該包含敏感信息（例如：堆棧信息）。但是為了方便問題排查，我們可以在系統內部日志中打印詳細的錯誤堆棧信息。

合理使用 HTTP 狀態碼

當請求出錯時，應該合理的返回 HTTP 狀態碼，以便讓客戶端感知到 HTTP 是否請求成功。為了更清晰的表述和區分狀態碼的含義，我們將 HTTP 狀態碼分成如下5類：

常用 HTTP 狀態碼

HTTP 狀態碼有很多，但是在錯誤碼設計時，我們只需要重點關注下面這些狀態碼：

• 200 - 表示請求成功執行
• 400 - 表示客戶端出問題
• 401 - 表示認證失敗
• 403 - 表示授權失敗
• 404 - 表示資源找不到
• 405 - 客戶端請求中的方法被禁止
• 500 - 表示服務端出問題
  在項目開發中，我們需要根據實際情況，靈活控制狀態碼的使用，讓客戶端的處理更容易。
  綜上所述，一個合理的錯誤返回應該包含 HTTP 狀態碼和錯誤碼，并且錯誤碼需要對外暴露錯誤說明，最好還要支持返回參考文檔。例如：

HTTP/1.1 405 Content-Type: application/json Transfer-Encoding: chunked Date: Thu, 28 Apr 2022 09:55:54 GMT Keep-Alive: timeout=60 Connection: keep-alive{"code":"U00N03", "msg":"HTTP請求方式不受支持"}

錯誤碼的具體實現

在系統開發中，推薦使用枚舉類，來存放所有錯誤碼、錯誤說明等信息。比如以系統公共錯誤碼為例：

// 在下面的代碼中只給出了部分有代表性的錯誤碼 @Getter @AllArgsConstructor public enum CommonErrorEnum implements IResponseEnum {/*** 成功*/SUCCESS("000000", 200, "SUCCESS"),/*** 參數校驗(Valid)異常*/PARAM_VALID_ERROR("U00P01", 400, "參數校驗異常"),/*** Token已過期*/TOKEN_EXPIRED("U00A02", 401, "Token已過期"),/*** 未授權，不能訪問*/AUTH_INVALID("U00A05", 403, "未授權，不能訪問"),/*** 服務器繁忙，請稍后重試*/SERVER_BUSY("U00S00", 500,"服務器繁忙"),/*** 未知異常，無法識別的異常*/SERVER_ERROR("U00O99", 500, "未知異常"),/*** Servlet請求類異常（部分）*/NoHandlerFoundException("U00N02", 404, "資源找不到"),HttpRequestMethodNotSupportedException("U00N03", 405, "HTTP請求方式不受支持"),HttpMediaTypeNotSupportedException("U00N05", 415, "HTTP請求頭的 Content-Type 不受支持"),;/*** 返回碼*/private String code;/*** 狀態碼*/private Integer http;/*** 返回消息*/private String message; // /** // * 參考文檔 （可選） // */ // private String reference; }

總結

總的來說，制定一套錯誤碼規約還是相對容易的，難的是在長期的實踐中如何管理并正確使用錯誤碼，保證不被濫用，其復雜程度跟項目規模相匹配。

所以我建議在規約設計時，應該以服務業務為導向，避免過度設計，保持簡潔；在管理使用時，應該以先到先得的原則統一審批生效，生效后永久固定。

以上就是我對于錯誤碼規約制定一些想法，規則的制定是靈活的，可變通的，同樣也沒有絕對的好與壞，只要可以滿足你的業務需求就是好的，優秀的。

本人能力有限，各位勉強一觀，若能拋磚引玉，不失為一件幸事。

---

📌 學習 積累 沉淀 分享
💖 歡迎關注我的個人公眾號：小瓦匠學編程！ 微信號：xiaowajiangxbc
🔎 掃描二維碼或微信搜索 “小瓦匠學編程” 即可關注。

（本文完）

總結

以上是生活随笔為你收集整理的错误码应该如何设计？的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。