SpringBoot 三招組合拳，手把手教你打出優雅的後端介面

前言 一個後端介面大致分為四個部分組成：介面地址（url）、介面請求方式（get、post 等）、請求資料（request）、響應資料（response）。如何構建這幾個部分每個公司要求都不同，沒有什麼 “一定是最好的” 標準，但一個優秀的後端介面和一個糟糕的後端介面對比起來差異還是蠻大的，其中最重要的關鍵點就是看是否規範！ 本文就一步一步演示如何構建起一個優秀的後端介面體系，體系構建好了自然就有了規範，同時再構建新的後端介面也會十分輕鬆。 在文章末尾貼上了專案演示的 github 地址，clone 下來即可執行，並且我將每一次的優化記錄都分別做了程式碼提交，你可以清晰的看到專案的改進過程！

所需依賴包 這裡用的是 SpringBoot 配置專案，本文講解的重點是後端介面，所以只需要匯入一個 spring-boot-starter-web 包就可以了：

org.springframework.boot spring-boot-starter-web 本文還用了 swagger 來生成 API 文件，lombok 來簡化類，不過這兩者不是必須的，可用可不用。

引數校驗 一個介面一般對引數（請求資料）都會進行安全校驗，引數校驗的重要性自然不必多說，那麼如何對引數進行校驗就有講究了。

業務層校驗 首先我們來看一下最常見的做法，就是在業務層進行引數校驗：

public String addUser(User user) { if (user == null || user.getId() == null || user.getAccount() == null || user.getPassword() == null || user.getEmail() == null) { return "物件或者物件欄位不能為空"; } if (StringUtils.isEmpty(user.getAccount()) || StringUtils.isEmpty(user.getPassword()) || StringUtils.isEmpty(user.getEmail())) { return "不能輸入空字串"; } if (user.getAccount().length() < 6 || user.getAccount().length() > 11) { return "賬號長度必須是6-11個字元"; } if (user.getPassword().length() < 6 || user.getPassword().length() > 16) { return "密碼長度必須是6-16個字元"; } if (!Pattern.matches("^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)+$", user.getEmail())) { return "郵箱格式不正確"; } // 引數校驗完畢後這裡就寫上業務邏輯 return "success"; } 這樣做當然是沒有什麼錯的，而且格式排版整齊也一目瞭然，不過這樣太繁瑣了，這還沒有進行業務操作呢光是一個引數校驗就已經這麼多行程式碼，實在不夠優雅。我們來改進一下，使用 Spring Validator 和 Hibernate Validator 這兩套 Validator 來進行方便的引數校驗！這兩套 Validator 依賴包已經包含在前面所說的 web 依賴包裡了，所以可以直接使用。

Validator + BindResult 進行校驗 Validator 可以非常方便的制定校驗規則，並自動幫你完成校驗。首先在入參裡需要校驗的欄位加上註解，每個註解對應不同的校驗規則，並可制定校驗失敗後的資訊：

@Data public class User { @NotNull(message = "使用者id不能為空") private Long id;

@NotNull(message = "使用者賬號不能為空")
@Size(min = 6, max = 11, message = "賬號長度必須是6-11個字元")
private String account;

@NotNull(message = "使用者密碼不能為空")
@Size(min = 6, max = 11, message = "密碼長度必須是6-16個字元")
private String password;

@NotNull(message = "使用者郵箱不能為空")
@Email(message = "郵箱格式不正確")
private String email;

} 校驗規則和錯誤提示資訊配置完畢後，接下來只需要在介面需要校驗的引數上加上 @Valid 註解，並新增 BindResult 引數即可方便完成驗證：

@RestController @RequestMapping("user") public class UserController { @Autowired private UserService userService;

@PostMapping("/addUser")
public String addUser(@RequestBody @Valid User user, BindingResult bindingResult) {
    // 如果有引數校驗失敗，會將錯誤資訊封裝成物件組裝在BindingResult裡
    for (ObjectError error : bindingResult.getAllErrors()) {
        return error.getDefaultMessage();
    }
    return userService.addUser(user);
}

} 這樣當請求資料傳遞到介面的時候 Validator 就自動完成校驗了，校驗的結果就會封裝到 BindingResult 中去，如果有錯誤資訊我們就直接返回給前端，業務邏輯程式碼也根本沒有執行下去。此時，業務層裡的校驗程式碼就已經不需要了：

public String addUser(User user) { // 直接編寫業務邏輯 return "success"; } 現在可以看一下引數校驗效果。我們故意給這個介面傳遞一個不符合校驗規則的引數，先傳遞一個錯誤資料給介面，故意將 password 這個欄位不滿足校驗條件：

{ "account": "12345678", "email": "123@qq.com", "id": 0, "password": "123" } 再來看一下介面的響應資料：

這樣是不是方便很多？不難看出使用 Validator 校驗有如下幾個好處：

簡化程式碼，之前業務層那麼一大段校驗程式碼都被省略掉了。 使用方便，那麼多校驗規則可以輕而易舉的實現，比如郵箱格式驗證，之前自己手寫正規表示式要寫那麼一長串，還容易出錯，用 Validator 直接一個註解搞定。（還有更多校驗規則註解，可以自行去了解哦） 減少耦合度，使用 Validator 能夠讓業務層只關注業務邏輯，從基本的引數校驗邏輯中脫離出來。 使用 Validator+ BindingResult 已經是非常方便實用的引數校驗方式了，在實際開發中也有很多專案就是這麼做的，不過這樣還是不太方便，因為你每寫一個介面都要新增一個 BindingResult 引數，然後再提取錯誤資訊返回給前端。這樣有點麻煩，並且重複程式碼很多（儘管可以將這個重複程式碼封裝成方法）。我們能否去掉 BindingResult 這一步呢？當然是可以的！

Validator + 自動丟擲異常 我們完全可以將 BindingResult 這一步給去掉：

@PostMapping("/addUser") public String addUser(@RequestBody @Valid User user) { return userService.addUser(user); } 去掉之後會發生什麼事情呢？直接來試驗一下，還是按照之前一樣故意傳遞一個不符合校驗規則的引數給介面。 此時我們觀察控制檯可以發現介面已經引發 MethodArgumentNotValidException 異常了：

其實這樣就已經達到我們想要的效果了，引數校驗不通過自然就不執行接下來的業務邏輯，去掉 BindingResult 後會自動引發異常，異常發生了自然而然就不會執行業務邏輯。也就是說，我們完全沒必要新增相關 BindingResult 相關操作嘛。不過事情還沒有完，異常是引發了，可我們並沒有編寫返回錯誤資訊的程式碼呀，那引數校驗失敗了會響應什麼資料給前端呢？ 我們來看一下剛才異常發生後介面響應的資料：

沒錯，是直接將整個錯誤物件相關資訊都響應給前端了！這樣就很難受，不過解決這個問題也很簡單，就是我們接下來要講的全域性異常處理！

全域性異常處理 引數校驗失敗會自動引發異常，我們當然不可能再去手動捕捉異常進行處理，不然還不如用之前 BindingResult 方式呢。又不想手動捕捉這個異常，又要對這個異常進行處理，那正好使用 SpringBoot 全域性異常處理來達到一勞永逸的效果！

基本使用 首先，我們需要新建一個類，在這個類上加上 @ControllerAdvice 或 @RestControllerAdvice 註解，這個類就配置成全域性處理類了。（這個根據你的 Controller 層用的是 @Controller 還是 @RestController 來決定） 然後在類中新建方法，在方法上加上 @ExceptionHandler 註解並指定你想處理的異常型別，接著在方法內編寫對該異常的操作邏輯，就完成了對該異常的全域性處理！ 我們現在就來演示一下對引數校驗失敗丟擲的 MethodArgumentNotValidException 全域性處理：

@RestControllerAdvice public class ExceptionControllerAdvice {

@ExceptionHandler(MethodArgumentNotValidException.class)
public String MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {
    // 從異常物件中拿到ObjectError物件
    ObjectError objectError = e.getBindingResult().getAllErrors().get(0);
    // 然後提取錯誤提示資訊進行返回
    return objectError.getDefaultMessage();
}

} 我們再來看下這次校驗失敗後的響應資料：

沒錯，這次返回的就是我們制定的錯誤提示資訊！我們通過全域性異常處理優雅的實現了我們想要的功能！以後我們再想寫介面引數校驗，就只需要在入參的成員變數上加上 Validator 校驗規則註解，然後在引數上加上 @Valid 註解即可完成校驗，校驗失敗會自動返回錯誤提示資訊，無需任何其他程式碼！

自定義異常 全域性處理當然不會只能處理一種異常，用途也不僅僅是對一個引數校驗方式進行優化。在實際開發中，如何對異常處理其實是一個很麻煩的事情。傳統處理異常一般有以下煩惱：

是捕獲異常 (try...catch) 還是丟擲異常 (throws) 是在 controller 層做處理還是在 service 層處理又或是在 dao 層做處理 處理異常的方式是啥也不做，還是返回特定資料，如果返回又返回什麼資料 不是所有異常我們都能預先進行捕捉，如果發生了沒有捕捉到的異常該怎麼辦？ 以上這些問題都可以用全域性異常處理來解決，全域性異常處理也叫統一異常處理，全域性和統一處理代表什麼？ 代表規範！ 規範有了，很多問題就會迎刃而解！ 全域性異常處理的基本使用方式大家都已經知道了，我們接下來更進一步的規範專案中的異常處理方式：自定義異常。 在很多情況下，我們需要手動丟擲異常，比如在業務層當有些條件並不符合業務邏輯，我這時候就可以手動丟擲異常從而觸發事務回滾。那手動丟擲異常最簡單的方式就是 throw new RuntimeException("異常資訊") 了，不過使用自定義會更好一些：

自定義異常可以攜帶更多的資訊，不像這樣只能攜帶一個字串。 專案開發中經常是很多人負責不同的模組，使用自定義異常可以統一了對外異常展示的方式。 自定義異常語義更加清晰明瞭，一看就知道是專案中手動丟擲的異常。 我們現在就來開始寫一個自定義異常：

@Getter //只要getter方法，無需setter public class APIException extends RuntimeException { private int code; private String msg;

public APIException() {
    this(1001, "介面錯誤");
}

public APIException(String msg) {
    this(1001, msg);
}

public APIException(int code, String msg) {
    super(msg);
    this.code = code;
    this.msg = msg;
}

} 在剛才的全域性異常處理類中記得新增對我們自定義異常的處理：

@ExceptionHandler(APIException.class) public String APIExceptionHandler(APIException e) { return e.getMsg(); } 這樣就對異常的處理就比較規範了，當然還可以新增對 Exception 的處理，這樣無論發生什麼異常我們都能遮蔽掉然後響應資料給前端，不過建議最後專案上線時這樣做，能夠遮蔽掉錯誤資訊暴露給前端，在開發中為了方便除錯還是不要這樣做。 現在全域性異常處理和自定義異常已經弄好了，不知道大家有沒有發現一個問題，就是當我們丟擲自定義異常的時候全域性異常處理只響應了異常中的錯誤資訊 msg 給前端，並沒有將錯誤程式碼 code 返回。這就要引申出我們接下來要講的東西了：資料統一響應

資料統一響應 現在我們規範好了引數校驗方式和異常處理方式，然而還沒有規範響應資料！比如我要獲取一個分頁資訊資料，獲取成功了呢自然就返回的資料列表，獲取失敗了後臺就會響應異常資訊，即一個字串，就是說前端開發者壓根就不知道後端響應過來的資料會是啥樣的！所以，統一響應資料是前後端規範中必須要做的！

自定義統一響應體 統一資料響應第一步肯定要做的就是我們自己自定義一個響應體類，無論後臺是執行正常還是發生異常，響應給前端的資料格式是不變的！那麼如何定義響應體呢？可以參考我們自定義異常類，也來一個響應資訊程式碼 code 和響應資訊說明 msg：

@Getter public class ResultVO { /** * 狀態碼，比如1000代表響應成功 / private int code; /* * 響應資訊，用來說明響應情況 / private String msg; /* * 響應的具體資料 */ private T data;

public ResultVO(T data) {
    this(1000, "success", data);
}

public ResultVO(int code, String msg, T data) {
    this.code = code;
    this.msg = msg;
    this.data = data;
}

} 然後我們修改一下全域性異常處理那的返回值：

@ExceptionHandler(APIException.class) public ResultVO APIExceptionHandler(APIException e) { // 注意哦，這裡返回型別是自定義響應體 return new ResultVO<>(e.getCode(), "響應失敗", e.getMsg()); }

@ExceptionHandler(MethodArgumentNotValidException.class) public ResultVO MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) { ObjectError objectError = e.getBindingResult().getAllErrors().get(0); // 注意哦，這裡返回型別是自定義響應體 return new ResultVO<>(1001, "引數校驗失敗", objectError.getDefaultMessage()); } 我們再來看一下此時如果發生異常了會響應什麼資料給前端：

OK，這個異常資訊響應就非常好了，狀態碼和響應說明還有錯誤提示資料都返給了前端，並且是所有異常都會返回相同的格式！異常這裡搞定了，別忘了我們到介面那也要修改返回型別，我們新增一個介面好來看看效果：

@GetMapping("/getUser") public ResultVO getUser() { User user = new User(); user.setId(1L); user.setAccount("12345678"); user.setPassword("12345678"); user.setEmail(" 123@qq.com");

return new ResultVO<>(user);

} 看一下如果響應正確返回的是什麼效果：

這樣無論是正確響應還是發生異常，響應資料的格式都是統一的，十分規範！

資料格式是規範了，不過響應碼 code 和響應資訊 msg 還沒有規範呀！大家發現沒有，無論是正確響應，還是異常響應，響應碼和響應資訊是想怎麼設定就怎麼設定，要是 10 個開發人員對同一個型別的響應寫 10 個不同的響應碼，那這個統一響應體的格式規範就毫無意義！所以，必須要將響應碼和響應資訊給規範起來。

響應碼列舉 要規範響應體中的響應碼和響應資訊用列舉簡直再恰當不過了，我們現在就來建立一個響應碼列舉類：

@Getter public enum ResultCode {

SUCCESS(1000, "操作成功"),

FAILED(1001, "響應失敗"),

VALIDATE_FAILED(1002, "引數校驗失敗"),

ERROR(5000, "未知錯誤");

private int code;
private String msg;

ResultCode(int code, String msg) {
    this.code = code;
    this.msg = msg;
}

} 然後修改響應體的構造方法，讓其只准接受響應碼列舉來設定響應碼和響應資訊：

public ResultVO(T data) { this(ResultCode.SUCCESS, data); }

public ResultVO(ResultCode resultCode, T data) { this.code = resultCode.getCode(); this.msg = resultCode.getMsg(); this.data = data; } 然後同時修改全域性異常處理的響應碼設定方式：

@ExceptionHandler(APIException.class) public ResultVO APIExceptionHandler(APIException e) { // 注意哦，這裡傳遞的響應碼列舉 return new ResultVO<>(ResultCode.FAILED, e.getMsg()); }

@ExceptionHandler(MethodArgumentNotValidException.class) public ResultVO MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) { ObjectError objectError = e.getBindingResult().getAllErrors().get(0); // 注意哦，這裡傳遞的響應碼列舉 return new ResultVO<>(ResultCode.VALIDATE_FAILED, objectError.getDefaultMessage()); } 這樣響應碼和響應資訊只能是列舉規定的那幾個，就真正做到了響應資料格式、響應碼和響應資訊規範化、統一化！

全域性處理響應資料 介面返回統一響應體 + 異常也返回統一響應體，其實這樣已經很好了，但還是有可以優化的地方。要知道一個專案下來定義的介面搞個幾百個太正常不過了，要是每一個介面返回資料時都要用響應體來包裝一下好像有點麻煩，有沒有辦法省去這個包裝過程呢？當然是有滴，還是要用到全域性處理。

首先，先建立一個類加上註解使其成為全域性處理類。然後繼承 ResponseBodyAdvice 介面重寫其中的方法，即可對我們的 controller 進行增強操作，具體看程式碼和註釋：

@RestControllerAdvice(basePackages = {"com.rudecrab.demo.controller"}) // 注意哦，這裡要加上需要掃描的包 public class ResponseControllerAdvice implements ResponseBodyAdvice