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