乐趣区

结合参数接收响应转换原理讲解SpringBoot常用注解

jiezi

一、常用注解回顾

1.1 @RequestBody 与 @ResponseBody


// 注意并不要求 @RequestBody 与 @ResponseBody 成对使用。public @ResponseBody  AjaxResponse saveArticle(@RequestBody ArticleVO article)

如上代码所示：

  • @RequestBody 修饰请求参数，注解用于接收 HTTP 的 body，默认是使用 JSON 的格式
  • @ResponseBody 修饰返回值，注解用于在 HTTP 的 body 中携带响应数据，默认是使用 JSON 的格式。如果不加该注解，spring 响应字符串类型，是跳转到模板页面或 jsp 页面的开发模式。说白了：加上这个注解你开发的是一个数据接口，不加这个注解你开发的是一个页面跳转控制器。

那么我们有一个问题：如果我们想接收或 XML 数据该怎么办？我们想响应 excel 的数据格式该怎么办？我们后文来回答这个问题。

1.2. @RequestMapping 注解

@RequestMapping 注解是所有常用注解中，最有看点的一个注解，用于标注 HTTP 服务端点。它的很多属性对于丰富我们的应用开发方式方法，都有很重要的作用。如：

  • value：应用请求端点，最核心的属性，用于标志请求处理方法的唯一性；
  • method：HTTP 协议的 method 类型，如：GET、POST、PUT、DELETE 等；
  • consumes：HTTP 协议请求内容的数据类型（Content-Type），例如 application/json, text/html;
  • produces: HTTP 协议响应内容的数据类型。下文会详细讲解。
  • params：HTTP 请求中必须包含某些参数值的时候，才允许被注解标注的方法处理请求。
  • headers：HTTP 请求中必须包含某些指定的 header 值，才允许被注解标注的方法处理请求。

@RequestMapping(value = "/article", method = POST)
@PostMapping(value = "/article")

上面代码中两种写法起到的是一样的效果，也就是 PostMapping 等同于 @RequestMapping 的 method 等于 POST。同理：@GetMapping、@PutMapping、@DeleteMapping 也都是简写的方式。

1.3. @RestController 与 @Controller

@Controller 注解是开发中最常使用的注解，它的作用有两层含义：

  • 一是告诉 Spring，被该注解标注的类是一个 Spring 的 Bean，需要被注入到 Spring 的上下文环境中。
  • 二是该类里面所有被 RequestMapping 标注的注解都是 HTTP 服务端点。

@RestController 相当于 @Controller 和 @ResponseBody 结合。它有两层含义：

  • 一是作为 Controller 的作用，将控制器类注入到 Spring 上下文环境，该类 RequestMapping 标注方法为 HTTP 服务端点。
  • 二是作为 ResponseBody 的作用，请求响应默认使用的序列化方式是 JSON，而不是跳转到 jsp 或模板页面。

1.4. @PathVariable 与 @RequestParam

PathVariable 用于 URI 上的 {参数}，如下方法用于删除一篇文章，其中 id 为文章 id。如：我们的请求 URL 为“/article/1”, 那么将匹配 DeleteMapping 并且 PathVariable 接收参数 id=1。而 RequestParam 用于接收普通表单方式或者 ajax 模拟表单提交的参数数据。

@DeleteMapping("/article/{id}")
public @ResponseBody AjaxResponse deleteArticle(@PathVariable Long id) {@PostMapping("/article")
public @ResponseBody AjaxResponse deleteArticle(@RequestParam Long id) {

二、接收复杂嵌套对象参数

有一些朋友可能还无法理解 RequestBody 注解存在的真正意义，表单数据提交用 RequestParam 就好了，为什么还要搞出来一个 RequestBody 注解呢？RequestBody 注解的真正意义在于能够使用对象或者嵌套对象接收前端数据。

仔细看上面的代码，是一个 paramData 对象里面包含了一个 bestFriend 对象。这种数据结构使用 RequestParam 就无法接收了，RequestParam 只能接收平面的、一对一的参数。像上文中这种数据结构的参数，就需要我们在 java 服务端定义两个类，一个类是 ParamData，一个类是 BestFriend.

public class ParamData {
    private String name;
    private int id;
    private String phone;
    private BestFriend bestFriend;
    
    public static class BestFriend {
        private String address;
        private String sex;
    }
}
  • 注意上面代码中省略了 GET、SET 方法等必要的 java plain model 元素。
  • 注意成员变量名称一定要和 JSON 属性名称对应上。
  • 注意接收不同类型的参数，使用不同的成员变量类型

完成以上动作，我们就可以使用 @RequestBody ParamData paramData，一次性的接收以上所有的复杂嵌套对象参数了，参数对象的所有属性都将被赋值。

三、Http 数据转换的原理

大家现在使用 JSON 都比较普遍了，其方便易用、表达能力强，是绝大部分数据接口式应用的首选。那么如何响应其他的类型的数据？其中的判别原理又是什么？下面就来给大家介绍一下：

  • 当一个 HTTP 请求到达时是一个 InputStream，通过 HttpMessageConverter 转换为 java 对象，从而进行参数接收。
  • 当对一个 HTTP 请求进行响应时，我们首先输出的是一个 java 对象，然后由 HttpMessageConverter 转换为 OutputStream 输出。

当我们在 Spring Boot 应用中集成了 jackson 的类库之后，如下的一些 HttpMessageConverter 将会被加载。

实现类 功能说明
StringHttpMessageConverter 将请求信息转为字符串
FormHttpMessageConverter 将表单数据读取到 MultiValueMap 中
XmlAwareFormHttpMessageConverter 扩展与 FormHttpMessageConverter，如果部分表单属性是 XML 数据，可用该转换器进行读取
ResourceHttpMessageConverter 读写 org.springframework.core.io.Resource 对象
BufferedImageHttpMessageConverter 读写 BufferedImage 对象
ByteArrayHttpMessageConverter 读写二进制数据
SourceHttpMessageConverter 读写 java.xml.transform.Source 类型的对象
MarshallingHttpMessageConverter 通过 Spring 的 org.springframework,xml.Marshaller 和 Unmarshaller 读写 XML 消息
Jaxb2RootElementHttpMessageConverter 通过 JAXB2 读写 XML 消息，将请求消息转换为标注的 XmlRootElement 和 XmlType 连接的类中
MappingJacksonHttpMessageConverter 利用 Jackson 开源包的 ObjectMapper 读写 JSON 数据
RssChannelHttpMessageConverter 读写 RSS 种子消息
AtomFeedHttpMessageConverter 和 RssChannelHttpMessageConverter 能够读写 RSS 种子消息

根据 HTTP 协议的 Accept 和 Content-Type 属性，以及参数数据类型来判别使用哪一种 HttpMessageConverter。当使用 RequestBody 或 ResponseBody 时，再结合前端发送的 Accept 数据类型，会自动判定优先使用 MappingJacksonHttpMessageConverter 作为数据转换器。但是，不仅 JSON 可以表达对象数据类型，XML 也可以。如果我们希望使用 XML 格式该怎么告知 Spring 呢，那就要使用到 produces 属性了。

@GetMapping(value ="/demo",produces = MediaType.APPLICATION_XML_VALUE)

这里我们明确的告知了返回的数据类型是 xml，就会使用 Jaxb2RootElementHttpMessageConverter 作为默认的数据转换器。当然实现 XML 数据响应比 JSON 还会更复杂一些，还需要结合 @XmlRootElement、@XmlElement 等注解实体类来使用。同理 consumes 属性你是不是也会用了呢。

四、自定义 HttpMessageConverter

其实绝大多数的数据格式都不需要我们自定义 HttpMessageConverter，都有第三方类库可以帮助我们实现 (包括下文代码中的 Excel 格式)。但有的时候，有些数据的输出格式并没有类似于 Jackson 这种类库帮助我们处理，需要我们自定义数据格式。该怎么做? 下面代码只是帮助我们理解的一个例子，不要用于生产：

@Service
public class TeamToXlsConverter extends AbstractHttpMessageConverter<Team> {private static final MediaType EXCEL_TYPE = MediaType.valueOf("application/vnd.ms-excel");

    TeamToXlsConverter() {super(EXCEL_TYPE);
    }

    @Override
    protected Team readInternal(final Class<? extends Team> clazz, final HttpInputMessage inputMessage) throws IOException, HttpMessageNotReadableException {return null;}

    @Override
    protected boolean supports(final Class<?> clazz) {return (Team.class == clazz);
    }

    @Override
    protected void writeInternal(final Team team, final HttpOutputMessage outputMessage) throws IOException, HttpMessageNotWritableException {try (final Workbook workbook = new HSSFWorkbook()) {final Sheet sheet = workbook.createSheet();
            int rowNo = 0;
            for (final TeamMember member : team.getMembers()) {final Row row = sheet.createRow(rowNo++);
                row.createCell(0)
                   .setCellValue(member.getName());
            }
            workbook.write(outputMessage.getBody());
        }
    }
}
  • 实现 AbstractHttpMessageConverter 接口
  • 指定该转换器是针对哪种数据格式的？如上文代码中的 ”application/vnd.ms-excel”
  • 指定该转换器针对那些对象数据类型？如上文代码中的 supports 函数
  • 使用 writeInternal 对数据进行输出处理，上例中是输出为 Excel 格式。

期待您的关注

  • 博主最近新写了一本书：《手摸手教您学习 SpringBoot 系列 -16 章 97 节》
  • 本文转载注明出处（必须带连接，不能只转文字）：字母哥博客。
退出移动版