使用 Spring 3 MVC HttpMessageConverter 功能构建 RESTful web 服务

原文地址：http://www.ibm.com/developerworks/cn/web/wa-restful/

简介： Spring，构建 Java 平台和 Enterprise Edition (Java EE) 应用程序的著名框架，现在在其模型-视图-控制器（Model-View-Controller ，MVC）层支持具象状态传输 (REST)。RESTful web 服务根据客户端请求生成多个具象（representations）很重要。在本篇文章中，学习使用 HttpMessageConverter 生成多个具象。代码示例展示如何使用RestTemplate 和 HttpMessageConverter 与服务进行通信。此外，还将学习如何使用 Spring API 和注释构建 RESTful web 服务，生成常见具象，比如 ATOM Feed、XML 和 JavaScript Object Notation (JSON)。

简介

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

Spring MVC 中的 REST 支持

本部分提供了支持 RESTful web 服务的主要 Spring 功能（或注释）的概述。

@Controller
使用 @Controller 注释对将成为 MVC 中控制器的类进行注释并处理 HTTP 请求。
@RequestMapping
使用 @RequestMapping 注释对函数进行注释，该函数处理某些 HTTP 方法、URI 或 HTTP 头。此注释是 Spring REST 支持的关键。可以更改 method 参数以处理其他 HTTP 方法。

例如：

@RequestMapping(method=RequestMethod.GET, value="/emps",
headers="Accept=application/xml, application/json")
@PathVariable
使用 @PathVariable 注释可将 URI 中的路径变量作为参数插入。

例如：

@RequestMapping(method=RequestMethod.GET, value="/emp/{id}")
public ModelAndView getEmployee(@PathVariable String id) { … }
其他有用的注释
使用 @RequestParam 将 URL 参数插入方法中。

使用 @RequestHeader 将某一 HTTP 头插入方法中。

使用 @RequestBody 将 HTTP 请求正文插入方法中。

使用 @ResponseBody 将内容或对象作为 HTTP 响应正文返回。

使用 HttpEntity<T> 将它自动插入方法中，如果将它作为参数提供。

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

例如：

public @ResponseBody Employee getEmployeeBy(@RequestParam("name")
String name, @RequestHeader("Accept") String accept, @RequestBody String body) {…}
public ResponseEntity<String> method(HttpEntity<String> entity) {…}

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

多具象支持

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

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

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

 

回页首

HttpMessageConverter

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

表 1. HttpMessageConverter 示例

使用...... 您可以......
StringHttpMessageConverter 从请求和响应读取/编写字符串。默认情况下，它支持媒体类型 text/* 并使用文本/无格式内容类型编写。
FormHttpMessageConverter 从请求和响应读取/编写表单数据。默认情况下，它读取媒体类型 application/x-www-form-urlencoded 并将数据写入 MultiValueMap<String,String>。
MarshallingHttpMessageConverter 使用 Spring 的 marshaller/un-marshaller 读取/编写 XML 数据。它转换媒体类型为 application/xml 的数据。
MappingJacksonHttpMessageConverter 使用 Jackson 的 ObjectMapper 读取/编写 JSON 数据。它转换媒体类型为 application/json 的数据。
AtomFeedHttpMessageConverter 使用 ROME 的 Feed API 读取/编写 ATOM 源。它转换媒体类型为 application/atom+xml 的数据。
RssChannelHttpMessageConverter 使用 ROME 的 feed API 读取/编写 RSS 源。它转换媒体类型为 application/rss+xml 的数据。

 

回页首

构建 RESTful web 服务

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

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

JSON

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

清单 1. 配置 rest-servlet.xml 中的 HttpMessageConverter

<bean class="org.springframework.web.servlet.mvc.annotation
.AnnotationMethodHandlerAdapter">
   <property name="messageConverters">
       <list>
           <ref bean="jsonConverter" />
   <ref bean="marshallingConverter" />
   <ref bean="atomConverter" />
       </list>
   </property>
</bean>

<bean id="jsonConverter"
            class="org.springframework.http.converter.json
.MappingJacksonHttpMessageConverter">
   <property name="supportedMediaTypes" value="application/json" />
</bean>

 

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

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

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

清单 2. 处理在 EmployeeController 中定义的 JSON 请求

@RequestMapping(method=RequestMethod.GET, value="/emp/{id}",
		headers="Accept=application/json")
public @ResponseBody Employee getEmp(@PathVariable String id) {
Employee e = employeeDS.get(Long.parseLong(id));
return e;
}

@RequestMapping(method=RequestMethod.GET, value="/emps",
		headers="Accept=application/json")
public @ResponseBody EmployeeListinggetAllEmp() {
List<Employee> employees = employeeDS.getAll();
EmployeeListinglist = new EmployeeList(employees);
return list;
}

 

@ResponseBody 注释用于将返回对象（Employee 或 EmployeeList）变为响应的正文内容，将使用MappingJacksonHttpMessageConverter 将其映射到 JSON。

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

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

清单 3. getEmp() 和 getAllEmp() 的 JSON 结果


Response for /rest/service/emp/1
{"id":1,"name":"Huang Yi Ming","email":"huangyim@cn.ibm.com"}

Response for /rest/service/emps
{"count":2,
"employees":[
{"id":1,"name":"Huang Yi Ming","email":"huangyim@cn.ibm.com"},
{"id":2,"name":"Wu Dong Fei","email":"wudongf@cn.ibm.com"}
]}

 

XML

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

清单 4. 配置 MarshallingHttpMessageConverter

<bean id="marshallingConverter"
class="org.springframework.http.converter.xml
		.MarshallingHttpMessageConverter">
<constructor-arg ref="jaxbMarshaller" />
    <property name="supportedMediaTypes" value="application/xml"/>
      </bean>

      <bean id="jaxbMarshaller"
      class="org.springframework.oxm.jaxb.Jaxb2Marshaller">

    <property name="classesToBeBound">
	  <list>
	    <value>dw.spring3.rest.bean.Employee</value>
	    <value>dw.spring3.rest.bean.EmployeeList</value>
	  </list>
    </property>

</bean>

 

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

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

headers=”Accept=application/json, application/xml”

 

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

清单 5. getEmp() 和 getAllEmp() 的 XML 结果

Response for /rest/service/emp/1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <employee>
   <email>huangyim@cn.ibm.com</email>
   <id>1</id>
   <name>Huang Yi Ming</name>
 </employee>
Response for /rest/service/emps
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <employees>
  <count>2</count>
    <employee>
      <email>huangyim@cn.ibm.com</email>
      <id>1</id>
      <name>Huang Yi Ming</name>
    </employee>
    <employee>
      <email>wudongf@cn.ibm.com</email>
      <id>2</id><name>Wu Dong Fei</name>
    </employee>
 </employees>

 

ATOM 源

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

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

清单 6. 配置 AtomFeedHttpMessageConverter

<bean id="atomConverter"
class="org.springframework.http.converter.feed
		.AtomFeedHttpMessageConverter">
<property name="supportedMediaTypes" value="application/atom+xml" />
</bean>

 

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

清单 7. EmployeeController & AtomUtil 类中的 getEmpFeed() 

@RequestMapping(method=RequestMethod.GET, value="/emps",
		headers="Accept=application/atom+xml")
public @ResponseBody Feed getEmpFeed() {
	List<Employee> employees = employeeDS.getAll();
	return AtomUtil.employeeFeed(employees, jaxb2Mashaller);
}

public static Feed employeeFeed(
	List<Employee> employees, Jaxb2Marshaller marshaller) {
Feed feed = new Feed();
feed.setFeedType("atom_1.0");
feed.setTitle("Employee Atom Feed");

List<Entry> entries = new ArrayList<Entry>();
for(Employee e : employees) {
	StreamResult result = new StreamResult(
	new ByteArrayOutputStream());
	marshaller.marshal(e, result);
	String xml = result.getOutputStream().toString();

	Entry entry = new Entry();
	entry.setId(Long.valueOf(e.getId()).toString());
	entry.setTitle(e.getName());
	Content content = new Content();
	content.setType(Content.XML);
	content.setValue(xml);

	List<Content> contents = new ArrayList<Content>();
	contents.add(content);
	entry.setContents(contents);
	entries.add(entry);
}
feed.setEntries(entries);
return feed;
}

 

在上述代码中，注意：

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

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

清单 8. 请求 application/atom+xml 时的 /rest/service/emps 输出

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Employee Atom Feed</title>

 <entry>
    <title>Huang Yi Ming</title>
    <id>1</id>
  <content type="xml">
    <employee>
            <email>huangyim@cn.ibm.com</email>
            <id>1</id>
            <name>Huang Yi Ming</name>
    </employee>
  </content>
</entry>

  <entry>
    <title>Wu Dong Fei</title>
    <id>2</id>
  <content type="xml">
    <employee>
            <email>wudongf@cn.ibm.com</email>
            <id>2</id>
            <name>Wu Dong Fei</name>
     </employee>
   </content>
 </entry>

</feed>

 

实现 POST、PUT 和 DELETE

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

清单 9. EmployeeController 中的 POST、PUT 和 DELETE 方法

@RequestMapping(method=RequestMethod.POST, value="/emp")
public @ResponseBody Employee addEmp(@RequestBody Employee e) {
employeeDS.add(e);
return e;
}

@RequestMapping(method=RequestMethod.PUT, value="/emp/{id}")
public @ResponseBody Employee updateEmp(
	@RequestBody Employee e, @PathVariable String id) {
employeeDS.update(e);
return e;
}

@RequestMapping(method=RequestMethod.DELETE, value="/emp/{id}")
public @ResponseBody void removeEmp(@PathVariable String id) {
employeeDS.remove(Long.parseLong(id));
}

 

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

 

回页首

使用 RestTemplate 与 REST 服务进行通信

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

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

配置 RestTemplate

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

清单 10. 配置 RestTemplate

<bean id="restTemplate"
class="org.springframework.web.client.RestTemplate">
<property name="messageConverters">
	<list>
	<ref bean="marshallingConverter" />
	<ref bean="atomConverter"  />
	<ref bean="jsonConverter" />
	</list>
</property>
</bean>

 

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

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

代码示例

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

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

清单 11. XML 具象请求

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_XML);
HttpEntity<String> entity = new HttpEntity<String>(headers);
ResponseEntity<EmployeeList> response = restTemplate.exchange(
"http://localhost:8080/rest/service/emps",
HttpMethod.GET, entity, EmployeeList.class);
EmployeeListingemployees = response.getBody();
// handle the employees

 

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

清单 12. 发布新员工

Employee newEmp = new Employee(99, "guest", "guest@ibm.com");
HttpEntity<Employee> entity = new HttpEntity<Employee>(newEmp);
ResponseEntity<Employee> response = restTemplate.postForEntity(
"http://localhost:8080/rest/service/emp", entity, Employee.class);
Employee e = response.getBody();
// handle the employee

 

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

清单 13. PUT 以更新员工

Employee newEmp = new Employee(99, "guest99", "guest99@ibm.com");
HttpEntity<Employee> entity = new HttpEntity<Employee>(newEmp);
restTemplate.put(
	"http://localhost:8080/rest/service/emp/{id}", entity, "99");

 

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

清单 14. DELETE 现有员工

restTemplate.delete(
	"http://localhost:8080/rest/service/emp/{id}", "99");

 

 

回页首

结束语

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

 

 

回页首

下载

描述 名字 大小 下载方法
文章源代码 src_code.zip 11KB HTTP

关于下载方法的信息

 

参考资料

学习

获得产品和技术

讨论

时间： 2025-01-30 04:05:33

使用 Spring 3 MVC HttpMessageConverter 功能构建 RESTful web 服务的相关文章

使用Spring Boot构建RESTful Web服务以访问存储于Aerospike集群

Spring Boot是对Spring快速入门的强大工具.Spring Boot能够帮助你很容易地构建基于Spring的应 用. Aerospike是分布式和可复制的内存数据库,不管使用DRAM还是原生的flash/SSD,Aerospike都进行 了优化. Aerospike具有高可靠性并且遵循ACID.开发人员能够在不停止数据库服务的情况下,很快地将 数据库集群从两个节点扩展到二十个节点. 你所要构建的是什么 本文将会引领你使用Spring Boot创建一个简单的RESTful Web服务.

使用Jersey和Apache Tomcat构建RESTful Web服务

RESTful Web 服务简介 REST 在 2000 年由 Roy Fielding 在博士论 文中提出,他是 HTTP 规范 1.0 和 1.1 版的首席作者之一. REST 中最 重要的概念是资源(resources),使用全球 ID(通常使用 URI)标识.客户端 应用程序使用 HTTP 方法(GET/ POST/ PUT/ DELETE)操作资源或资源集. RESTful Web 服务是使用 HTTP 和 REST 原理实现的 Web 服务.通常,RESTful Web 服务应该定义

用 Jersey 2 和 Spring 4 构建 RESTful web service

本文介绍了如何通过 Jersey 框架优美的在 Java 实现了 REST 的 API.CRUD 的 操作存储在 MySQL 中 1. 示例 1.1 为什么 Spring 可以对于 REST 有自己的实现(见 https://spring.io/guides/tutorials/rest/). 但本文展示的是用 "官方" 的 方法来实现 REST ,即使用 Jersey. 1.2 它是做什么的? 管理 资源. REST API 将允许创建.检索.更新和删除这样的资源. 1.3 架构及技

使用GWT和RESTful Web服务构建动态的组织树

简介 最近几年,Web 应用程序开发的潮流是创建富 Internet 应用程 序,其中大多数是使用 Asynchronous JavaScript + XML (Ajax) 实现的.但是 ,由于编写 JavaScript 代码比较复杂,这种方法并不容易,尤其是很难构建大 型 Web 应用程序.因此出现了 GWT:它让我们能够使用 Java 编程而不是 Ajax 构建功能丰富的响应性的 Web 界面.GWT 还提供 Java 开发的所有优势,比如 出色的 IDE 支持和高级调试功能.GWT 可以显

使用Apache Wink、Eclipse和Maven开发RESTful Web服务

简介:Apache Wink 是 Java API for RESTful Web Services (JAX-RS) 规范的一个开源实现 .了解如何使用 Apache Wink.Eclipse IDE 以及 Maven 项目管理工具开发.部署和运行 RESTful Web 服务. Apache Wink 是一个促进创建和使用 REST Web 服务的 Apache 孵化器项目.通过 REST Web 服务,客户机和服务之间的交互局限于一组预定义的操作,客户机和服务器之间的交互的复杂性限制 为客

使用 Eclipse 在 Google App Engine 上创建 mashup，第 3 部分: 使用 RESTful Web 服务

使用社会网络可以更轻松地获取并聚合数据,从而创建富有革新精神的新 Web 应用程序.但是,仍然必须处理创建可伸缩 Web 应用程序的所有常见问题.现在,使用 Google App Engine (GAE) 也可以简化工作.使用 GAE,可以不必考虑管理应用服务器池的所有事务,而是集中精力创建优秀的 mashup.本文是共分三部分的系列文章 "使用 Eclipse 在 Google App Engine 上创建 mashup" 的最后一部分,在本文中,将利用并进一步增强在前两部分中构建的

分享一个Android和java调用RESTful Web服务的利器Resting

分享一个Android和java调用RESTful Web服务的利器Resting   当我们调用Web服务,往往是最终目标是取HTTP响应,将其转化为将在应用中呈现的值对象.Resting可以用来实现这一功能.Resting,在Java的一个轻量级的REST框架,可用于调用一个RESTful Web服务,并转换成响应来自客户端应用程序定制的Java对象.由于它的简单,resting是适合Android等手持设备.   resting目标•暴露简单的get(),post(),put()和dele

java-使用http post如何传递多参数到restful web服务？

问题描述 使用http post如何传递多参数到restful web服务? 我创建了俩个数组参数和Objects数组,我想传递它们,我可以用下面的方法吗? @POST @Path("Test3") @Produces("text/plain") @Consumes({"application/json"}) public String Test3(String[] id1,String[] id2 ,Object [] oo) { String

如何创建RESTFul Web服务

想写这篇文章很久了,这是个大话题,不是一时半会就能说清楚的. 所以准备花个一星期整理资料,把思路理清楚,然后再在Team里做个sharing:) 其实RESTFul是架构风格,并不是实现规范,也不一定非要用HTTP,但鉴于HTTP的普世性和 SOA的实现基本都基于HTTP实现. 这句话只对了前一半, 实际上REST和HTTP是息息相关的,是一种Web架构,WWW是世界最大型的分布式应用,而其实现就是基于REST的web架构的设计标准,REST架构的提出者(Roy T. Fielding 2000