我踩过的Spring Boot统一返回体中的坑_swagger3 统一的返回封装类 ui不显示response-优快云博客

本文详细介绍了在SpringBoot项目中如何通过@RestControllerAdvice和ResponseBodyAdvice接口实现接口返回格式的统一，包括如何控制作用范围、设置白名单、处理返回独立字符串的问题，并提供了具体的代码示例。同时，还分享了解决返回字符串时遇到的类型转换异常和JSON序列化策略问题的解决方案。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

在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);
        
       

       
        
       
       
        
             }
        
       

       
        
       
       
        
         }