摘要：本文演示如何構建起一個優秀的后端介面體系，體系構建好了自然就有了規范，同時再構建新的后端介面也會十分輕松，
一個后端介面大致分為四個部分組成：介面地址（url）、介面請求方式（get、post等）、請求資料（request）、回應資料（response），如何構建這幾個部分每個公司要求都不同，沒有什么“一定是最好的”標準，但一個優秀的后端介面和一個糟糕的后端介面對比起來差異還是蠻大的，其中最重要的關鍵點就是看是否規范!
本文就一步一步演示如何構建起一個優秀的后端介面體系，體系構建好了自然就有了規范，同時再構建新的后端介面也會十分輕松，
所需依賴包
這里用的是SpringBoot配置專案，本文講解的重點是后端介面，所以只需要匯入一個spring-boot-starter-web包就可以了：
<!--web依賴包，web應用必備-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>本文還用了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校驗有如下幾個好處：
（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注解即可完成校驗，校驗失敗會自動回傳錯誤提示資訊，無需任何其他代碼！更多的校驗思路：SpringBoot實作通用的介面引數校驗
自定義例外
全域處理當然不會只能處理一種例外，用途也不僅僅是對一個引數校驗方式進行優化，在實際開發中，如何對例外處理其實是一個很麻煩的事情，傳統處理例外一般有以下煩惱：
- 是捕獲例外(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<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());
}這樣回應碼和回應資訊只能是列舉規定的那幾個，就真正做到了回應資料格式、回應碼和回應資訊規范化、統一化！這些可以參考：Java專案構建基礎：統一結果，統一例外，統一日志
全域處理回應資料
介面回傳統一回應體 + 例外也回傳統一回應體，其實這樣已經很好了，但還是有可以優化的地方，要知道一個專案下來定義的介面搞個幾百個太正常不過了，要是每一個介面回傳資料時都要用回應體來包裝一下好像有點麻煩，有沒有辦法省去這個包裝程序呢？當然是有滴，還是要用到全域處理，
首先，先創建一個類加上注解使其成為全域處理類，然后繼承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.getGenericParameterType().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 + 自動拋出例外來完成了方便的引數校驗
- 通過全域例外處理 + 自定義例外完成了例外操作的規范
- 通過資料統一回應完成了回應資料的規范
- 多個方面組裝非常優雅的完成了后端介面的協調，讓開發人員有更多的經歷注重業務邏輯代碼，輕松構建后端介面
點擊關注，第一時間了解華為云新鮮技術~
轉載請註明出處，本文鏈接：https://www.uj5u.com/ruanti/70226.html
標籤：其他