SpringBoot + MinIO 輕松構建物件儲存服務，支持私有化部署！

2024-09-04科技

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、統一返回格式

@RestControllerpublic 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 註解方法，進行增強攔截 */@ControllerAdvicepublic 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 物件類別，直接改成對應的業務物件即可，範例如下：

@RestControllerpublic 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、字串類別返回問題

假如返回的介面數據物件是字串類別，比如如下範例：

@RestControllerpublic 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 時，對其單獨進行處理，範例如下：

/** * 如果開啟，就會對返回結果進行處理 */@Overridepublic 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 層投擲的異常，具體套用範例如下：

@ControllerAdvicepublic 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";}

啟動服務後，在瀏覽器發起請求，返回結果如下：