程式碼評審的18個軍規，收藏好！

來源：撿田螺的小男孩

前言

大家好，我是田螺。

我們開發完需求，提測前，一般都需要程式碼評審。小夥伴們，你們知道程式碼評審，一般都有哪些軍規嘛？今天田螺哥給你帶來程式碼評審的18個軍規。

1. 新增必要的註釋

其實，寫程式碼的時候，沒有必要寫太多的註釋，因為好的方法名、變數名，就是最好的註釋。以下就是筆者總結的一些註釋規範：

• 所有的類都必須新增建立者和建立日期，以及簡單的註釋描述
• 方法內部的複雜業務邏輯或者演算法，需要新增清楚的註釋
• 一般情況下，註釋描述類、方法、變數的作用
• 任何需要提醒的警告或TODO，也要註釋清楚
• 如果是註釋一行程式碼的，就用//;如果註釋程式碼塊或者介面方法的，有多行/* **/
• 一塊程式碼邏輯如果你站在一個陌生人的角度去看,第一遍看不懂的話,就需要新增註釋了

以下就是一些新增註釋的demo：

/**
 * @author 田螺
 * @date 2023/04/22 5:20 PM
 * @desc 田螺的實現類，撿田螺、賣田螺 （更多幹貨，關注公眾號：撿田螺的小男孩）
 */
public class TianLuoClass {
 
    /**
     * 這是賣田螺的兩法，它將兩個田螺的價格整數相加並返回結果。
     * 
     * @param x 第一個整數
     * @param y 第二個整數
     * @return 兩個整數的和
     */
    public int sellTianLuo(int x, int y) {
        return x + y;
    }
}

2.日誌列印規範

日誌是快速定位問題的好幫手，是撕逼和甩鍋的利器！列印好日誌非常重要。如果程式碼評審的時候，這些日誌規範沒遵守，就需要修改：

• 日誌級別選擇不對。常見的日誌級別有error、warn、info、debug四種，不要反手就是info哈
• 日誌沒列印出呼叫方法的入參和響應結果，尤其是跨系統呼叫的時候。
• 業務日誌沒包含關鍵引數,如userId,bizSeq等等,不方便問題排查
• 如果日誌包含關鍵資訊，比如手機號、身份證等，需要脫敏處理
• 一些不符合預期的情況，如一些未知異常（資料庫的資料異常等），又或者不符合業務預期的特殊場景，都需要列印相關的日誌

對於日誌列印規範，我之前整理出一篇文章，大家可以看一下哈，挺有用的：

工作總結！日誌列印的15個建議

3. 命名規範

Java程式碼的命名應該清晰、簡潔和易於理解。我們程式碼評審的時候，要注意是否有命名不規範，不清晰的程式碼。下面是一些命名規範的建議：

• 類和介面應該使用首字母大寫的駝峰命名法
• 方法和變數應該使用小寫的駝峰命名法
• 常量應該使用全大寫字母和下劃線
• 開發者是不是選擇易於理解的名稱給變數、類和方法進行命名

4.引數校驗

我們程式碼評審的時候，要注意引數是否都做了校驗，如userId非空檢查、金額範圍檢查、userName長度校驗等等。一般我們在處理業務邏輯的時候，要遵循先檢查、後處理的原則。

如果你的資料庫欄位userName設定為varchar(16),對方傳了一個32位的字串過來，你不校驗引數，插入資料庫直接異常了。

很多bug都是因為沒做引數校驗造成的，這一軍規，是程式碼評審重點關注的哈：

5. 判空處理

• 獲取物件的屬性時，都要判空處理。要不然很多時候會出現空指標異常。

if(object!=null){
   String name = object.getName();
}

如果你要遍歷列表，也需要判空

  if (CollectionUtils.isNotEmpty(tianLuolist)) {
        for (TianLuo temp : tianLuolist) {
            //do something
        }
    }

6. 異常處理規範

良好的異常處理可以確保程式碼的可靠性和可維護性。因此，異常處理也是程式碼評審的一項重要規範。以下是一些異常處理的建議：

• 不要捕獲通用的Exception異常，而應該儘可能捕獲特定的異常
• 在捕獲異常時，應該記錄異常資訊以便於除錯
• 內部異常要確認最終的處理方式，避免未知異常當作失敗處理。
• 在finally塊中釋放資源，或者使用try-with-resource
• 不要使用e.printStackTrace(),而是使用log列印。
• catch了異常，要列印出具體的exception，否則無法更好定位問題
• 捕獲異常與丟擲異常必須是完全匹配，或者捕獲異常是拋異常的父類
• 捕獲到的異常，不能忽略它，要列印相對應的日誌
• 注意異常對你的程式碼層次結構的侵染（早發現早處理）
• 自定義封裝異常，不要丟棄原始異常的資訊Throwable cause
• 注意異常匹配的順序，優先捕獲具體的異常
• 對外提供APi時，要提供對應的錯誤碼
• 系統內部應該丟擲有業務含義的自定義異常，而不是直接丟擲RuntimeException，或者直接丟擲Exception\Throwable。

大家有興趣可以看下之前我的這篇文章哈：Java 異常處理的十個建議

7. 模組化，可擴充套件性

程式碼評審的時候，關注一下，程式碼編寫設計是否滿足模組話，介面是否具有可擴充套件性

比如你的需求是醬紫：是使用者新增或者修改員工時，需要刷臉。那你是反手提供一個員工管理的提交刷臉資訊介面？還是先思考：提交刷臉是不是通用流程呢？比如轉賬或者一鍵貼現需要接入刷臉的話，你是否需要重新實現一個介面呢？還是當前按業務型別劃分模組，複用這個介面就好，保留介面的可擴充套件性。

如果按模組劃分的話，未來如果其他場景比如一鍵貼現接入刷臉的話，不用再搞一套新的介面，只需要新增列舉，然後複用刷臉透過流程介面，實現一鍵貼現刷臉的差異化即可。

8. 併發控制規範

• 在使用併發集合時，應該注意它們的執行緒安全性和併發效能,如ConcurrentHashMap是線性安全的,HashMap就是非線性安全的
• 樂觀鎖,悲觀鎖防止資料庫併發.樂觀鎖一般用版本號version控制,悲觀鎖一般用select …for update
• 如果是單例項的多執行緒併發處理,一般透過Java鎖機制,比如sychronized ,reentrantlock
• 如果是同一叢集的多執行緒併發處理,可以用Redis分散式鎖或者走zookeeper
• 如果是跨叢集的多執行緒併發處理,則考慮資料庫實現的分散式鎖。
• 在使用分散式鎖的時候,要注意有哪些坑,比如redis一些經典的坑.

至於分散式鎖,大家可以看下我之前的這幾篇文章哈

• Redis分散式鎖的10個坑
• 面試必備：聊聊分散式鎖的多種實現！

9. 單元測試規範

• 測試類的命名,一般以測試的類+Test,如:CalculatorTest.
• 測試方法的命名,一般以test開頭+ 測試的方法,如testAdd.
• 單測行覆蓋率一般要求大於75%.
• 單測一般要求包含主流程用例、引數邊界值等校驗用例
• 單測一般也要求包含中介軟體訪問超時、返回空、等異常的用例,比如訪問資料庫或者Redis異常.
• 單測用例要求包含併發、防重、冪等等用例.

10. 程式碼格式規範

良好的程式碼格式，可以使程式碼更容易閱讀和理解。下面是一些常見的程式碼格式化建議：

• 縮排使用四個空格
• 程式碼塊使用花括號分隔
• 每行不超過80個字元
• 每個方法應該按照特定的順序排列，例如：類變數、例項變數、建構函式、公共方法、私有方法等。

11. 介面相容性

程式碼評審的時候,要重點關注是否考慮到了介面的相容性.因為很多bug都是因為修改了對外舊介面，但是卻不做相容導致的。關鍵這個問題多數是比較嚴重的，可能直接導致系統發版失敗的。新手程式設計師很容易犯這個錯誤哦~

所以，如果你的需求是在原來介面上修改，尤其這個介面是對外提供服務的話，一定要考慮介面相容。舉個例子吧，比如dubbo介面，原本是隻接收A，B引數，現在你加了一個引數C，就可以考慮這樣處理：

//老介面
void oldService(A,B){
  //相容新介面，傳個null代替C
  newService(A,B,null);
}

//新介面，暫時不能刪掉老介面，需要做相容。
void newService(A,B,C){
  ...
}

12. 程式邏輯是否清晰,主次是否夠分明

程式碼評審的時候，要關注程式邏輯是否清晰。比如，你的一個註冊介面，有引數校驗、判斷使用者是否已經註冊、插入使用者記錄、傳送註冊成功通知等功能。如果你把所有所有功能程式碼塞到一個方法裡面，程式邏輯就不清晰，主次不夠分明，反例如下:

 public Response registerUser(String userName, String password, String email) {

        if (userName == null || StringUtils.isEmpty(userName)) {
          log.info("使用者名稱不能為空！");
            throw new BizException();
        }

        if (password == null || password.length() < 6) {
            log.info("密碼長度不能少於6位！");
            throw new BizException();
        }

        if (email == null || StringUtils.isEmpty(email) || !email.contains("@")) {
            log.info("郵箱格式不正確！");
            throw new BizException();
        }

        Response response = new Response();
        UserInfo userInfo = userService.queryUserInfoByUsername();
        if (Objects.nonNull(userInfo)) {
            response.setCode(0);
            response.setMsg("註冊成功");
            return response;
        }


        UserInfo addUserInfo = new UserInfo();
        addUserInfo.setUserName(userName);
        addUserInfo.setPassword(password);
        addUserInfo.setEmail(email);
        userService.addUserInfo(addUserInfo);

        MessageDo messageDo = new MessageDo();
        messageDo.setUserName(userName);
        messageDo.setEmail(email);
        messageDo.setContent("註冊成功");
        messageService.sendMsg(messageDo);

        response.setCode(0);
        response.setMsg("註冊成功");
        return response;
    }

其實，以上這塊程式碼，主次不夠分明的點:引數校驗就佔registerUser方法很大一部分。正例可以劃分主次，抽一下小函式，如下：

    public Response registerUser(String userName, String password, String email) {

        //檢查引數
        checkRegisterParam(userName, password, email);
        //檢查使用者是否已經存在
        if (checkUserInfoExist(userName)) {
            Response response = new Response();
            response.setCode(0);
            response.setMsg("註冊成功");
            return response;
        }

        //插入使用者
        addUser(userName, password, email);
        sendMsgOfRegister(userName, email);

        //構造註冊成功報文
        Response response = new Response();
        response.setCode(0);
        response.setMsg("註冊成功");
        return response;
    }

    private void sendMsgOfRegister(String userName, String email) {
        MessageDo messageDo = new MessageDo();
        messageDo.setUserName(userName);
        messageDo.setEmail(email);
        messageDo.setContent("註冊成功");
        messageService.sendMsg(messageDo);
    }

    private void addUser(String userName, String password, String email) {
        UserInfo addUserInfo = new UserInfo();
        addUserInfo.setUserName(userName);
        addUserInfo.setPassword(password);
        addUserInfo.setEmail(email);
        userService.addUserInfo(addUserInfo);
    }

    private boolean checkUserInfoExist(String userName) {
        UserInfo userInfo = userService.queryUserInfoByUsername();
        if (Objects.nonNull(userInfo)) {
            return true;
        }
        return false;
    }

    private void checkRegisterParam(String userName, String password, String email) {
        if (userName == null || StringUtils.isEmpty(userName)) {
            log.info("使用者名稱不能為空！");
            throw new BizException();
        }

        if (password == null || password.length() < 6) {
            log.info("密碼長度不能少於6位！");
            throw new BizException();
        }

        if (email == null || StringUtils.isEmpty(email) || !email.contains("@")) {
            log.info("郵箱格式不正確！");
            throw new BizException();
        } 
    }

13. 安全規範

程式碼評審，也非常有必要評審程式碼是否存在安全性問題。比如：

• 輸入校驗：應該始終對任何來自外部的輸入資料進行校驗，以確保它們符合預期並且不會對系統造成傷害。校驗應該包括檢查資料的型別、大小和格式。
• 防範SQL隱碼攻擊:在使用SQL查詢時，應該始終使用引數化查詢或預處理語句，以防止SQL隱碼攻擊。
• 防範跨站指令碼攻擊（XSS）: 在Web應用程式中，應該始終對輸入的HTML、JavaScript和CSS進行校驗，並轉義特殊字元，以防止XSS攻擊。
• 避免敏感資訊洩露: 敏感資訊（如密碼、金鑰、會話ID等）應該在傳輸和儲存時進行加密，以防止被未經授權的人訪問。同時，應該避免在日誌、除錯資訊或錯誤訊息中洩露敏感資訊。
• 防範跨站請求偽造（CSRF）: 應該為所有敏感操作（如更改密碼、刪除資料等）新增CSRF令牌，以防止未經授權的人員執行這些操作。
• 防範安全漏洞: 應該使用安全性高的演算法和協議（如HTTPS、TLS）來保護敏感資料的傳輸和儲存，並定期對系統進行漏洞掃描和安全性審計。

其實我以前寫過一篇文章，保證資料安全的10種方案，大家可以看看哈：保證介面資料安全的10種方案

14. 事務控制規範

• 一般推薦使用程式設計式事務，而不是一個註解 @Transactional的宣告式事務。因為 @Transactional有很多場景，可能導致事務不生效。 大家可以看下我的這篇文章哈：美團二面:spring事務不生效的15種場景
• 事務範圍要明確，資料庫操作必須在事務作用範圍內，如果是非資料庫操作，儘量不要包含在事務內。
• 不要在事務內進行遠端呼叫（可能導致資料不一致，比如本地成功了，但是遠端方法失敗了，這時候需要用分散式事務解決方案）
• 事務中避免處理太多資料，一些查詢相關的操作，儘量放到事務之外（避免大事務問題）

15. 冪等處理規範

什麼是冪等？

電腦科學中，冪等表示一次和多次請求某一個資源應該具有同樣的副作用，或者說，多次請求所產生的影響與一次請求執行的影響效果相同。

程式碼評審的時候，要關注介面是否考慮冪等。比如開戶介面，多次請求過來的時候，需要先查一下該客戶是否已經開過戶，如果已經開戶成功，直接返回開戶成功的報文。如果還沒開戶，就先開戶，再返回開戶成功的報文。這就是冪等處理。

一般情況有這幾種冪等處理方案：

• select+insert+主鍵/唯一索引衝突
• 直接insert + 主鍵/唯一索引衝突
• 狀態機冪等
• 抽取防重表
• token令牌
• 悲觀鎖
• 樂觀鎖
• 分散式鎖

冪等要求有個唯一標記，比如資料庫防重表的一個業務唯一鍵。同時強調多次請求和一次請求所產生影響是一樣的。

大家如果對介面冪等有興趣的話，可以看下我之前的這篇文章：聊聊冪等設計

16. 中介軟體注意事項 （資料庫，redis）

程式碼評審的時候，如果用資料庫、Redis、RocketMq等的中介軟體時，我們需要關注這些中介軟體的一些注意事項哈。

比如資料庫：

• 關注資料庫連線池引數設定、超時引數設定是否合理
• 避免迴圈呼叫資料庫操作
• 如果不分頁，查詢SQL時，如果條數不明確，是否加了limit限制限制
• 資料庫的返回是否判空處理
• 資料庫慢SQL是否有監控
• 表結構更新是否做相容，存量表資料是否涉及相容問題考慮
• 索引新增是否合理
• 是否連表過多等等

比如Redis:

• Redis的key使用是否規範
• Redis 異常捕獲以及處理邏輯是否合理
• Redis連線池、超時引數設定是否合理
• Redis 是否使用了有坑的那些命令，如hgetall、smember
• 是否可能會存在快取穿透、快取雪奔、快取擊穿等問題。

之前我寫過一篇文章，介紹Redis使用注意點的，大家可以看一下哈:使用Redis，你必須知道的21個注意要點

17. 注意程式碼壞味道問題

理解幾個常見的程式碼壞味道，大家程式碼評審的時候，需要關注一些哈：

• 大量重複程式碼（抽公用方法，設計模式）
• 方法引數過多（可封裝成一個DTO物件）
• 方法過長（抽小函式）
• 判斷條件太多（最佳化if...else）
• 不處理沒用的程式碼（沒用的import）
• 避免過度設計

18. 遠端呼叫

遠端呼叫是程式碼評審重點關注的一欄，比如：

• 不要把超時當作失敗處理: 遠端呼叫可能會失敗，比如網路中斷、超時等等。開發者需要注意遠端呼叫返回的錯誤碼，除非是明確的失敗，如果僅僅是超時等問題，不能當作失敗處理！而是應該發起查詢，確認是否成功，再做處理。
• 異常處理：遠端呼叫可能會丟擲異常，例如由於服務端錯誤或請求格式不正確等。因此，開發人員需要確保能夠捕獲和處理這些異常，以避免系統崩潰或資料丟失。
• 網路安全：由於遠端呼叫涉及網路通訊，因此開發人員需要考慮網路安全的問題，例如資料加密、認證、訪問控制等。儘可能使用安全的協議，例如HTTPS 或 SSL/TLS。
• 服務質量：遠端呼叫可能會影響系統的效能和可用性。因此，開發人員需要確保服務的質量，例如避免過度使用遠端呼叫、最佳化資料傳輸、實現負載均衡等。
• 版本相容：由於遠端呼叫涉及不同的程式或計算機之間的通訊，因此開發人員需要注意服務端和客戶端之間的版本相容性。儘可能使用相同的介面和資料格式，避免出現不相容的情況。
• 儘量避免for迴圈遠端呼叫: 儘量避免for迴圈遠端呼叫，而應該考慮實現了批次功能的介面。