建站
咨詢
售后
建站咨詢
新聞中心
背景
越來越多的項目開始基于前后端分離的模式進行開發(fā)，這對后端接口的報文格式便有了一定的要求。通常，我們會采用JSON格式作為前后端交換數(shù)據(jù)格式，從而減少溝通成本等。
網站前端頁面設計會用DIV+CSS架構，布局出來的網站外觀簡潔大氣。HTML靜態(tài)，H5場景定制+CSS3網站，自適應電腦、手機、平板，符合用戶體驗的習慣，更容易與用戶產生互動。專業(yè)網絡公司的服務理念是“高性價比建站，讓企業(yè)網站具備營銷價值，促進長期合作共贏模式”。
這篇文章，就帶大家了解一下基于SpringBoot框架來封裝返回報文以及統(tǒng)一異常處理。
報文基本格式
一般報文格式通常會包含狀態(tài)碼、狀態(tài)描述（或錯誤提示信息）、業(yè)務數(shù)據(jù)等信息。在此基礎上，不同的架構師、項目搭建者可能會有所調整。但從整體上來說，基本上都是大同小異。
在SpringBoot項目中，通常接口返回的報文中至少包含三個屬性：
- code：請求接口的返回碼，成功或者異常等返回編碼，例如定義請求成功。
- message：請求接口的描述，也就是對返回編碼的描述。
- data：請求接口成功，返回的業(yè)務數(shù)據(jù)。
示例報文如下：
{
"code":200,
"message":"SUCCESS",
"data":{
"info":"測試成功"
}
}在上述報文格式中，不同的設計者是會有一些分歧的，特別是code值的定義。如果完全基于RESTful API設計的話，code字段可能就不需要存在了，而是通過HTTP協(xié)議中提供的GET、POST、PUT、DELETE操作等來完成資源的訪問。
但在實踐中，不論是出于目前國內大多數(shù)程序員的習慣，還是受限于HTTP協(xié)議提供的操作方法的局限性，很少完全遵照RESTful API方式進行設計。通常都是通過自定義Code值的形式來賦予它業(yè)務意義或業(yè)務錯誤編碼。
雖然可以不用完全遵守RESTful API風格來定義Code，在Code值的自定義中，也存在兩種形式：遵循HTTP狀態(tài)碼和自主定義。
像上面的示例，用200表示返回成功，這就是遵循HTTP響應狀態(tài)碼的形式來返回，比如還有其他的400、401、404、500等。當然，還有完全自主定義的，比如用0表示成功，1表示失敗，然后再跟進通用編碼、業(yè)務分類編碼等進行定義。
在此，筆者暫不評論每種形式的好壞，只列舉了常規(guī)的幾種形式，大家了解對應的情況，做到心中有數(shù)，有所選擇即可。
響應參數(shù)封裝實踐
創(chuàng)建一個SpringBoot項目，并引入Lombok依賴（精簡代碼），對應的核心依賴如下：
org.springframework.boot
spring-boot-starter-web
org.projectlombok
lombok
創(chuàng)建枚舉類，用于定義返回的錯誤碼：
@Getter
@AllArgsConstructor
public enum ResponseCodeEnums {
SUCCESS(200, "success"),
FAIL(500, "failed"),
HTTP_STATUS_200(200, "ok"),
HTTP_STATUS_400(400, "request error"),
HTTP_STATUS_401(401, "no authentication"),
HTTP_STATUS_403(403, "no authorities"),
HTTP_STATUS_500(500, "server error");
private final int code;
private final String message;
}
這里只定義了一些通用的、基于的HTTP響應狀態(tài)碼，業(yè)務相關的編碼可根據(jù)業(yè)務需求進行定義。
定義統(tǒng)一返回結果實體類：
@Data
public class ResponseInfo{
/**
* 狀態(tài)碼
*/
protected int code;
/**
* 響應信息
*/
protected String message;
/**
* 返回數(shù)據(jù)
*/
private T data;
public staticResponseInfo success() {
return new ResponseInfo<>();
}
public staticResponseInfo success(T data) {
return new ResponseInfo<>(data);
}
public staticResponseInfo fail(String message) {
return new ResponseInfo<>(ResponseCodeEnums.FAIL.getCode(), message);
}
public ResponseInfo() {
this.code = ResponseCodeEnums.SUCCESS.getCode();
this.message = ResponseCodeEnums.SUCCESS.getMessage();
}
public ResponseInfo(ResponseCodeEnums statusEnums) {
this.code = statusEnums.getCode();
this.message = statusEnums.getMessage();
}
/**
* 若沒有數(shù)據(jù)返回，可以人為指定狀態(tài)碼和提示信息
*/
public ResponseInfo(int code, String msg) {
this.code = code;
this.message = msg;
}
/**
* 有數(shù)據(jù)返回時，狀態(tài)碼為200，默認提示信息為“操作成功！”
*/
public ResponseInfo(T data) {
this.data = data;
this.code = ResponseCodeEnums.SUCCESS.getCode();
this.message = ResponseCodeEnums.SUCCESS.getMessage();
}
/**
* 有數(shù)據(jù)返回，狀態(tài)碼為 200，人為指定提示信息
*/
public ResponseInfo(T data, String msg) {
this.data = data;
this.code = ResponseCodeEnums.SUCCESS.getCode();
this.message = msg;
}
}
在ResponseInfo中運用了泛型和公共方法、構造方法的封裝，方便在業(yè)務中使用。示例中只提供了部分方法的封裝，根據(jù)自身業(yè)務場景和需要可進一步封裝。
統(tǒng)一報文封裝在接口中的使用：
@Slf4j
@RestController
public class TestController {
@RequestMapping("/calc")
public ResponseInfocalc(Integer id) {
try {
// 模擬異常業(yè)務代碼
int num = 1 / id;
log.info("計算結果num={}", num);
return ResponseInfo.success();
} catch (Exception e) {
return ResponseInfo.fail("系統(tǒng)異常，請聯(lián)系管理員！");
}
}
}
在瀏覽器中訪問：http://localhost:8080/calc，返回結果如下：
{
"code": 500,
"message": "系統(tǒng)異常，請聯(lián)系管理員！",
"data": null
}這是因為沒傳遞id參數(shù)，導致業(yè)務拋異常，走異常報文返回。
在瀏覽器中訪問：http://localhost:8080/calc?id=1，返回結果如下：
{
"code": 200,
"message": "success",
"data": null
}正常返回結果。
統(tǒng)一異常處理
在上述實例中，我們通過try...catch的形式捕獲異常，并進行處理。在SpringBoot中，我們可以通過RestControllerAdvice注解來定義全局異常處理，這樣就無需每處都try...catch了。
@Slf4j
@RestControllerAdvice
public class ExceptionHandlerAdvice {
/**
* 參數(shù)格式異常處理
*/
@ExceptionHandler({IllegalArgumentException.class})
@ResponseStatus(HttpStatus.BAD_REQUEST)
public ResponseInfobadRequestException(IllegalArgumentException ex) {
log.error("參數(shù)格式不合法：{}", ex.getMessage());
return new ResponseInfo<>(HttpStatus.BAD_REQUEST.value() + "", "參數(shù)格式不符！");
}
/**
* 權限不足異常處理
*/
@ExceptionHandler({AccessDeniedException.class})
@ResponseStatus(HttpStatus.FORBIDDEN)
public ResponseInfobadRequestException(AccessDeniedException ex) {
return new ResponseInfo<>(HttpStatus.FORBIDDEN.value() + "", ex.getMessage());
}
/**
* 參數(shù)缺失異常處理
*/
@ExceptionHandler({MissingServletRequestParameterException.class})
@ResponseStatus(HttpStatus.BAD_REQUEST)
public ResponseInfobadRequestException(Exception ex) {
return new ResponseInfo<>(HttpStatus.BAD_REQUEST.value() + "", "缺少必填參數(shù)！");
}
/**
* 空指針異常
*/
@ExceptionHandler(NullPointerException.class)
@ResponseStatus(value = HttpStatus.INTERNAL_SERVER_ERROR)
public ResponseInfohandleTypeMismatchException(NullPointerException ex) {
log.error("空指針異常，{}", ex.getMessage());
return ResponseInfo.fail("空指針異常");
}
@ExceptionHandler(Exception.class)
@ResponseStatus(value = HttpStatus.INTERNAL_SERVER_ERROR)
public ResponseInfohandleUnexpectedServer(Exception ex) {
log.error("系統(tǒng)異常：", ex);
return ResponseInfo.fail("系統(tǒng)發(fā)生異常，請聯(lián)系管理員");
}
/**
* 系統(tǒng)異常處理
*/
@ExceptionHandler(Throwable.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ResponseInfoexception(Throwable throwable) {
log.error("系統(tǒng)異常", throwable);
return new ResponseInfo<>(HttpStatus.INTERNAL_SERVER_ERROR.value() + "系統(tǒng)異常，請聯(lián)系管理員！");
}
}
在上述方法中，對一些常見的異常進行了統(tǒng)一處理。通常情況下，根據(jù)業(yè)務需要還會定義業(yè)務異常，并對業(yè)務異常進行處理，大家可以根據(jù)自己項目中異常的使用情況進行拓展。
關于@RestControllerAdvice的幾點說明：
- @RestControllerAdvice注解包含了@Component注解，會把被注解的類作為組件交給Spring來管理。
- @RestControllerAdvice注解包含了@ResponseBody注解，異常處理完之后給調用方輸出一個JSON格式的封裝數(shù)據(jù)。
- @RestControllerAdvice注解有一個basePackages屬性，該屬性用來攔截哪個包中的異常信息，一般不指定，攔截項目工程中的所有異常。
- 在方法上通過@ExceptionHandler注解來指定具體的異常，在方法中處理該異常信息，最后將結果通過統(tǒng)一的JSON結構體返回給調用者。
重新定義一個接口：
@RequestMapping("/calc1")
public ResponseInfo calc1(Integer id) {
// 模擬異常業(yè)務代碼
int num = 1 / id;
log.info("計算結果num={}", num);
return ResponseInfo.success();
} 在請求的時候，不傳遞id值，即在瀏覽器中訪問：
{
"code": 500,
"message": "空指針異常",
"data": null
}可以看到統(tǒng)一異常處理對空指針異常進行了攔截處理，并返回了ExceptionHandlerAdvice中定義的統(tǒng)一報文格式。
小結
在使用SpringBoot或其他項目中，統(tǒng)一的報文格式和統(tǒng)一的異常處理都是必須的。本篇文章介紹了基于SpringBoot的實現(xiàn)，如果你的項目中采用了其他的技術棧，則可考慮對應的處理方式。同時，日常中很多類似的功能都可以統(tǒng)一進行處理，避免大量無效的硬編碼。
文章名稱：SpringBoot：如何優(yōu)雅地進行響應數(shù)據(jù)封裝、異常處理？
分享路徑：http://m.fisionsoft.com.cn/article/djjcpsd.html
