【項目實踐】SpringBoot三招組合拳，手把手教你打出優雅的後端接口

時間  2021-04-14
標籤 前端 java git 程序員 github web 面試 正則表達式 spring json 欄目 Spring 简体版
原文   原文鏈接

做者：RudeCrab前端

原文：juejin.im/post/6844904101940117511java

前言

一個後端接口大體分爲四個部分組成：接口地址（url）、接口請求方式（get、post等）、請求數據（request）、響應數據（response）。如何構建這幾個部分每一個公司要求都不一樣，沒有什麼「必定是最好的」標準，但一個優秀的後端接口和一個糟糕的後端接口對比起來差別仍是蠻大的，其中最重要的關鍵點就是看是否規範! 本文就一步一步演示如何構建起一個優秀的後端接口體系，體系構建好了天然就有了規範，同時再構建新的後端接口也會十分輕鬆。在文章末尾貼上了項目演示的github地址，clone下來便可運行,而且我將每一次的優化記錄都分別作了代碼提交，你能夠清晰的看到項目的改進過程！git

所需依賴包

這裏用的是SpringBoot配置項目，本文講解的重點是後端接口，因此只須要導入一個spring-boot-starter-web包就能夠了：程序員

<!--web依賴包，web應用必備-->
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
</dependency>

本文還用了swagger來生成API文檔，lombok來簡化類，不過這二者不是必須的，可用可不用。github

參數校驗

一個接口通常對參數（請求數據）都會進行安全校驗，參數校驗的重要性天然沒必要多說，那麼如何對參數進行校驗就有講究了。web

業務層校驗

首先咱們來看一下最多見的作法，就是在業務層進行參數校驗：面試

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能夠很是方便的制定校驗規則，並自動幫你完成校驗。首先在入參裏須要校驗的字段加上註解,每一個註解對應不一樣的校驗規則，並可制定校驗失敗後的信息：spring

@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參數便可方便完成驗證：json

@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校驗有以下幾個好處：

  1. 簡化代碼，以前業務層那麼一大段校驗代碼都被省略掉了。
  2. 使用方便，那麼多校驗規則能夠垂手可得的實現，好比郵箱格式驗證，以前本身手寫正則表達式要寫那麼一長串，還容易出錯，用Validator直接一個註解搞定。（還有更多校驗規則註解，能夠自行去了解哦）
  3. 減小耦合度，使用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註解便可完成校驗，校驗失敗會自動返回錯誤提示信息，無需任何其餘代碼！

自定義異常

全局處理固然不會只能處理一種異常，用途也不只僅是對一個參數校驗方式進行優化。在實際開發中，如何對異常處理實際上是一個很麻煩的事情。傳統處理異常通常有如下煩惱：

  1. 是捕獲異常( try...catch)仍是拋出異常( throws)
  2. 是在 controller層作處理仍是在 service層處理又或是在 dao層作處理
  3. 處理異常的方式是啥也不作，仍是返回特定數據，若是返回又返回什麼數據
  4. 不是全部異常咱們都能預先進行捕捉，若是發生了沒有捕捉到的異常該怎麼辦？

以上這些問題均可以用全局異常處理來解決，全局異常處理也叫統一異常處理，全局和統一處理表明什麼？表明規範！ 規範有了，不少問題就會迎刃而解！全局異常處理的基本使用方式你們都已經知道了，咱們接下來更進一步的規範項目中的異常處理方式：自定義異常。在不少狀況下，咱們須要手動拋出異常，好比在業務層當有些條件並不符合業務邏輯，我這時候就能夠手動拋出異常從而觸發事務回滾。那手動拋出異常最簡單的方式就是throw new RuntimeException("異常信息")了，不過使用自定義會更好一些：

  1. 自定義異常能夠攜帶更多的信息，不像這樣只能攜帶一個字符串。
  2. 項目開發中常常是不少人負責不一樣的模塊，使用自定義異常能夠統一了對外異常展現的方式。
  3. 自定義異常語義更加清晰明瞭，一看就知道是項目中手動拋出的異常。

咱們如今就來開始寫一個自定義異常：

@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<T> {
    /**
     * 狀態碼，好比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<String> APIExceptionHandler(APIException e) {
    // 注意哦，這裏返回類型是自定義響應體
    return new ResultVO<>(e.getCode(), "響應失敗", e.getMsg());
}

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResultVO<String> MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {
    ObjectError objectError = e.getBindingResult().getAllErrors().get(0);
    // 注意哦，這裏返回類型是自定義響應體
    return new ResultVO<>(1001, "參數校驗失敗", objectError.getDefaultMessage());
}

咱們再來看一下此時若是發生異常了會響應什麼數據給前端：OK，這個異常信息響應就很是好了，狀態碼和響應說明還有錯誤提示數據都返給了前端，而且是全部異常都會返回相同的格式！異常這裏搞定了，別忘了咱們到接口那也要修改返回類型，咱們新增一個接口好來看看效果：

@GetMapping("/getUser")
public ResultVO<User> 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<String> APIExceptionHandler(APIException e) {
    // 注意哦，這裏傳遞的響應碼枚舉
    return new ResultVO<>(ResultCode.FAILED, e.getMsg());
}

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResultVO<String> 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<Object> {
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> aClass) {
        // 若是接口返回的類型自己就是ResultVO那就沒有必要進行額外的操做，返回false
        return !returnType.getParameterType().equals(ResultVO.class);
    }

    @Override
    public Object beforeBodyWrite(Object data, MethodParameter returnType, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest request, ServerHttpResponse response) {
        // String類型不能直接包裝，因此要進行些特別的處理
        if (returnType.getGenericParameterType().equals(String.class)) {
            ObjectMapper objectMapper = new ObjectMapper();
            try {
                // 將數據包裝在ResultVO裏後，再轉換爲json字符串響應給前端
                return objectMapper.writeValueAsString(new ResultVO<>(data));
            } catch (JsonProcessingException e) {
                throw new APIException("返回String類型錯誤");
            }
        }
        // 將本來的數據包裝在ResultVO裏
        return new ResultVO<>(data);
    }
}

重寫的這兩個方法是用來在controller將數據進行返回前進行加強操做，supports方法要返回爲true纔會執行beforeBodyWrite方法，因此若是有些狀況不須要進行加強操做能夠在supports方法裏進行判斷。對返回數據進行真正的操做仍是在beforeBodyWrite方法中，咱們能夠直接在該方法裏包裝數據，這樣就不須要每一個接口都進行數據包裝了，省去了不少麻煩。

咱們能夠如今去掉接口的數據包裝來看下效果：

@GetMapping("/getUser")
public User getUser() {
    User user = new User();
    user.setId(1L);
    user.setAccount("12345678");
    user.setPassword("12345678");
    user.setEmail("123@qq.com");
    // 注意哦，這裏是直接返回的User類型，並無用ResultVO進行包裝
    return user;
}

而後咱們來看下響應數據：

成功對數據進行了包裝！

「

注意：beforeBodyWrite方法裏包裝數據沒法對String類型的數據直接進行強轉，因此要進行特殊處理，這裏不講過多的細節，有興趣能夠自行深刻了解。

」

總結

自此整個後端接口基本體系就構建完畢了

  • 經過Validator + 自動拋出異常來完成了方便的參數校驗
  • 經過全局異常處理 + 自定義異常完成了異常操做的規範
  • 經過數據統一響應完成了響應數據的規範
  • 多個方面組裝很是優雅的完成了後端接口的協調，讓開發人員有更多的經歷注重業務邏輯代碼，輕鬆構建後端接口

再次強調，項目體系該怎麼構建、後端接口該怎麼寫都沒有一個絕對統一的標準，不是說必定要按照本文的來纔是最好的，你怎樣均可以，本文每個環節你均可以按照本身的想法來進行編碼，我只是提供了一個思路！

最後在這裏放上此項目的github地址，clone到本地便可直接運行.

https://github.com/RudeCrab/rude-java/tree/master/project-practice/validation-and-exception-handler


好文章，我在看

本文分享自微信公衆號 - 程序員閃充寶（cxyscb1024）。
若有侵權，請聯繫 support@oschina.cn 刪除。
本文參與「OSC源創計劃」，歡迎正在閱讀的你也加入，一塊兒分享。

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程