SpringBoot項目中Controller層代碼編寫規(guī)范整理方式

更新時間：2026年01月20日 09:54:37 作者：碼覺客

文章主要討論了Controller層代碼規(guī)范,包括返回統(tǒng)一的ResultBean/PageResultBean格式、避免復(fù)雜的輸入?yún)?shù)、返回必要的數(shù)據(jù)等,這些規(guī)范有助于提高代碼的可讀性、可維護性和可測試性

Controller層代碼規(guī)范

主要的內(nèi)容是就是接口定義里面的內(nèi)容，你只要遵循里面的規(guī)范，controller就問題不大，除了這些，還有另外的幾點：

所有函數(shù)返回統(tǒng)一的ResultBean/PageResultBean格式;
沒有統(tǒng)一格式，AOP無法玩.
ResultBean/PageResultBean是controller專用的，不允許往后傳
Controller做參數(shù)格式的轉(zhuǎn)換，不允許把json，map這類對象傳到services去，也不允許services返回json、map。

SpringMVC接口定義要注意以下常見的幾種問題

1. 返回格式不統(tǒng)一

同一個接口，有時候返回數(shù)組，有時候返回單個；成功的時候返回對象，失敗的時候返回錯誤信息字符串。工作中有個系統(tǒng)集成就是這樣定義的接口，真是辣眼睛。

這個對應(yīng)代碼上，返回的類型是map，json，object，都是不應(yīng)該的。實際工作中，我們會定義一個統(tǒng)一的格式，就是ResultBean，分頁的有另外一個PageResultBean

錯誤范例：

    //返回map可讀性不好，盡量不要　
    @PostMapping("/delete") 
    public Map<String, Object> delete(long id, String lang) { } 
    // 成功返回boolean，失敗返回string，大忌 
    @PostMapping("/delete") 
    public Objectdelete(long id, String lang) { 
        try { 
            boolean result = configService.delete(id, local); return result; 
        } catch (Exception e) {
            log.error(e); return e.toString(); 
        } 
    }

2. 沒有考慮失敗情況

一開始只考慮成功場景，等后面測試發(fā)現(xiàn)有錯誤情況，怎么辦，改接口唄，前后臺都改，勞民傷財無用功。

錯誤范例：

//不返回任何數(shù)據(jù)，沒有考慮失敗場景，容易返工　
＠PostMapping("/update") public void update(long id, xxx) { }

3. 出現(xiàn)和業(yè)務(wù)無關(guān)的輸入?yún)?shù)

如lang語言，當(dāng)前用戶信息都不應(yīng)該出現(xiàn)參數(shù)里面，應(yīng)該從當(dāng)前會話里面獲取。后面講ThreadLocal會說到怎么樣去掉。除了代碼可讀性不好問題外，尤其是參數(shù)出現(xiàn)當(dāng)前用戶信息的，這是個嚴(yán)重問題。

錯誤范例：

// （當(dāng)前用戶刪除數(shù)據(jù)）參數(shù)出現(xiàn)lang和userid，尤其是userid，大忌　
＠PostMapping("/delete") 
public Map<String, Object> delete(long id,String lang, String userId) { }

4. 出現(xiàn)復(fù)雜的輸入?yún)?shù)

一般情況下，不允許出現(xiàn)例如json字符串這樣的參數(shù)，這種參數(shù)可讀性極差。應(yīng)該定義對應(yīng)的bean。

錯誤范例：

// 參數(shù)出現(xiàn)json格式，可讀性不好，代碼也難看　
＠PostMapping("/update") public Map<String, Object> update(long id, String jsonStr) { }

5. 沒有返回應(yīng)該返回的數(shù)據(jù)

例如，新增接口一般情況下應(yīng)該返回新對象的id標(biāo)識，這需要編程經(jīng)驗。新手定義的時候因為前臺沒有用就不返回數(shù)據(jù)或者只返回true，這都是不恰當(dāng)?shù)摹e人要不要是別人的事情，你該返回的還是應(yīng)該返回。

錯誤范例：

// 約定俗成，新建應(yīng)該返回新對象的信息，只返回boolean容易導(dǎo)致返工　
＠PostMapping("/add") 
public boolean add(xxx) { //xxx return configService.add(); }

很多人看了我的這篇文章程序員你為什么這么累？都覺得里面的技術(shù)也很簡單，沒有什么特別的地方，但是，實現(xiàn)這個代碼框架之前，就是要你的接口的統(tǒng)一的格式ResultBean，aop才好做。有些人誤解了，我那篇文章說的都不是技術(shù)，重點說的是編碼習(xí)慣工作方式，如果你重點還是放在什么技術(shù)上，那我也幫不了你了。同樣，如果我后面的關(guān)于習(xí)慣和規(guī)范的帖子，你重點還是放在技術(shù)上的話，那是丟了西瓜撿芝麻，有很多貼還是沒有任何技術(shù)點呢。

附上ResultBean，沒有任何技術(shù)含量：

/**
 * Controller統(tǒng)一返回對象，響應(yīng)信息主體
 */
@Getter
@ApiModel(value = "響應(yīng)信息主體")
public class R<T> implements Serializable {

    private static final long serialVersionUID = 1L;
    /**
     * 狀態(tài)碼：1成功，其他均為失敗【詳見錯誤狀態(tài)碼表】
     */
    @ApiModelProperty(value = "狀態(tài)碼")
    private int code;
    /**
     * 成功為success，其他為失敗原因
     */
    @ApiModelProperty(value = "消息")
    private Object message = "success";
    /**
     * 數(shù)據(jù)結(jié)果集
     */
    @ApiModelProperty(value = "數(shù)據(jù)結(jié)果集")
    private T data;
    /**
     * 當(dāng)前時間
     */
    @ApiModelProperty(value = "時間戳")
    private final long time = System.currentTimeMillis();

    public R<T> setMessage(Object message) {
        this.message = message;
        return this;
    }

    public R<T> setMessage(String format, Object... args) {
        this.message = new Formatter().format(format, args).toString();
        return this;
    }

    public R() {
    }

    /**
     * 使用枚舉類中模版消息
     *
     * @param resultConstant ResultConstant
     * @param data           數(shù)據(jù)結(jié)果集
     */
    private R(ResultConstant resultConstant, T data) {
        this.code = resultConstant.getCode();
        this.message = resultConstant.getMessage();
        this.data = data;
    }

    public static <T> R<T> ok() {
        return restResult(ResultConstant.SUCCESS, null, null);
    }

    public static <T> R<T> ok(T data) {
        return restResult(ResultConstant.SUCCESS, null, data);
    }

    public static <T> R<T> ok(T data, Object message) {
        return restResult(ResultConstant.SUCCESS, message, data);
    }

    public static <T> R<T> failed(ResultConstant resultConstant) {
        return restResult(resultConstant, null, null);
    }

    public static <T> R<T> failed(ResultConstant resultConstant, Object message) {
        return restResult(resultConstant, message, null);
    }

    public static <T> R<T> failed(ResultConstant resultConstant, Object message, T data) {
        return restResult(resultConstant, message, data);
    }

    private static <T> R<T> restResult(ResultConstant resultConstant, Object message, T data) {
        R<T> apiResult = new R<>(resultConstant, data);
        if (null != message) {
            apiResult.setMessage(message);
        }
        return apiResult;
    }
}

統(tǒng)一的接口規(guī)范，能幫忙規(guī)避很多無用的返工修改和可能出現(xiàn)的問題。能使代碼可讀性更加好，利于進行aop和自動化測試這些額外工作。