AgileBoot 專案內統一的錯誤碼設計分析

2022-10-22 14:00:18

引言

本篇文章主要探討關於統一錯誤碼的設計，並提供筆者的實現

歡迎大家討論，指正。

該錯誤碼的設計在倉庫：

github:github.com/valarchie/A…

gitee:gitee.com/valarchie/A…

統一的錯誤碼管理的優點

統一的錯誤碼描述，如果沒有統一的錯誤碼的話，錯誤描述散落在專案內的不同地方，同一個錯誤碼卻產生不同的錯誤描述，會導致歧義。
錯誤碼的層級，在與使用者端的互動過程中，我們可能需要根據錯誤的層級，來做不同的顯示。例如系統內部的錯誤，我們產生紅色的警告框。業務上操作型別的錯誤（例如使用者名稱不能超過64位元），我們則以正常的黃色提示框來提醒使用者。
i18n的處理。統一的錯誤碼管理，才使得國際化更好實現。我們可以給每一種錯誤碼定義唯一的key，來找到對應不同語言的錯誤描述。
集中的錯誤碼管理便於形成檔案供呼叫者參考。例如我們提供介面給其他團隊呼叫，可以提供給他們詳細的錯誤碼列表。

無錯誤碼設計的缺陷

Ruoyi專案

錯誤描述散落在專案的各個地方，一旦有改變錯誤描述的需求，要滿專案去尋找關聯的錯誤描述，然後逐一修改。這種情形很容易造成疏漏。
如果需要翻譯的話，這種隨意的字串形式也很難去做國際化翻譯。
沒有準確的錯誤碼，在一些情形下，呼叫方需要根據你返回的錯誤碼進行不同的處理。如果沒有準確的錯誤碼，僅憑錯誤描述，比較難以實現。

錯誤碼的層級

錯誤碼的層級有助於使用者端對於不同級別的錯誤進行處理。比如有的錯誤進行隱藏，有的錯誤直接暴露給使用者。這邊我規劃了四層錯誤碼。錯誤碼集合

1~9999 為保留錯誤碼或者常用錯誤碼
10000~19999 為內部錯誤碼
20000~29999 使用者端錯誤碼（使用者端異常呼叫之類的錯誤）
30000~39999 為第三方錯誤碼（程式碼正常，但是第三方異常）
40000~49999 為業務邏輯錯誤碼（無異常，程式碼正常流轉，並返回提示給使用者）

錯誤碼的模組

為了更好的分門別類，筆者給錯誤碼設定了模組，便於使用者端的特殊處理。例如使用者端可以專門給某一個模組的錯誤進行一個統一的處理。模組對應的數位在千位和百位。例如1XX01，XX代表了模組的意義。

/**
 * 系統內的模組
 */
public enum Module {
    /**
     * 普通模組
     */
    COMMON(0),
    /**
     * 許可權模組
     */
    PERMISSION(1),
    /**
     * 登入模組
     */
    LOGIN(2),
    /**
     * 資料庫模組
     */
    DB(3),
    /**
     * 上傳
     */
    UPLOAD(4),
    /**
     * 使用者
     */
    USER(5),
    /**
     * 設定
     */
    CONFIG(6),
    /**
     * 職位
     */
    POST(7),
    ;
    private final int code;
    Module(int code) { this.code = code * 100; }
    public int code() {return code; }
}

錯誤碼程式碼例子

/**
     * 10000~19999是內部錯誤碼  例如 框架有問題之類的
     */
    public enum Internal implements ErrorCodeInterface {
        /**
         * 內部錯誤碼
         */
        INVALID_PARAMETER(Module.COMMON, 1, "引數異常"),
        UNKNOWN_ERROR(Module.COMMON, 2, "未知異常, 請檢視系統紀錄檔"),
        GET_ENUM_FAILED(Module.COMMON, 3, "獲取列舉型別失敗, 列舉類: {}"),
        GET_CACHE_FAILED(Module.COMMON, 4, "獲取快取失敗"),
        LOGIN_CAPTCHA_GENERATE_FAIL(Module.LOGIN, 1, "驗證碼生成失敗"),
        INVALID_TOKEN(Module.PERMISSION, 1, "token異常"),
        DB_INTERNAL_ERROR(Module.DB, 1, "資料庫異常: {}"),
        ;
        private final int code;
        private final String msg;
        private static final int BASE_CODE = 10000;
        Internal(Module module, int code, String msg) {
            this.code = BASE_CODE + module.code() + code;
            this.msg = msg;
        }
        @Override
        public int code() {
            return this.code;
        }
        @Override
        public String message() {
            return this.msg;
        }
    }

錯誤碼的使用

為了便於錯誤碼在編寫程式碼時方便使用，我建立了ErrorCode這個類，並將四個層級的錯誤類一併放進這個類當中。

程式碼中的例子

 if (roleService.checkRoleNameUnique(getRoleId(), getRoleName())) {
            throw new ApiException(ErrorCode.Business.ROLE_NAME_IS_NOT_UNIQUE, getRoleName());
 }