在Spring Boot项目中我们可以通过RestControllerAdvice
配合实现ResponseBodyAdvice<T>
接口来保证Spring MVC接口具有统一的返回格式,以保证前端同学能够封装统一的数据接收工具。但是很多网上的文章并没有对实际开发中的细节作出更多的讲解。今天胖哥就来分享一下我的采坑经历,也算作一个总结。
控制作用范围
我记得在前面关于Swagger3的文章中提过,如果我们不指定范围将导致Swagger无法识别接口的元信息。因此如果你使用了Swagger必须指定其范围,这里你可以通过指定扫描包来指定其作用域:
@RestControllerAdvice("cn.felord.controller")
如果你的Spring MVC控制器有统一的父类控制器的话,
@RestController
@RequestMapping("/foo")
public class FooController extends BaseController {
//todo 省略
}
也可以这样:
@RestControllerAdvice(assignableTypes = BaseController.class)
白名单
有些接口可能根据业务需要或者协议需要不能使用统一返回体,例如支付的通知应答。这就需要一个类似白名单的机制来绕过统一返回体控制器通知类。我们可以借助于ResponseBodyAdvice<T>
的下列方法实现:
boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType);
这个方法如果返回false
就表示不执行统一返回体的封装逻辑。这里我推荐注解实现。定义一个标记注解,可以定义在类上或者方法上:
@Documented
@Inherited
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface IgnoreRestBody {
}
然后上面的supports
方法这样实现:
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
return !returnType.hasMethodAnnotation(IgnoreRestBody.class);
}
如果某个Controller下所有的方法都绕过,就把这个注解标记在控制器类上;如果只想忽略某个方法上就把它标记在该方法上即可。
返回独立字符串的问题
有些接口我们会返回一个字符串:
@GetMapping("/get")
public String getStr(){
//返回了一个字符串
return "felord.cn";
}
我们希望这个字符串被统一返回体处理,类似这样:
{
code: 200,
data: "felord.cn",
msg: "返回成字符串",
}
但是你会发现并没有达到期望的效果,会抛出类型转换异常。这是因为当我们的Spring MVC接口返回数据时,会根据Content-Type
来选择一个HttpMessageConverter
来处理,而字符串在不声明Content-Type
的情况下优先使用StringHttpMessageConverter
,就导致了转换异常,需要设定成MappingJackson2HttpMessageConverter
用Jackson来处理,Spring MVC的对应配置如下:
@Configuration(proxyBeanMethods = false)
public class SpringMvcConfiguration implements WebMvcConfigurer {
@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
// 解决 String 统一封装RestBody的问题
converters.add(0, new MappingJackson2HttpMessageConverter());
}
}
嗯,这样就起效了!你以为这样就完了?你会发现你的JSON序列化不按照你设置的策略执行了。因为你new了一个而不是采用系统初始化的那个。解决方法为,将Spring IoC中的ObjectMapper
注入到MappingJackson2HttpMessageConverter
中去。或者你使用Debug调试出系统默认的MappingJackson2HttpMessageConverter
的位置,比如我的索引为7
,就可以这样配置:
@Configuration(proxyBeanMethods = false)
public class SpringMvcConfiguration implements WebMvcConfigurer {
@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
// 解决 String 统一封装RestBody的问题
HttpMessageConverter<?> httpMessageConverter = converters.get(7);
if (!(httpMessageConverter instanceof MappingJackson2HttpMessageConverter)) {
// 确保正确,如果有改动就重新debug
throw new RuntimeException("MappingJackson2HttpMessageConverter is not here");
}
converters.add(0, httpMessageConverter);
}
}
Data的类型问题
曾经一个安卓开发同学说,你这统一结构中的data
如果是数组:
{
code: 200,
data: ['a','b'],
msg: "返回成字符串",
}
后续如果data
添加其它与数组没有关系的属性就不兼容了,你应该保证这个data
是个Map
。是的,这也是问题,实际中发现不仅仅是数组,如果是int
、long
等原始类型或者String
类型都面临这种情况,需要加一个额外的判断body
是不是可能改变data
类型的类型:
private boolean checkPrimitive(Object body) {
Class<?> clazz = body.getClass();
return clazz.isPrimitive()
|| clazz.isArray()
|| Collection.class.isAssignableFrom(clazz)
|| body instanceof Number
|| body instanceof Boolean
|| body instanceof Character
|| body instanceof String;
}
然后我们在ResponseBodyAdvice<T>
实现中增加一个判断:
// 增强扩展性
if (checkPrimitive(body)) {
return RestBody.okData(Collections.singletonMap("result", body));
}
就解决问题了。
总结
今天对Spring Boot中统一返回体的一些细节问题进行了分享,希望能够帮助你解决一些实际开发中遇到的同样问题。多多关注:码农小胖哥 分享更多有用的编程知识。
关注公众号:Felordcn 获取更多资讯
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。