1. 介绍
如果你正在寻找一种方法来规范化你的RESTful API的返回值,那么这篇文章将是你的理想选择。通过阅读这篇文章,你将了解到如何使用Spring ResponseBodyAdvice来改善你的API设计和实现。
为什么要统一接口返回值?
- 统一规范:通过 ResponseBodyAdvice 可以对所有接口返回值进行统一的包装,从而制定统一的规范,使得接口返回值更加清晰、易于理解。这对于整个应用程序的接口管理非常有帮助,可以避免不同接口返回值格式不一致的问题。
- 可读性增强:通过包装返回值,可以添加必要的字段,如状态码、状态消息等,使得接口返回值更加易于阅读和理解。这对于开发者和用户来说都是非常有益的,可以更方便地了解接口的返回结果。
- 扩展性:通过 ResponseBodyAdvice 可以很方便地扩展接口返回值的格式,例如添加JSON格式的返回值,而不需要修改原有的接口代码。这使得应用程序具有更好的扩展性,可以根据需求灵活地添加新的返回值格式。
2. 开发流程
定义统一返回值的包装类
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 {
@Resource
private ObjectMapper objectMapper ;
@Override
public boolean supports(MethodParameter returnType, Class> converterType) {
// 只有返回值不是R类型的时候才通过该Advice进行处理
return !returnType.getParameterType().equals(R.class) ;
}
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
Class> selectedConverterType, ServerHttpRequest request,
ServerHttpResponse response) {
// 统一返回值处理
return R.success(body) ;
}
}
测试接口
@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)) ;
}
}
首先,测试接口/advices/{id}
图片
处理了最终的返回结果。
继续测试/advices/str
图片
程序出错了
控制台输出
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]
出现ClassCastException错误,是由于Controller接口返回值是String,那么匹配到的HttpMessageConverter是StringHttpMessageConverter处理,而该转换器的调用是在ResponseBodyAdvice之后执行,这时候的字符串已经被转换成了R对象,所以最后在write时就出现了类型转换错误。通过如下方式处理
public Object beforeBodyWrite(Object body,
MethodParameter returnType,
MediaType selectedContentType,
Class> 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) ;
}
针对返回值是String类型的正常了。
通过自定义注解排除那些不需要处理的接口
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface NoR {
}
修改PackResponseBodyAdvice#supports方法,添加NoR注解的判断
public boolean supports(MethodParameter returnType, Class> converterType) {
// 方法上或者是类上没有NoR注解
return (!returnType.hasMethodAnnotation(NoR.class)
|| AnnotatedElementUtils.hasAnnotation(returnType.getContainingClass(), NoR.class))
&& !returnType.getParameterType().equals(R.class) ;
}
这样就可以控制具体哪些方法不进行处理了。
通过自定义ResponseBodyAdvice,我们可以实现接口统一返回值的处理,从而提高了接口的可读性、扩展性和错误处理能力。同时,这也有助于保持代码的清晰和规范。通过学习和实践,我们可以更好地利用SpringMVC相应的功能,开发出更优秀的应用程序。