使用Spring MVC編寫RESTful Controller

1、Spring對REST的支持

Spring3（這里討論Spring3.2+）對Spring MVC的一些增強功能為REST提供了良好的支持。Spring對開發REST資源提供以下支持：

1. 操作方式：控制器可以處理所有的HTTP方法，包含4個主要的REST方法：GET、PUT、DELETE以及POST。Spring的表單綁定JSP標簽庫的<form:form>標簽以及新的HiddenHttpMethodFilter，使得通過HTML表單提交的PUT和DELETE請求成為可能
2. 資源標識：新的@PathVariable注解使得控制器能夠處理參數化的URL
3. 資源表述方法1：通過使用Spring的視圖解析器，資源可以以各種形式進行表述，包括XML、JSON、Atom和RSS（）。使用新的ContentNegotiatingViewResolver來選擇最合適客戶端的表述
4. 資源表述方法2：通過使用@ResponseBody注解和各種HttpMethodConverter實現來達到。@RequestBody注解記憶HttpMethodConverter實現可以將傳入的HTTP數據轉化為傳入控制器方法的Java對象
5. REST客戶端：RestTemplate簡化了客戶端對REST資源的使用

 2、參數化URL

Spring3.0中引入了新的@PathVariable注解，幫助Controller使用面向資源的方式處理請求。如：

@Controller
@RequestMapping(value="/spitters")
public class SpittleController{
    private SpitterService spitterService;
    ...
    @RequestMapping(value="/{id}", method= RequestMethod.PUT)
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void putSpittle(@PathVariable("id")) long id,
                           @Valid Spittle spittle)
    {
        spitterService.saveSpittle(spittle);
    }
}

3、協商資源表述

“協商資源表述”即確定一個HTTP請求所需要返回的資源格式，HTML、XML還是JSON等。按優先級，Spring MVC依次通過以下三個條件確定客戶端需要什么類型的內容表述：

1. URL路徑上添加擴展名，如 http://myserver/myapp/accounts/list.html 或者 http://myserver/myapp/accounts/list.xls。
2. URL參數，如 http://myserver/myapp/accounts/list?format=xls，參數名默認為“format”，但也可以更改。
3. 通過HTTP請求的Accept頭部信息確定返回資源格式，但由於客戶端的處理不同，這個方法並不太可靠。

JAF（JavaBeans Activation Framework）可提供由擴展名（或URL參數）到資源格式的自動映射機制（如json->"application/json"），這時classpath下必須有activation.jar包。

Spring MVC通過ContentNegotiationManager來進行資源協商，一般配置如下：

<bean id="contentNegotiationManager"
      class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean">
<property name="favorPathExtension" value="false" />
<property name="favorParameter" value="true" />
<property name="parameterName" value="mediaType" />
<property name="ignoreAcceptHeader" value="true"/>
<property name="useJaf" value="false"/>
<property name="defaultContentType" value="application/json" />

<property name="mediaTypes">
    <map>
        <entry key="json" value="application/json" />
        <entry key="xml" value="application/xml" />
    </map>
</property>
</bean>

以上配置表示：不使用路徑擴展名方式，也不使用Accept頭信息方式，僅使用URL參數方式確定資源類型，URL參數名使用“mediaType”代替默認的“format”，不使用JAF而是自行定義URL參數到資源格式的映射，這里只定義了JSON和XML。

4、表述資源（一）

Spring MVC通過兩種方式將Java表述形式的資源轉化為發送給客戶端的表述形式：

• 基於視圖渲染進行協商（@ContentNegotiatingViewResolver）
• HTTP消息轉換器（HttpMessageConverters）

首先是第一種方式，使用HttpMessageConverters表述資源。當ContentNegotiationManager配置如下，且類路徑下包含JAXB和Jackson包時，Spring MVC將自動匹配使用哪種HttpMessageCoverter。

ContentNegotiationManager配置：

<!-- enable the "produces" annotation of "RequestMapping" -->
<mvc:annotation-driven content-negotiation-manager="contentNegotiationManager" />

<!-- Simple strategy: only path extension is taken into account -->
<bean id="cnManager"
      class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean">
<property name="favorPathExtension" value="true"/>
<property name="ignoreAcceptHeader" value="true" />
<property name="defaultContentType" value="text/html" />
<property name="useJaf" value="false"/>

<property name="mediaTypes">
    <map>
        <entry key="html" value="text/html" />
        <entry key="json" value="application/json" />
        <entry key="xml" value="application/xml" />
    </map>
</property>
</bean>

Controller:

@Controller
class AccountController {
    // RESTful method, use MappingJacksonHttpMessageConverter and Jaxb2RootElementHttpMessageConverter automatically
    //accounts.json -> application/json
    //accounts.xml -> text/xml
    @RequestMapping(value="/accounts", produces={"application/xml", "application/json"})
    @ResponseStatus(HttpStatus.OK)
    public @ResponseBody List<Account> listWithMarshalling(Principal principal) {
        return accountManager.getAccounts(principal);
    }

    // View-based method
    //accounts.html -> text/html
    //accounts.others -> text/html
    @RequestMapping("/accounts")
    public String listWithView(Model model, Principal principal) {
        // Call RESTful method to avoid repeating account lookup logic
        model.addAttribute( listWithMarshalling(principal) );

        // Return the view to use for rendering the response
        return ¨accounts/list¨;
    }
}

 使用 JAXB 和 Jackson時，需要在account類上添加annotation：

/**
 * Represents an account for a member of a financial institution. An account has
 * zero or more {@link Transaction}s and belongs to a {@link Customer}. An aggregate entity.
 */
@Entity
@Table(name = "T_ACCOUNT")
@XmlRootElement
public class Account {

    // data-members omitted ...

    public Account(Customer owner, String number, String type) {
        this.owner = owner;
        this.number = number;
        this.type = type;
    }

    /**
     * Returns the number used to uniquely identify this account.
     */
    @XmlAttribute
    public String getNumber() {
        return number;
    }

    /**
     * Get the account type.
     *
     * @return One of "CREDIT", "SAVINGS", "CHECK".
     */
    @XmlAttribute
    public String getType() {
        return type;
    }

    /**
     * Get the credit-card, if any, associated with this account.
     *
     * @return The credit-card number or null if there isn't one.
     */
    @XmlAttribute
    public String getCreditCardNumber() {
        return StringUtils.hasText(creditCardNumber) ? creditCardNumber : null;
    }

    /**
     * Get the balance of this account in local currency.
     *
     * @return Current account balance.
     */
    @XmlAttribute
    public MonetaryAmount getBalance() {
        return balance;
    }


    /**
     * Returns a single account transaction. Callers should not attempt to hold
     * on or modify the returned object. This method should only be used
     * transitively; for example, called to facilitate reporting or testing.
     *
     * @param name
     *            the name of the transaction account e.g "Fred Smith"
     * @return the beneficiary object
     */
    @XmlElement   // Make these a nested <transactions> element
    public Set<Transaction> getTransactions() {
        return transactions;
    }

    // Setters and other methods ...

}

5、表述資源（二） 

第二種方式，使用視圖渲染器（View Resolution）。使用ContentNegotiatingViewResolver和ContentNegotiationManager進行配置：

<!-- View resolver that delegates to other view resolvers based on the content type -->
<bean class="org.springframework.web.servlet.view.ContentNegotiatingViewResolver">
<!-- All configuration is now done by the manager - since Spring V3.2 -->
    <property name="contentNegotiationManager" ref="cnManager"/>
</bean>

<!-- Setup a simple strategy -->
<bean id="cnManager" class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean">
    <property name="ignoreAcceptHeader" value="true"/>
    <property name="defaultContentType" value="text/html" />
</bean>

使用以上配置Spring將根據約定自動查找ViewResolvers，並渲染資源。也可顯式配置ViewResolvers：

<bean class="org.springframework.web.servlet.view.ContentNegotiatingViewResolver">
<property name="contentNegotiationManager" ref="cnManager"/>

<!-- Define the view resolvers explicitly -->
<property name="viewResolvers">
    <list>
        <bean class="org.springframework.web.servlet.view.XmlViewResolver">
            <property name="location" value="spreadsheet-views.xml"/>
        </bean>

        <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
            <property name="prefix" value="WEB-INF/views"/>
            <property name="suffix" value=".jsp"/>
        </bean>
    </list>
</property>
</bean>

這樣Controller就可以去掉@ResponseBody的Method，只寫一個Method了。

6、參考

《Spring in Action 第三版》

Content Negotiation using Spring MVC

Content Negotiation using Views