Spring Boot 統(tǒng)一接口響應(yīng)格式的正確姿勢(shì)！
01、背景介紹
熟悉 web 系統(tǒng)開發(fā)的同學(xué)可能比較熟悉，目前絕大多數(shù)的互聯(lián)網(wǎng)軟件平臺(tái)基本都是前后端分離的開發(fā)模式，為了加快前后端接口對(duì)接速度，一套完善且規(guī)范的接口標(biāo)準(zhǔn)格式是非常有必要的，不僅能夠提升開發(fā)效率，也會(huì)讓代碼看起來更加簡(jiǎn)潔、好維護(hù)。
今天這篇文章，我們一起來學(xué)習(xí)一下如何在 Spring Boot 中統(tǒng)一接口的返回?cái)?shù)據(jù)格式。
02、定義數(shù)據(jù)返回格式
最常見的一種做法是封裝一個(gè)工具類，在類中定義需要返回的字段信息，比如狀態(tài)碼、結(jié)果描述、結(jié)果數(shù)據(jù)集等，然后在接口中返回給客戶端。
例如如下示例。
2.1、定義返回對(duì)象
public class ResultMsg<T> {
/**狀態(tài)碼**/
private int code;
/**結(jié)果描述**/
private String message;
/**結(jié)果集**/
private T data;
/**時(shí)間戳**/
private long timestamp;
// set、get方法等...
public ResultMsg() {
timestamp = System.currentTimeMillis();
}
public static <T> ResultMsg<T> success() {
return success(null);
}
public static <T> ResultMsg<T> success(T data) {
ResultMsg<T> resultMsg = new ResultMsg<>();
resultMsg.setCode(ReturnCode.RC200.getCode());
resultMsg.setMessage(ReturnCode.RC200.getMessage());
resultMsg.setData(data);
return resultMsg;
}
public static <T> ResultMsg<T> fail(String message) {
return fail(ReturnCode.RC500.getCode(), message);
}
public static <T> ResultMsg<T> fail(ReturnCode returnCode) {
return fail(returnCode.getCode(), returnCode.getMessage());
}
public static <T> ResultMsg<T> fail(int code, String message) {
ResultMsg<T> resultMsg = new ResultMsg<>();
resultMsg.setCode(code);
resultMsg.setMessage(message);
return resultMsg;
}
}2.2、定義狀態(tài)碼
public enum ReturnCode {
/**操作成功**/
RC200(200,"請(qǐng)求成功"),
/**access_denied**/
RC403(403,"無訪問權(quán)限,請(qǐng)聯(lián)系管理員授予權(quán)限"),
/**服務(wù)異常**/
RC500(500,"系統(tǒng)異常，請(qǐng)稍后重試");
/**自定義狀態(tài)碼**/
private final int code;
/**自定義描述**/
private final String message;
ReturnCode(int code, String message){
this.code = code;
this.message = message;
}
public int getCode() {
return code;
}
public String getMessage() {
return message;
}
}2.3、統(tǒng)一返回格式
@RestController
public class UserController {
@Autowired
private UserService userService;
@RequestMapping(value = "/queryUser")
public ResultMsg query(@RequestParam("userId") Long userId){
try {
// 業(yè)務(wù)代碼...
User user = userService.queryId(userId);
return ResultMsg.success(user);
} catch (Exception e){
return ResultMsg.fail(e.getMessage());
}
}
}當(dāng)請(qǐng)求http://localhost:8080/queryUser?userId=1地址時(shí)，返回結(jié)果示例如下：
{
"code": 200,
"message": "請(qǐng)求成功",
"data": {
"userId": 1,
"userName": "張三"
},
"timestamp": 1716540843798
}前端根據(jù)code值來判斷接口請(qǐng)求是否成功。
這種實(shí)現(xiàn)方式屬于萬能的一種方式，唯一的缺點(diǎn)就是重復(fù)編程工作很大，每個(gè)接口都要根據(jù)業(yè)務(wù)的要求進(jìn)行不同程度的try..catch操作，如果有幾百個(gè)接口，代碼看起來會(huì)比較臃腫。
03、高級(jí)封裝實(shí)現(xiàn)
Spring Boot 框架其實(shí)已經(jīng)幫助開發(fā)者封裝了很多實(shí)用的工具，比如ResponseBodyAdvice，我們可以利用來實(shí)現(xiàn)數(shù)據(jù)格式的統(tǒng)一返回。
簡(jiǎn)單的說，ResponseBodyAdvice可以對(duì)controller層中的擁有@ResponseBody注解屬性的方法進(jìn)行響應(yīng)攔截，用戶可以利用這一特性來封裝數(shù)據(jù)的返回格式，也可以進(jìn)行加密、簽名等操作。
3.1、ResponseBodyAdvice 用法介紹
/**
* 對(duì)controller 層中 ResponseBody 注解方法，進(jìn)行增強(qiáng)攔截
*/
@ControllerAdvice
public class CustomerResponseAdvice implements ResponseBodyAdvice<Object> {
/**
* 是否開啟支持功能
*/
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
return true;
}
/**
* 如果開啟，就會(huì)對(duì)返回結(jié)果進(jìn)行處理
*/
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
return ResultMsg.success(body);
}
}3.2、調(diào)整接口返回參數(shù)
此時(shí)，在controller層無需返回ResultMsg對(duì)象類型，直接改成對(duì)應(yīng)的業(yè)務(wù)對(duì)象即可，示例如下：
@RestController
public class UserController {
@Autowired
private UserService userService;
@RequestMapping(value = "/queryUser")
public User query(@RequestParam("userId") Long userId){
// 業(yè)務(wù)代碼...
User user = userService.queryId(userId);
return user;
}
}在此請(qǐng)求接口地址，返回結(jié)果與上文一致。
3.3、字符串類型返回問題
假如返回的接口數(shù)據(jù)對(duì)象是字符串類型，比如如下示例：
@RestController
public class HelloController {
@GetMapping(value = "/hello")
public String hello(){
return "hello world";
}
}先猜猜結(jié)果如下？
在瀏覽器中請(qǐng)求地址http://localhost:8080/hello，結(jié)果如下：
圖片
拋出異常了！錯(cuò)誤原因如下。
java.lang.ClassCastException: com.example.basic.core.result.ResultMsg cannot be cast to java.lang.String發(fā)生這個(gè)現(xiàn)象的原因在于：當(dāng)接口返回的結(jié)果是String類型時(shí)，會(huì)優(yōu)先使用StringHttpMessageConverter字符串消息轉(zhuǎn)換器來響應(yīng)數(shù)據(jù)，其次采用對(duì)象轉(zhuǎn)換器。
因此我們需要對(duì)CustomerResponseAdvice進(jìn)行改造，當(dāng)返回的數(shù)據(jù)類型為String時(shí)，對(duì)其單獨(dú)進(jìn)行處理，示例如下：
/**
* 如果開啟，就會(huì)對(duì)返回結(jié)果進(jìn)行處理
*/
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
// 設(shè)置響應(yīng)類型為json
response.getHeaders().setContentType(MediaType.APPLICATION_JSON_UTF8);
if(body != null && (body instanceof ResultMsg)){
// 如果body返回的是ResultMsg類型的對(duì)象，不進(jìn)行增強(qiáng)處理
return body;
}
if(body != null && (body instanceof String)){
// 如果body返回的是String類型的對(duì)象，單獨(dú)處理
return toJson(body);
}
return ResultMsg.success(body);
}
private Object toJson(Object body) {
try {
return new ObjectMapper().writeValueAsString(ResultMsg.success(body));
} catch (JsonProcessingException e) {
throw new RuntimeException("無法轉(zhuǎn)發(fā)json格式", e);
}
}啟動(dòng)服務(wù)后，再次請(qǐng)求地址，結(jié)果如下：
圖片
從日志上可以清晰的看到，與預(yù)期一致！
**有個(gè)地方需要重點(diǎn)注意一下：默認(rèn)String類型的數(shù)據(jù)響應(yīng)給客戶端的格式為text/html，為了統(tǒng)一響應(yīng)格式，需要手動(dòng)設(shè)置響應(yīng)類型為json**。
3.4、全局異常處理
在上文的介紹中，當(dāng)遇到異常時(shí)第一時(shí)間想到的是try...catch。其實(shí)大量的try...catch，不僅編程工作量很大，而且可讀性也差。
在 Spring Boot 中，其實(shí)我們不用一個(gè)一個(gè)的去寫，我們可以利用@ControllerAdvice和@ExceptionHandler注解實(shí)現(xiàn)全局異常處理器，攔截controller層拋出的異常，具體應(yīng)用示例如下：
@ControllerAdvice
public class GlobalExceptionHandler {
/**
* 處理全局異常
* @param e
* @return
*/
@ExceptionHandler(value = Exception.class)
@ResponseBody
public Object exceptionHandler(Exception e){
// 業(yè)務(wù)異常
if(e instanceof BusinessException){
BusinessException ex = (BusinessException) e;
return ResultMsg.fail(e.getCode, ex.getMessage());
}
// 運(yùn)行時(shí)異常
if(e instanceof RuntimeException){
RuntimeException ex = (RuntimeException) e;
return ResultMsg.fail(500, ex.getMessage());
}
return ResultMsg.fail(999, e.getMessage());
}
}下面我們寫一個(gè)異常接口來驗(yàn)證一下，代碼如下：
@GetMapping(value = "/fail")
public String fail(){
if(1 == 1){
throw new RuntimeException("測(cè)試");
}
return "1";
}啟動(dòng)服務(wù)后，在瀏覽器發(fā)起請(qǐng)求，返回結(jié)果如下：
04、小結(jié)
最后總結(jié)一下，在實(shí)際的項(xiàng)目開發(fā)過程中，統(tǒng)一響應(yīng)格式通常有兩種實(shí)現(xiàn)方式。
- 方式一：在接口層直接返回標(biāo)準(zhǔn)格式，同時(shí)通過全局異常處理器來捕捉并處理異常；
- 方式二：在接口層返回業(yè)務(wù)對(duì)象，通過實(shí)現(xiàn)ResponseBodyAdvice接口統(tǒng)一封裝格式
如果不希望 Spring Boot 托管響應(yīng)內(nèi)容，要求編程風(fēng)格統(tǒng)一，可以采用方式一；如果希望盡量簡(jiǎn)化業(yè)務(wù)代碼的開發(fā)量，可以采用方式二。
這兩種方式，項(xiàng)目開發(fā)中都有所應(yīng)用，具體采用哪一種，通常以團(tuán)隊(duì)開發(fā)風(fēng)格為主。
示例代碼地址：
https://gitee.com/pzblogs/spring-boot-example-demo
