【項目實踐】後端介面統一規範的同時，如何優雅得擴展規範
以項目驅動學習，以實踐檢驗真知
前言
我在上一篇部落格中寫了如何通過參數校驗 + 統一響應碼 + 統一異常處理來構建一個優雅後端介面體系：
【項目實踐】SpringBoot三招組合拳，手把手教你打出優雅的後端介面。我們做到了：
- 通過Validator + 自動拋出異常來完成了方便的參數校驗
- 通過全局異常處理 + 自定義異常完成了異常操作的規範
- 通過數據統一響應完成了響應數據的規範
- 多個方面組裝非常優雅的完成了後端介面的協調，讓開發人員有更多的經歷注重業務邏輯程式碼，輕鬆構建後端介面
這樣看上去好像挺完美的，很多地方做到了統一和規範。但！事物往往是一體兩面的，統一和規範帶來的好處自然不必多說，那壞處呢？壞處就是不夠靈活。
數據統一響應
不夠靈活主要體現在哪呢，就是數據統一響應這一塊。後端響應給前端的數據一共分為三個部分：
code：響應碼，比如1000代表響應成功，1001代表響應失敗等等
msg：響應資訊，用來說明/描述響應情況
data：響應的具體數據
我們通過響應碼枚舉做到了code和msg的統一，無論怎樣我們只會響應枚舉規定好的code和msg。我天真的以為這樣就能滿足所有應用場景了，直到我碰到了一位網友的提問：
想請問下如果我檢驗的每個參數對應不同的錯誤資訊，即code，message都不同 這樣該如何處理呢？因為這些錯誤碼是有業務含義的，比如說手機號校驗的錯誤碼是V00001，身份證號錯誤碼是V00002。
這一下把我問的有點懵，當時回答道validation參數校驗失敗的話可以手動捕捉參數校驗異常對象，判斷是哪個欄位，再根據欄位手動返回錯誤程式碼。我先來演示一下我所說的這種極為麻煩的做法：
手動捕捉異常對象
因為BindingResult對象里封裝了很多資訊，我們可以拿到校驗錯誤的欄位名，拿到了欄位名後再響應對應的錯誤碼和錯誤資訊。在Controller層里對BindingResult進行了處理自然就不會被我們之前寫的全局異常處理給捕獲到，也就不會響應那統一的錯誤碼了，從而達到了每個欄位有自己的響應碼和響應資訊：
@PostMapping("/addUser")
public ResultVO<String> addUser(@RequestBody @Valid User user, BindingResult bindingResult) {
for (ObjectError error : bindingResult.getAllErrors()) {
// 拿到校驗錯誤的參數欄位
String field = bindingResult.getFieldError().getField();
// 判斷是哪個欄位發生了錯誤，然後返回數據響應體
switch (field) {
case "account":
return new ResultVO<>(100001, "帳號驗證錯誤", error.getDefaultMessage());
case "password":
return new ResultVO<>(100002, "密碼驗證錯誤", error.getDefaultMessage());
case "email":
return new ResultVO<>(100003, "郵箱驗證錯誤", error.getDefaultMessage());
}
}
// 沒有錯誤則返回則直接返回正確的資訊
return new ResultVO<>(userService.addUser(user));
}
我們故意輸錯參數，來看下效果：
嗯，是達到效果了。不過這程式碼一放出來簡直就讓人頭疼不已。繁瑣、維護性差、復用性差，這才判斷三個欄位就這樣子了，要那些特別多欄位的還不得起飛咯？
這種方式直接pass！
那我們不手動捕捉異常，我們直接捨棄validation校驗，手動校驗呢？
手動校驗
我們來試試：
@PostMapping("/addUser")
public ResultVO<String> addUser(@RequestBody User user) {
// 參數校驗
if (user.getAccount().length() < 6 || user.getAccount().length() > 11) {
return new ResultVO<>(100001, "帳號驗證錯誤", "帳號長度必須是6-11個字元");
}
if (user.getPassword().length() < 6 || user.getPassword().length() > 16) {
return new ResultVO<>(100002, "密碼驗證錯誤", "密碼長度必須是6-16個字元");
}
if (!Pattern.matches("^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$", user.getEmail())) {
return new ResultVO<>(100003, "郵箱驗證錯誤", "郵箱格式不正確");
}
// 沒有錯誤則返回則直接返回正確的資訊
return new ResultVO<>(userService.addUser(user));
}
我去，這還不如上面那種方式呢。上面那種方式至少還能享受validation校驗規則的便利性，這種方式簡直又臭又長。
那有什麼辦法既享受validation的校驗規則，又能做到為每個欄位制定響應碼呢？不賣關子了，當然是有滴嘛！
還記得我們前面所說的BindingResult可以拿到校驗錯誤的欄位名嗎？既然可以拿到欄位名，我們再進一步當然也可以拿到欄位Field對象，能夠拿到Field對象我們也能同時拿到欄位的註解嘛。對，咱們就是要用註解來優雅的實現上面的功能！
自定義註解
如果validation校驗失敗了，我們可以拿到欄位對象並能夠獲取欄位的註解資訊，那麼只要我們為每個欄位帶上註解，註解中帶上我們自定義的錯誤碼code和錯誤資訊msg，這樣就能方便的返迴響應體啦！
首先我們自定義一個註解：
/**
* @author RC
* @description 自定義參數校驗錯誤碼和錯誤資訊註解
*/
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD}) // 表明該註解只能放在類的欄位上
public @interface ExceptionCode {
// 響應碼code
int value() default 100000;
// 響應資訊msg
String message() default "參數校驗錯誤";
}
然後我們給參數的欄位上加上我們的自定義註解：
@Data
public class User {
@NotNull(message = "用戶id不能為空")
private Long id;
@NotNull(message = "用戶帳號不能為空")
@Size(min = 6, max = 11, message = "帳號長度必須是6-11個字元")
@ExceptionCode(value = 100001, message = "帳號驗證錯誤")
private String account;
@NotNull(message = "用戶密碼不能為空")
@Size(min = 6, max = 11, message = "密碼長度必須是6-16個字元")
@ExceptionCode(value = 100002, message = "密碼驗證錯誤")
private String password;
@NotNull(message = "用戶郵箱不能為空")
@Email(message = "郵箱格式不正確")
@ExceptionCode(value = 100003, message = "郵箱驗證錯誤")
private String email;
}
然後我們跑到我們的全局異常處理來進行操作，注意看程式碼注釋：
@RestControllerAdvice
public class ExceptionControllerAdvice {
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResultVO<String> MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) throws NoSuchFieldException {
// 從異常對象中拿到錯誤資訊
String defaultMessage = e.getBindingResult().getAllErrors().get(0).getDefaultMessage();
// 參數的Class對象，等下好通過欄位名稱獲取Field對象
Class<?> parameterType = e.getParameter().getParameterType();
// 拿到錯誤的欄位名稱
String fieldName = e.getBindingResult().getFieldError().getField();
Field field = parameterType.getDeclaredField(fieldName);
// 獲取Field對象上的自定義註解
ExceptionCode annotation = field.getAnnotation(ExceptionCode.class);
// 有註解的話就返回註解的響應資訊
if (annotation != null) {
return new ResultVO<>(annotation.value(),annotation.message(),defaultMessage);
}
// 沒有註解就提取錯誤提示資訊進行返回統一錯誤碼
return new ResultVO<>(ResultCode.VALIDATE_FAILED, defaultMessage);
}
}
這裡做了全局異常處理，那麼Controller層那邊就只用專心做業務邏輯就好了：
@ApiOperation("添加用戶")
@PostMapping("/addUser")
public String addUser(@RequestBody @Valid User user) {
return userService.addUser(user);
}
我們來看下效果：
可以看到，只要加了我們自定義的註解，參數校驗失敗了就會返回註解的錯誤碼code和錯誤資訊msg。這種做法相比前兩種做法帶來了以下好處：
- 方便。從之前一大堆手動判斷程式碼，到現在一個註解搞定
- 復用性強。不單單可以對一個對象有效果，對其他受校驗的對象都有效果，不用再寫多餘的程式碼
- 能夠和統一響應碼配合。前兩種方式是要麼就對一個對象所有參數用自定義的錯誤碼，要麼就所有參數用統一響應碼。這種方式如果你不想為某個欄位設置自定義響應碼，那麼不加註解自然而然就會返回統一響應碼
簡直不要太方便！這種方式就像在數據統一響應上加了一個擴展功能，既規範又靈活！
當然，我這裡只是提供了一個思路，我們還可以用自定義註解做很多事情。比如，我們可以讓註解直接加在整個類上，讓某個類都參數用一個錯誤碼等等！
繞過數據統一響應
上面演示了如何讓錯誤碼變得靈活，我們繼續進一步擴展。
全局統一處理數據響應體會讓所有數據都被ResultVO包裹起來返還給前端，這樣我們前端接到的所有響應都是固定格式的，方便的很。但是！如果我們的介面並不是給我們自己前端所用呢？我們要調用其他第三方介面並給予響應數據，別人要接受的響應可不一定按照code、msg、data來哦！所以，我們還得提供一個擴展性，就是允許繞過數據統一響應！
我想大家猜到了，我們依然要用自定義註解來完成這個功能：
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD}) // 表明該註解只能放在方法上
public @interface NotResponseBody {
}
只要加了這個註解的方法，我們就不做數據統一響應處理，返回類型是啥就是返回的啥
@GetMapping("/getUser")
@NotResponseBody
public User getUser() {
User user = new User();
user.setId(1L);
user.setAccount("12345678");
user.setPassword("12345678");
user.setEmail("[email protected]");
return user;
}
我們接下來再數據統一響應處理類里對這個註解進行判斷：
@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) || returnType.hasMethodAnnotation(NotResponseBody.class));
}
...
}
好，我們來看看效果。沒加註解前，數據是被響應體包裹了的：
方法加了註解後數據就直接返回了數據本身：
非常好，在數據統一響應上又加了一層擴展。
總結
經過一波操作後，我們從沒有規範到有規範，再從有規範到擴展規範：
沒有規範（一團糟） –> 有規範（缺乏靈活） –> 擴展規範（Nice）
寫這篇文章的起因就是我前面所說的，一個網友突然問了我那個問題，我才赫然發現項目開發中各種各樣的情況都可能會出現，沒有任何一個架構可以做到完美，與其說我們要去追求完美，倒不如說我們應該要去追求，處理需求變化紛雜的能力！
最後在這裡放上此項目的github地址，克隆到本地即可直接運行，並且我將每一次的優化記錄都分別做了程式碼提交，你可以清晰的看到項目的改進過程，如果對你有幫助請在github上點個star，我還會繼續更新更多【項目實踐】哦！
