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