優(yōu)雅地統(tǒng)一處理接口返回值的最佳實(shí)踐
1. 介紹
如果你正在尋找一種方法來(lái)規(guī)范化你的RESTful API的返回值，那么這篇文章將是你的理想選擇。通過(guò)閱讀這篇文章，你將了解到如何使用Spring ResponseBodyAdvice來(lái)改善你的API設(shè)計(jì)和實(shí)現(xiàn)。
為什么要統(tǒng)一接口返回值？
- 統(tǒng)一規(guī)范：通過(guò) ResponseBodyAdvice 可以對(duì)所有接口返回值進(jìn)行統(tǒng)一的包裝，從而制定統(tǒng)一的規(guī)范，使得接口返回值更加清晰、易于理解。這對(duì)于整個(gè)應(yīng)用程序的接口管理非常有幫助，可以避免不同接口返回值格式不一致的問(wèn)題。
- 可讀性增強(qiáng)：通過(guò)包裝返回值，可以添加必要的字段，如狀態(tài)碼、狀態(tài)消息等，使得接口返回值更加易于閱讀和理解。這對(duì)于開(kāi)發(fā)者和用戶來(lái)說(shuō)都是非常有益的，可以更方便地了解接口的返回結(jié)果。
- 擴(kuò)展性：通過(guò) ResponseBodyAdvice 可以很方便地?cái)U(kuò)展接口返回值的格式，例如添加JSON格式的返回值，而不需要修改原有的接口代碼。這使得應(yīng)用程序具有更好的擴(kuò)展性，可以根據(jù)需求靈活地添加新的返回值格式。
2. 開(kāi)發(fā)流程
定義統(tǒng)一返回值的包裝類
public class R {
private Integer code ;
private Object data ;
private String message ;
public R(Integer code, Object data, String message) {
this.code = code ;
this.data = data ;
this.message = message ;
}
public static R success(Object data) {
return new R(200, data, "success") ;
}
public static R failure(String message) {
return new R(500, null, message) ;
}
}自定義ResponseBodyAdvice
@RestControllerAdvice
public class PackResponseBodyAdvice implements ResponseBodyAdvice<Object> {
@Resource
private ObjectMapper objectMapper ;
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
// 只有返回值不是R類型的時(shí)候才通過(guò)該Advice進(jìn)行處理
return !returnType.getParameterType().equals(R.class) ;
}
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request,
ServerHttpResponse response) {
// 統(tǒng)一返回值處理
return R.success(body) ;
}
}測(cè)試接口
@RestController
@RequestMapping("/advices")
public class AdviceController {
@GetMapping("/str")
public String str() {
return "success" ;
}
@GetMapping("/{id}")
public User body(@PathVariable("id") Long id) {
return new User(id, "張三 - " + new Random().nextInt(1000)) ;
}
}首先，測(cè)試接口/advices/{id}
圖片
處理了最終的返回結(jié)果。
繼續(xù)測(cè)試/advices/str
圖片
程序出錯(cuò)了
控制臺(tái)輸出
java.lang.ClassCastException: class com.pack.common.dto.R cannot be cast to class java.lang.String (com.pack.common.dto.R is in unnamed module of loader 'app'; java.lang.String is in module java.base of loader 'bootstrap')
at org.springframework.http.converter.StringHttpMessageConverter.addDefaultHeaders(StringHttpMessageConverter.java:44) ~[spring-web-5.3.27.jar:5.3.27]
at org.springframework.http.converter.AbstractHttpMessageConverter.write(AbstractHttpMessageConverter.java:211) ~[spring-web-5.3.27.jar:5.3.27]出現(xiàn)ClassCastException錯(cuò)誤，是由于Controller接口返回值是String，那么匹配到的HttpMessageConverter是StringHttpMessageConverter處理，而該轉(zhuǎn)換器的調(diào)用是在ResponseBodyAdvice之后執(zhí)行，這時(shí)候的字符串已經(jīng)被轉(zhuǎn)換成了R對(duì)象，所以最后在write時(shí)就出現(xiàn)了類型轉(zhuǎn)換錯(cuò)誤。通過(guò)如下方式處理
public Object beforeBodyWrite(Object body,
MethodParameter returnType,
MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request,
ServerHttpResponse response) {
if (body instanceof String) {
try {
return this.objectMapper.writeValueAsString(R.success(body)) ;
} catch (JsonProcessingException e) {
e.printStackTrace();
}
}
return R.success(body) ;
}
針對(duì)返回值是String類型的正常了。
通過(guò)自定義注解排除那些不需要處理的接口
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface NoR {
}修改PackResponseBodyAdvice#supports方法，添加NoR注解的判斷
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
// 方法上或者是類上沒(méi)有NoR注解
return (!returnType.hasMethodAnnotation(NoR.class)
|| AnnotatedElementUtils.hasAnnotation(returnType.getContainingClass(), NoR.class))
&& !returnType.getParameterType().equals(R.class) ;
}這樣就可以控制具體哪些方法不進(jìn)行處理了。
通過(guò)自定義ResponseBodyAdvice，我們可以實(shí)現(xiàn)接口統(tǒng)一返回值的處理，從而提高了接口的可讀性、擴(kuò)展性和錯(cuò)誤處理能力。同時(shí)，這也有助于保持代碼的清晰和規(guī)范。通過(guò)學(xué)習(xí)和實(shí)踐，我們可以更好地利用SpringMVC相應(yīng)的功能，開(kāi)發(fā)出更優(yōu)秀的應(yīng)用程序。
