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注释对将成为 MVC 中控制器的类进行注释并处理 HTTP 请求。 - 使用
@RequestMapping注释对函数进行注释，该函数处理某些 HTTP 方法、URI 或 HTTP 头。此注释是 Spring REST 支持的关键。可以更改method参数以处理其他 HTTP 方法。例如：
@RequestMapping(method=RequestMethod.GET, value="/emps", headers="Accept=application/xml, application/json")
-
使用@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 ResponseEntitymethod(HttpEntity entity) {…} 参见 Spring 文档（参见 ) 获得可插入方法中的支持注释或对象的完整列表。
@Controller @RequestMapping @PathVariable其他有用的注释 多具象支持
使用不同 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
在配置中，注册了 3 个转换程序。MappingJacksonHttpMessageConverter 用于将对象转换为 JSON，反之亦然。此内置转换程序使用 Jackson 的 ObjectMapper 将 JSON 映射到 JavaBean，因此您必须将下列 Jackson JAR 文件添加到类路径。
org.codehaus.jackson.jarorg.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 employees = employeeDS.getAll(); EmployeeList list = 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
... ...
dw.spring3.rest.bean.Employee dw.spring3.rest.bean.EmployeeList
了解 JAXB 2 不能很好地支持 java.util.List<T> 到 XML 的映射很重要。常用实践是为对象集添加一个包装类。参见 “使用 Spring 3 构建 RESTful web 服务”（参见 ）或 源代码，了解此 JAXB 注释类的详细信息。
在处理请求的控制器中的方法如何？回顾一下 中的代码。发现在此处不需要添加任何代码一点也不奇怪。您只需要在 Accept 头中添加另一个支持的媒体类型，如下所示。
headers=”Accept=application/json, application/xml”
转换程序将对象正确地映射到请求的类型（JSON 或 XML）。清单 5 显示了请求 application/xml 具象的理想结果。
清单 5. getEmp() 和 getAllEmp() 的 XML 结果
Response for /rest/service/emp/1Response for /rest/service/emps huangyim@cn.ibm.com 1 Huang Yi Ming 2 huangyim@cn.ibm.com 1 Huang Yi Ming wudongf@cn.ibm.com 2 Wu Dong Fei
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
清单 7 显示了处理 ATOM 请求和源生成的代码。
清单 7. EmployeeController & AtomUtil 类中的 getEmpFeed()
@RequestMapping(method=RequestMethod.GET, value="/emps", headers="Accept=application/atom+xml")public @ResponseBody Feed getEmpFeed() { List employees = employeeDS.getAll(); return AtomUtil.employeeFeed(employees, jaxb2Mashaller);} AtomUtil.javapublic static Feed employeeFeed(List employees, Jaxb2Marshaller marshaller) { Feed feed = new Feed(); feed.setFeedType("atom_1.0"); feed.setTitle("Employee Atom Feed"); List entries = new ArrayList (); 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 contents = new ArrayList (); 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 输出
Employee Atom Feed Huang Yi Ming 1 huangyim@cn.ibm.com 1 Huang Yi Ming Wu Dong Fei 2 wudongf@cn.ibm.com 2 Wu Dong Fei
实现 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
本文中的示例仅使用了一些可简化服务器之间通信的方法。RestTemplate支持其他方法，包括：
exchange：使用请求正文执行一些 HTTP 方法并获得响应。getForObject：执行 HTTPGET方法并将响应作为对象获得。postForObject：使用特定请求正文执行 HTTPPOST方法。put：使用特定请求正文执行 HTTPPUT方法。delete：执行 HTTPDELETE方法以获得特定 URI。
代码示例
下列代码示例帮助阐述如何使用 RestTemplate。参见 RestTemplate API（参见 ）获得使用的 API 的详细说明。
清单 11 显示如何将头添加到请求中，然后调用请求。使用 MarshallingHttpMessageConverter 您可以获得响应并将其转换为类型类。可以使用不同的媒体类型测试其他具象。
清单 11. XML 具象请求
HttpHeaders headers = new HttpHeaders();headers.setContentType(MediaType.APPLICATION_XML);HttpEntityentity = new HttpEntity (headers);ResponseEntity 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");HttpEntityentity = new HttpEntity (newEmp);ResponseEntity 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");HttpEntityentity = new HttpEntity (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 实现之间的差异。