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

HttpMessageConverter

RestTemplate

HttpMessageConverter

简介

ContentNegotiatingViewResolver

HttpMessageConverter

RestTemplate

HttpMessageConverter

Spring MVC 中的 REST 支持

@Controller

@Controller

@RequestMapping

@RequestMapping

method

@RequestMapping(method=RequestMethod.GET, value="/emps",
headers="Accept=application/xml, application/json")

@PathVariable

使用 @PathVariable

@RequestMapping(method=RequestMethod.GET, value="/emp/{id}")
public ModelAndView getEmployee(@PathVariable String id) { … }

其他有用的注释

使用 @RequestParam

@RequestHeader

@RequestBody

@ResponseBody

HttpEntity<T>

ResponseEntity<T>

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

多具象支持

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

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

还有另一种方式可生成多具象 — 将 
HttpMessageConverter
 和 [code]c@ResponseBody

HttpMessageConverter

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

表 1. HttpMessageConverter 示例

ObjectMapper

构建 RESTful web 服务

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

首先，您必须配置 
HttpMessageConverter
。要生成多个具象，自定义几个 [code]HttpMessageConverter

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="marshallingConverter" />
<ref bean="atomConverter"  />
<ref bean="jsonConverter" />
</list>
</property>
</bean>

在配置中，注册了 3 个转换程序。
MappingJacksonHttpMessageConverter
 用于将对象转换为 JSON，反之亦然。此内置转换程序使用 Jackson 的 [code]ObjectMapper

org.codehaus.jackson.jar

org.codehaus.jackson.mapper.jar

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

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

@RequestMapping(method=RequestMethod.GET, value="/emp/{id}", headers="Accept=application/xml, 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/xml, application/json")
public @ResponseBody EmployeeList getAllEmp() {
List<Employee> employees = employeeDS.getAll();
EmployeeList list = new EmployeeList(employees);
return list;
}

@ResponseBody

Employee

EmployeeList

MappingJacksonHttpMessageConverter

使用 
HttpMessageConverter
 和 [code]@ResponseBody

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

AtomUtil.java
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()

getAllEmp()

Accept

使用 
employeeFeed()
 方法，您可以将 [code]Employee

<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 显示了 [code]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()

HttpMessageConverter

RestTemplate

使用 RestTemplate 与 REST 服务进行通信

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

JmsTemplate

RestTemplate

HttpMessageConverter

配置 RestTemplate

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

清单 10. 配置 RestTemplate

　　<!-- Client -->
<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

getForObject

GET

postForObject

POST

put

PUT

delete

DELETE

代码示例

下列代码示例帮助阐述如何使用 
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
。它提供了对多具象的客户端和服务器端支持。使用提供的 源代码，您可以探索本文中的 [code]HttpMessageConverter

ContentNegotiatingViewResolver