使用Spring3MVCHttpMessageConverter功能构建RESTfulweb服务

简介

随附文章&＃xff0c;“使用 Spring 3 构建 RESTful web 服务”&＃xff08;参见 参考资料&＃xff09;&＃xff0c;介绍了使用 Spring 构建 RESTful web 服务的方式。还解释了如何使用 ContentNegotiatingViewResolver 生成多个具象&＃xff0c;这是 RESTful web 服务的一个重要功能。本文还阐述了使用 HttpMessageConverter 生成多个具象的另一种方式&＃xff0c;并且本文中的示例展示了如何使用RestTemplate 和 HttpMessageConverter 与服务进行通信。

回页首

Spring MVC 中的 REST 支持

本部分提供了支持 RESTful web 服务的主要 Spring 功能&＃xff08;或注释&＃xff09;的概述。

&＃64;Controller

使用 &＃64;Controller 注释对将成为 MVC 中控制器的类进行注释并处理 HTTP 请求。

&＃64;RequestMapping

使用 &＃64;RequestMapping 注释对函数进行注释&＃xff0c;该函数处理某些 HTTP 方法、URI 或 HTTP 头。此注释是 Spring REST 支持的关键。可以更改 method 参数以处理其他 HTTP 方法。

例如&＃xff1a;

&＃64;RequestMapping(method&＃61;RequestMethod.GET, value&＃61;"/emps", headers&＃61;"Accept&＃61;application/xml, application/json")

&＃64;PathVariable

使用 &＃64;PathVariable 注释可将 URI 中的路径变量作为参数插入。

例如&＃xff1a;

&＃64;RequestMapping(method&＃61;RequestMethod.GET, value&＃61;"/emp/{id}") public ModelAndView getEmployee(&＃64;PathVariable String id) { … }

其他有用的注释

使用 &＃64;RequestParam 将 URL 参数插入方法中。

使用 &＃64;RequestHeader 将某一 HTTP 头插入方法中。

使用 &＃64;RequestBody 将 HTTP 请求正文插入方法中。

使用 &＃64;ResponseBody 将内容或对象作为 HTTP 响应正文返回。

使用 HttpEntity 将它自动插入方法中&＃xff0c;如果将它作为参数提供。

使用 ResponseEntity 返回具有自定义状态或头的 HTTP 响应。

例如&＃xff1a;

public &＃64;ResponseBody Employee getEmployeeBy(&＃64;RequestParam("name") String name, &＃64;RequestHeader("Accept") String accept, &＃64;RequestBody String body) {…} public ResponseEntity method(HttpEntity entity) {…}

参见 Spring 文档&＃xff08;参见 参考资料) 获得可插入方法中的支持注释或对象的完整列表。

多具象支持

使用不同 MIME 类型表示同一资源是 RESTful web 服务的一个重要方面。通常&＃xff0c;可以使用具有不同 "accept" HTTP 头的同一 URI 提取具有不同表示的资源。还可以使用不同的 URI 或具有不同请求参数的 URI。

“使用 Spring 3 构建 RESTful web 服务”&＃xff08;参见 参考资料&＃xff09;介绍了 ContentNegotiatingViewResolver&＃xff0c;可以挑选不同的视图解析器处理同一 URI&＃xff08;具有不同的 accept 头&＃xff09;。因此&＃xff0c;ContentNegotiatingViewResolver 可用于生成多个具象。

还有另一种方式可生成多具象 — 将 HttpMessageConverter 和 c&＃64;ResponseBody 注释结合起来使用。使用这种方法无需使用视图技术。

回页首

HttpMessageConverter

HTTP 请求和响应是基于文本的&＃xff0c;意味着浏览器和服务器通过交换原始文本进行通信。但是&＃xff0c;使用 Spring&＃xff0c;controller 类中的方法返回纯 &＃39;String&＃39; 类型和域模型&＃xff08;或其他 Java 内建对象&＃xff09;。如何将对象序列化/反序列化为原始文本&＃xff1f;这由HttpMessageConverter 处理。Spring 具有捆绑实现&＃xff0c;可满足常见需求。表 1 显示了一些示例。

回页首

构建 RESTful web 服务

在此部分中&＃xff0c;学习构建可生成多个具象的简单 RESTful web 服务。示例应用程序中使用的一些资源在 “使用 Spring 3 构建 RESTful web 服务”&＃xff08;参见 参考资料&＃xff09;中构建。还可以 下载 示例代码。

首先&＃xff0c;您必须配置 HttpMessageConverter。要生成多个具象&＃xff0c;自定义几个 HttpMessageConverter 实例&＃xff0c;以将对象转换为不同的媒体类型。此部分包括 JSON、ATOM 和 XML 媒体类型。

JSON

从最简单的示例开始。JSON 是一个轻量型的数据交换格式&＃xff0c;人们可轻松地进行读取和编写。清单 1 显示了配置 JSON converter 的代码。

在配置中&＃xff0c;注册了 3 个转换程序。MappingJacksonHttpMessageConverter 用于将对象转换为 JSON&＃xff0c;反之亦然。此内置转换程序使用 Jackson 的 ObjectMapper 将 JSON 映射到 JavaBean&＃xff0c;因此您必须将下列 Jackson JAR 文件添加到类路径。

• org.codehaus.jackson.jar
• org.codehaus.jackson.mapper.jar

下一步是编写一个方法&＃xff0c;处理请求 JSON 具象的请求。清单 2 显示了详细信息。

&＃64;ResponseBody 注释用于将返回对象&＃xff08;Employee 或 EmployeeList&＃xff09;变为响应的正文内容&＃xff0c;将使用MappingJacksonHttpMessageConverter 将其映射到 JSON。

使用 HttpMessageConverter 和 &＃64;ResponseBody&＃xff0c;您可以实现多个具象&＃xff0c;而无需包含 Spring 的视图技术 — 这是使用ContentNegotiatingViewResolver 所不具有的一个优势。

现在您可以使用 CURL 或 REST Client Firefox 插件调用请求。记住添加一个 HTTP 头&＃xff1a;Accept&＃61;application/json。清单 3 以 JSON 格式显示了所需的响应。

XML

Spring 的内置转换程序 MarshallingHttpMessageConverter 用于在对象和 XML (OXM) 之间进行映射。本示例使用 JAXB 2 作为转换程序的 marshaller/un-marshaller。清单 4 显示了配置。

了解 JAXB 2 不能很好地支持 java.util.List 到 XML 的映射很重要。常用实践是为对象集添加一个包装类。参见 “使用 Spring 3 构建 RESTful web 服务”&＃xff08;参见 参考资料&＃xff09;或 下载 源代码&＃xff0c;了解此 JAXB 注释类的详细信息。

在处理请求的控制器中的方法如何&＃xff1f;回顾一下 清单 2 中的代码。发现在此处不需要添加任何代码一点也不奇怪。您只需要在 Accept 头中添加另一个支持的媒体类型&＃xff0c;如下所示。

转换程序将对象正确地映射到请求的类型&＃xff08;JSON 或 XML&＃xff09;。清单 5 显示了请求 application/xml 具象的理想结果。

ATOM 源

ATOM 源是另一种在 RESTful web 服务中交换数据的常见格式。Atom 源文档是 Atom 源&＃xff08;包括有关源及与其相关的所有或部分项的元数据&＃xff09;的具象。其根是 atom:feed 元素。还有一个 ATOM Publish Protocol (APP) 定义交换格式和行为。&＃xff08;定义 ATOM 和 APP 格式不在本文的讨论范围内。参见 参考资料 了解更多信息。&＃xff09;

本示例使用 AtomFeedHttpMessageConverter 转换 ATOM 源&＃xff0c;利用 ROME ATOM API。因此&＃xff0c;您必须在类路径中包含 JAR 文件 sun.syndication.jar。清单 6 显示了此转换程序的配置。

清单 7 显示了处理 ATOM 请求和源生成的代码。

在上述代码中&＃xff0c;注意&＃xff1a;

• getEmpFeed() 方法将同一 URI 处理为 getAllEmp()&＃xff0c;但具有不同的 Accept 头。
• 使用 employeeFeed() 方法&＃xff0c;您可以将 Employee 对象解析为 XML&＃xff0c;然后将其添加到源项的  元素。

清单 8 显示了请求 URI /rest/service/emps 的 application/atom&＃43;xml 具象时的输出。

实现 POST、PUT 和 DELETE

目前为止&＃xff0c;示例已实现了几个处理 HTTP GET 方法的方法。清单 9 显示了 POST、PUT 和 DELETE 方法的实现。

&＃64;RequestBody 注释在 addEmp() 和 updateEmp() 方法中使用。它接收 HTTP 请求正文并试图使用注册的HttpMessageConverter 将其转换为对象类。在下一部分中&＃xff0c;您将使用 RestTemplate 与这些服务进行通信。

回页首

使用 RestTemplate 与 REST 服务进行通信

“使用 Spring 3 构建 RESTful web 服务”&＃xff08;参见 参考资料&＃xff09;介绍了如何使用 CURL 和 REST 客户端测试 REST 服务。从编程水平上讲&＃xff0c;Jakarta Commons HttpClient 通常用于完成此测试&＃xff08;但这不在本文的讨论范围中&＃xff09;。您还可以使用名为RestTemplate 的 Spring REST 客户端。从概念上讲&＃xff0c;它与 Spring 中的其他模板类相似&＃xff0c;比如 JdbcTemplate 和JmsTemplate。

RestTemplate 还使用 HttpMessageConverter。您可以将对象类传入请求并使转换程序处理映射。

配置 RestTemplate

清单 10 显示了 RestTemplate 的配置。它还使用之前介绍的 3 个转换程序。

本文中的示例仅使用了一些可简化服务器之间通信的方法。RestTemplate支持其他方法&＃xff0c;包括&＃xff1a;

• exchange&＃xff1a;使用请求正文执行一些 HTTP 方法并获得响应。
• getForObject&＃xff1a;执行 HTTP GET 方法并将响应作为对象获得。
• postForObject&＃xff1a;使用特定请求正文执行 HTTP POST 方法。
• put&＃xff1a;使用特定请求正文执行 HTTP PUT 方法。
• delete&＃xff1a;执行 HTTP DELETE方法以获得特定 URI。

代码示例

下列代码示例帮助阐述如何使用 RestTemplate。参见 RestTemplate API&＃xff08;参见 参考资料&＃xff09;获得使用的 API 的详细说明。

清单 11 显示如何将头添加到请求中&＃xff0c;然后调用请求。使用 MarshallingHttpMessageConverter 您可以获得响应并将其转换为类型类。可以使用不同的媒体类型测试其他具象。

清单 12 显示了如何将新员工发布到服务器。服务器端服务 addEmp() 可接受媒体类型为 application/xml 和 application/json 的数据。

清单 13 显示了如何 PUT 修改的员工以更新旧员工。它还显示了可用作请求 URI 占位符&＃xff08;{id}&＃xff09;的功能。

清单 14 显示了如何 DELETE 现有员工。

回页首

结束语

在本篇文章中&＃xff0c;您学习了 Spring 3 中引入的 HttpMessageConverter。它提供了对多具象的客户端和服务器端支持。使用提供的 源代码&＃xff0c;您可以探索本文中的 HttpMessageConverter 实现和使用 “使用 Spring 3 构建 RESTful web 服务” 中的 ContentNegotiatingViewResolver 实现之间的差异。

回页首

下载

关于下载方法的信息

参考资料

学习

• 随附文章 “使用 Spring 3 来创建 RESTful Web Services”&＃xff08;developerWorks&＃xff0c;2010 年 7 月&＃xff09;介绍了构建 RESTful web 服务的 Spring 方式。
  
  
• 在 Wikipedia 上了解 REST 及其相关链接。
  
  
• 浏览 Spring MVC showcase 以很好地了解技术的作用。它包括一个示例项目&＃xff0c;以及支持的幻灯片演示和示范视频。
  
  
• 全面了解 Spring 3。
  
  
• 了解有关 RestTemplate API 的更多信息。
  
  
• 全面了解 JAXB Reference Implementation Project。
  
  
• 探索 ROME&＃xff0c;一个 Atom/RSS Java 实用工具集&＃xff0c;可与大多数联合格式一起在 Java 中使用。
  
  
• 了解有关 ATOM 的更多信息。
  
  
• 阅读 developerWorks 系列 “认识 Atom 发布协议&＃xff0c;第 1 部分: 使用 Atom 发布协议创建和编辑 Web 资源”&＃xff08;2006 年 10 月&＃xff09;获得协议概述及其基本操作和功能。
  
  
• 了解 Jackson&＃xff0c;快速开源 JSON 处理器。
  
  
• developerWorks Web development 专区&＃xff1a;通过专门关于 Web 技术的文章和教程&＃xff0c;扩展您在网站开发方面的技能。
  
  
• developerWorks Ajax 资源中心&＃xff1a;这是有关 Ajax 编程模型信息的一站式中心&＃xff0c;包括很多文档、教程、论坛、blog、wiki 和新闻。任何 Ajax 的新信息都能在这里找到。
  
  
• developerWorks Web 2.0 资源中心&＃xff0c;这是有关 Web 2.0 相关信息的一站式中心&＃xff0c;包括大量 Web 2.0 技术文章、教程、下载和相关技术资源。您还可以通过 Web 2.0 新手入门 栏目&＃xff0c;迅速了解 Web 2.0 的相关概念。
  
  

获得产品和技术

• 获取最新 Spring 发行版。
  
  
• 下载 Jackson。
  
  
• 下载 IBM 产品评估试用版软件 或 IBM SOA 人员沙箱 &＃xff0c;并开始使用来自 DB2®、Lotus®、Rational®、Tivoli® 和 WebSphere® 的应用程序开发工具和中间件产品。
  
  

讨论

• 现在就创建您的 developerWorks 社区 个人档案 并设置一个关于 OSGi 的 关注清单。连接到 developerWorks 社区 并保持连接。
  
  
• 找到 对 web 开发感兴趣的其他 developerWorks 成员。
  
  
• Web 开发人员&＃xff0c;请在 web 开发群组中分享您的经验和知识。
  
  
• 分享您的知识&＃xff1a;加入一个关注 web 主题的 developerWorks 群组。
  
  
• Roland Barcia 撰写的关于 Web 2.0 和中间件 的博客。
  
  
• 关注 developerWorks 成员 关于 web 主题的共享书签。
  
  
• 快速解答&＃xff1a;访问 Web 2.0 Apps 论坛。
  
  

关于作者