Dubbo3 開發(fā) REST 應用

在 Dubbo 中開發(fā) REST 風格的遠程調用

作者：沈理

文檔版權：Apache 2.0許可證 署名-禁止演繹

本文篇幅較長，因為REST本身涉及面較多。另外，本文參照 Spring 等的文檔風格，不僅僅局限于框架用法的闡述，同時也努力呈現(xiàn)框架的設計理念和優(yōu)良應用的架構思想。 對于想粗略了解 dubbo 和 REST 的人，只需瀏覽 概述 至 標準Java REST API：JAX-RS簡介 幾節(jié)即可。

目錄

• 概述
• REST的優(yōu)點
• 應用場景
• 快速入門
• 標準Java REST API：JAX-RS簡介
• REST服務提供端詳解HTTP POST/GET的實現(xiàn)Annotation放在接口類還是實現(xiàn)類JSON、XML等多數(shù)據(jù)格式的支持中文字符支持XML數(shù)據(jù)格式的額外要求定制序列化配置REST Server的實現(xiàn)獲取上下文（Context）信息配置端口號和Context Path配置線程數(shù)和IO線程數(shù)配置長連接配置最大的HTTP連接數(shù)配置每個消費端的超時時間和HTTP連接數(shù)GZIP數(shù)據(jù)壓縮用Annotation取代部分Spring XML配置添加自定義的Filter、Interceptor等添加自定義的Exception處理配置HTTP日志輸出輸入?yún)?shù)的校驗是否應該透明發(fā)布REST服務Dubbo的REST提供端在被調用時使用header
• REST服務消費端詳解場景1：非dubbo的消費端調用dubbo的REST服務場景2：dubbo消費端調用dubbo的REST服務場景3：dubbo的消費端調用非dubbo的REST服務Dubbo的消費端在調用REST服務時配置自定義header
• Dubbo中JAX-RS的限制
• REST常見問題解答（REST FAQ）Dubbo REST的服務能和Dubbo注冊中心、監(jiān)控中心集成嗎？Dubbo REST中如何實現(xiàn)負載均衡和容錯（failover）？JAX-RS中重載的方法能夠映射到同一URL地址嗎？JAX-RS中作POST的方法能夠接收多個參數(shù)嗎？
• Dubbo當前體系可能的不足之處（與REST相關的）RpcContext的侵入性Protocol配置的局限性XML命名不符合spring規(guī)范
• REST最佳實踐
• 性能基準測試測試環(huán)境測試腳本測試結果
• 擴展討論REST與Thrift、Protobuf等的對比REST與傳統(tǒng)WebServices的對比JAX-RS與Spring MVC的對比
• 未來

概述

dubbo支持多種遠程調用方式，例如dubbo RPC（二進制序列化 + tcp協(xié)議）、http invoker（二進制序列化 + http協(xié)議，至少在開源版本沒發(fā)現(xiàn)對文本序列化的支持）、hessian（二進制序列化 + http協(xié)議）、WebServices （文本序列化 + http協(xié)議）等等，但缺乏對當今特別流行的REST風格遠程調用（文本序列化 + http協(xié)議）的支持。

有鑒于此，我們基于標準的Java REST API——JAX-RS 2.0（Java API for RESTful Web Services的簡寫），為dubbo提供了接近透明的REST調用支持。由于完全兼容Java標準API，所以為dubbo開發(fā)的所有REST服務，未來脫離dubbo或者任何特定的REST底層實現(xiàn)一般也可以正常運行。

特別值得指出的是，我們并不需要完全嚴格遵守REST的原始定義和架構風格。即使著名的Twitter REST API也會根據(jù)情況做適度調整，而不是機械的遵守原始的REST風格。

附注：我們將這個功能稱之為REST風格的遠程調用，即RESTful Remoting（抽象的遠程處理或者調用），而不是叫RESTful RPC（具體的遠程“過程”調用），是因為REST和RPC本身可以被認為是兩種不同的風格。在dubbo的REST實現(xiàn)中，可以說有兩個面向，其一是提供或消費正常的REST服務，其二是將REST作為dubbo RPC體系中一種協(xié)議實現(xiàn)，而RESTful Remoting同時涵蓋了這兩個面向。

REST的優(yōu)點

以下摘自維基百科：

• 可更高效利用緩存來提高響應速度
• 通訊本身的無狀態(tài)性可以讓不同的服務器的處理一系列請求中的不同請求，提高服務器的擴展性
• 瀏覽器即可作為客戶端，簡化軟件需求
• 相對于其他疊加在HTTP協(xié)議之上的機制，REST的軟件依賴性更小
• 不需要額外的資源發(fā)現(xiàn)機制
• 在軟件技術演進中的長期的兼容性更好

這里我還想特別補充REST的顯著優(yōu)點：基于簡單的文本格式消息和通用的HTTP協(xié)議，使它具備極廣的適用性，幾乎所有語言和平臺都對它提供支持，同時其學習和使用的門檻也較低。

應用場景

正是由于REST在適用性方面的優(yōu)點，所以在dubbo中支持REST，可以為當今多數(shù)主流的遠程調用場景都帶來（顯著）好處：

1. 顯著簡化企業(yè)內部的異構系統(tǒng)之間的（跨語言）調用。此處主要針對這種場景：dubbo的系統(tǒng)做服務提供端，其他語言的系統(tǒng)（也包括某些不基于dubbo的java系統(tǒng)）做服務消費端，兩者通過HTTP和文本消息進行通信。即使相比Thrift、ProtoBuf等二進制跨語言調用方案，REST也有自己獨特的優(yōu)勢（詳見后面討論）
2. 顯著簡化對外Open API（開放平臺）的開發(fā)。既可以用dubbo來開發(fā)專門的Open API應用，也可以將原內部使用的dubbo service直接“透明”發(fā)布為對外的Open REST API（當然dubbo本身未來最好可以較透明的提供諸如權限控制、頻次控制、計費等諸多功能）
3. 顯著簡化手機（平板）APP或者PC桌面客戶端開發(fā)。類似于2，既可以用dubbo來開發(fā)專門針對無線或者桌面的服務器端，也可以將原內部使用的dubbo service直接”透明“的暴露給手機APP或桌面程序。當然在有些項目中，手機或桌面程序也可以直接訪問以上場景2中所述的Open API。
4. 顯著簡化瀏覽器AJAX應用的開發(fā)。類似于2，既可以用dubbo來開發(fā)專門的AJAX服務器端，也可以將原內部使用的dubbo service直接”透明“的暴露給瀏覽器中JavaScript。當然，很多AJAX應用更適合與web框架協(xié)同工作，所以直接訪問dubbo service在很多web項目中未必是一種非常優(yōu)雅的架構。
5. 為企業(yè)內部的dubbo系統(tǒng)之間（即服務提供端和消費端都是基于dubbo的系統(tǒng)）提供一種基于文本的、易讀的遠程調用方式。
6. 一定程度簡化dubbo系統(tǒng)對其它異構系統(tǒng)的調用?？梢杂妙愃芼ubbo的簡便方式“透明”的調用非dubbo系統(tǒng)提供的REST服務（不管服務提供端是在企業(yè)內部還是外部）

需要指出的是，我認為1～3是dubbo的REST調用最有價值的三種應用場景，并且我們?yōu)閐ubbo添加REST調用，其最主要到目的也是面向服務的提供端，即開發(fā)REST服務來提供給非dubbo的（異構）消費端。

歸納起來，所有應用場景如下圖所示： 

借用Java過去最流行的宣傳語，為dubbo添加REST調用后，可以實現(xiàn)服務的”一次編寫，到處訪問“，理論上可以面向全世界開放，從而真正實現(xiàn)比較理想化的面向服務架構（SOA）。

當然，傳統(tǒng)的WebServices（WSDL/SOAP）也基本同樣能滿足以上場景（除了場景4）的要求（甚至還能滿足那些需要企業(yè)級特性的場景），但由于其復雜性等問題，現(xiàn)在已經越來越少被實際采用了。

快速入門

在dubbo中開發(fā)一個REST風格的服務會比較簡單，下面以一個注冊用戶的簡單服務為例說明。

這個服務要實現(xiàn)的功能是提供如下URL（注：這個URL不是完全符合REST的風格，但是更簡單實用）：

http://localhost:8080/users/register

而任何客戶端都可以將包含用戶信息的JSON字符串POST到以上URL來完成用戶注冊。

首先，開發(fā)服務的接口：

public interface UserService {    
   void registerUser(User user);
}

然后，開發(fā)服務的實現(xiàn)：

@Path("users")
public class UserServiceImpl implements UserService {
       
    @POST
    @Path("register")
    @Consumes({MediaType.APPLICATION_JSON})
    public void registerUser(User user) {
        // save the user...
    }
}

上面的服務實現(xiàn)代碼非常簡單，但是由于REST服務是要被發(fā)布到特定HTTP URL，供任意語言客戶端甚至瀏覽器來訪問，所以這里要額外添加了幾個JAX-RS的標準annotation來做相關的配置：

@Path(“users”)：指定訪問UserService的URL相對路徑是/users，即http://localhost:8080/users

@Path(“register”)：指定訪問registerUser()方法的URL相對路徑是/register，再結合上一個@Path為UserService指定的路徑，則調用UserService.register()的完整路徑為http://localhost:8080/users/register

@POST：指定訪問registerUser()用HTTP POST方法

@Consumes({MediaType.APPLICATION_JSON})：指定registerUser()接收JSON格式的數(shù)據(jù)。REST框架會自動將JSON數(shù)據(jù)反序列化為User對象

最后，在spring配置文件中添加此服務，即完成所有服務開發(fā)工作：

<!-- 用rest協(xié)議在8080端口暴露服務 -->
<dubbo:protocol name="rest" port="8080"/>

<!-- 聲明需要暴露的服務接口 -->
<dubbo:service interface="xxx.UserService" ref="userService"/>

<!-- 和本地bean一樣實現(xiàn)服務 -->
<bean id="userService" class="xxx.UserServiceImpl" />

標準Java REST API：JAX-RS簡介

JAX-RS是標準的Java REST API，得到了業(yè)界的廣泛支持和應用，其著名的開源實現(xiàn)就有很多，包括Oracle的Jersey，RedHat的RestEasy，Apache的CXF和Wink，以及restlet等等。另外，所有支持JavaEE 6.0以上規(guī)范的商用JavaEE應用服務器都對JAX-RS提供了支持。因此，JAX-RS是一種已經非常成熟的解決方案，并且采用它沒有任何所謂vendor lock-in的問題。

JAX-RS在網(wǎng)上的資料非常豐富，例如下面的入門教程：

• Oracle官方的tutorial：http://docs.oracle.com/javaee/7/tutorial/doc/jaxrs.htm
• IBM developerWorks中國站文章：http://www.ibm.com/developerworks/cn/java/j-lo-jaxrs/

更多的資料請自行google或者百度一下。就學習JAX-RS來說，一般主要掌握其各種annotation的用法即可。

注意：dubbo是基于JAX-RS 2.0版本的，有時候需要注意一下資料或REST實現(xiàn)所涉及的版本。

REST服務提供端詳解

下面我們擴充“快速入門”中的UserService，進一步展示在dubbo中REST服務提供端的開發(fā)要點。

HTTP POST/GET的實現(xiàn)

REST服務中雖然建議使用HTTP協(xié)議中四種標準方法POST、DELETE、PUT、GET來分別實現(xiàn)常見的“增刪改查”，但實際中，我們一般情況直接用POST來實現(xiàn)“增改”，GET來實現(xiàn)“刪查”即可（DELETE和PUT甚至會被一些防火墻阻擋）。

前面已經簡單演示了POST的實現(xiàn)，在此，我們?yōu)閁serService添加一個獲取注冊用戶資料的功能，來演示GET的實現(xiàn)。

這個功能就是要實現(xiàn)客戶端通過訪問如下不同URL來獲取不同ID的用戶資料：

http://localhost:8080/users/1001
http://localhost:8080/users/1002
http://localhost:8080/users/1003

當然，也可以通過其他形式的URL來訪問不同ID的用戶資料，例如：

http://localhost:8080/users/load?id=1001

JAX-RS本身可以支持所有這些形式。但是上面那種在URL路徑中包含查詢參數(shù)的形式（http://localhost:8080/users/1001） 更符合REST的一般習慣，所以更推薦大家來使用。下面我們就為UserService添加一個getUser()方法來實現(xiàn)這種形式的URL訪問：

@GET
@Path("{id : \\d+}")
@Produces({MediaType.APPLICATION_JSON})
public User getUser(@PathParam("id") Long id) {
    // ...
}

@GET：指定用HTTP GET方法訪問

@Path("{id : \d+}")：根據(jù)上面的功能需求，訪問getUser()的URL應當是“http://localhost:8080/users/ + 任意數(shù)字"，并且這個數(shù)字要被做為參數(shù)傳入getUser()方法。 這里的annotation配置中，@Path中間的{id: xxx}指定URL相對路徑中包含了名為id參數(shù)，而它的值也將被自動傳遞給下面用@PathParam(“id”)修飾的方法參數(shù)id。{id:后面緊跟的\d+是一個正則表達式，指定了id參數(shù)必須是數(shù)字。

@Produces({MediaType.APPLICATION_JSON})：指定getUser()輸出JSON格式的數(shù)據(jù)。框架會自動將User對象序列化為JSON數(shù)據(jù)。

Annotation放在接口類還是實現(xiàn)類

在Dubbo中開發(fā)REST服務主要都是通過JAX-RS的annotation來完成配置的，在上面的示例中，我們都是將annotation放在服務的實現(xiàn)類中。但其實，我們完全也可以將annotation放到服務的接口上，這兩種方式是完全等價的，例如：

@Path("users")
public interface UserService {
    
    @GET
    @Path("{id : \\d+}")
    @Produces({MediaType.APPLICATION_JSON})
    User getUser(@PathParam("id") Long id);
}

在一般應用中，我們建議將annotation放到服務實現(xiàn)類，這樣annotation和java實現(xiàn)代碼位置更接近，更便于開發(fā)和維護。另外更重要的是，我們一般傾向于避免對接口的污染，保持接口的純凈性和廣泛適用性。

但是，如后文所述，如果我們要用dubbo直接開發(fā)的消費端來訪問此服務，則annotation必須放到接口上。

如果接口和實現(xiàn)類都同時添加了annotation，則實現(xiàn)類的annotation配置會生效，接口上的annotation被直接忽略。

JSON、XML等多數(shù)據(jù)格式的支持

在dubbo中開發(fā)的REST服務可以同時支持傳輸多種格式的數(shù)據(jù)，以給客戶端提供最大的靈活性。其中我們目前對最常用的JSON和XML格式特別添加了額外的功能。

比如，我們要讓上例中的getUser()方法支持分別返回JSON和XML格式的數(shù)據(jù)，只需要在annotation中同時包含兩種格式即可：

@Produces({MediaType.APPLICATION_JSON, MediaType.TEXT_XML})
User getUser(@PathParam("id") Long id);

或者也可以直接用字符串（還支持通配符）表示MediaType：

@Produces({"application/json", "text/xml"})
User getUser(@PathParam("id") Long id);

如果所有方法都支持同樣類型的輸入輸出數(shù)據(jù)格式，則我們無需在每個方法上做配置，只需要在服務類上添加annotation即可：

@Path("users")
@Consumes({MediaType.APPLICATION_JSON, MediaType.TEXT_XML})
@Produces({MediaType.APPLICATION_JSON, MediaType.TEXT_XML})
public class UserServiceImpl implements UserService {
    // ...
}

在一個REST服務同時對多種數(shù)據(jù)格式支持的情況下，根據(jù)JAX-RS標準，一般是通過HTTP中的MIME header（content-type和accept）來指定當前想用的是哪種格式的數(shù)據(jù)。

但是在dubbo中，我們還自動支持目前業(yè)界普遍使用的方式，即用一個URL后綴（.json和.xml）來指定想用的數(shù)據(jù)格式。例如，在添加上述annotation后，直接訪問http://localhost:8888/users/1001.json則表示用json格式，直接訪問http://localhost:8888/users/1002.xml則表示用xml格式，比用HTTP Header更簡單直觀。Twitter、微博等的REST API都是采用這種方式。

如果你既不加HTTP header，也不加后綴，則dubbo的REST會優(yōu)先啟用在以上annotation定義中排位最靠前的那種數(shù)據(jù)格式。

注意：這里要支持XML格式數(shù)據(jù)，在annotation中既可以用MediaType.TEXT_XML，也可以用MediaType.APPLICATION_XML，但是TEXT_XML是更常用的，并且如果要利用上述的URL后綴方式來指定數(shù)據(jù)格式，只能配置為TEXT_XML才能生效。

中文字符支持

為了在dubbo REST中正常輸出中文字符，和通常的Java web應用一樣，我們需要將HTTP響應的contentType設置為UTF-8編碼。

基于JAX-RS的標準用法，我們只需要做如下annotation配置即可：

@Produces({"application/json; charset=UTF-8", "text/xml; charset=UTF-8"})
User getUser(@PathParam("id") Long id);

為了方便用戶，我們在dubbo REST中直接添加了一個支持類，來定義以上的常量，可以直接使用，減少出錯的可能性。

@Produces({ContentType.APPLICATION_JSON_UTF_8, ContentType.TEXT_XML_UTF_8})
User getUser(@PathParam("id") Long id);

XML數(shù)據(jù)格式的額外要求

由于JAX-RS的實現(xiàn)一般都用標準的JAXB（Java API for XML Binding）來序列化和反序列化XML格式數(shù)據(jù)，所以我們需要為每一個要用XML傳輸?shù)膶ο筇砑右粋€類級別的JAXB annotation，否則序列化將報錯。例如為getUser()中返回的User添加如下：

@XmlRootElement
public class User implements Serializable {
    // ...
}

此外，如果service方法中的返回值是Java的 primitive類型（如int，long，float，double等），最好為它們添加一層wrapper對象，因為JAXB不能直接序列化primitive類型。

例如，我們想讓前述的registerUser()方法返回服務器端為用戶生成的ID號：

long registerUser(User user);

由于primitive類型不被JAXB序列化支持，所以添加一個wrapper對象：

@XmlRootElement
public class RegistrationResult implements Serializable {
    
    private Long id;
    
    public RegistrationResult() {
    }
    
    public RegistrationResult(Long id) {
        this.id = id;
    }
    
    public Long getId() {
        return id;
    }
    
    public void setId(Long id) {
        this.id = id;
    }
}

并修改service方法：

RegistrationResult registerUser(User user);

這樣不但能夠解決XML序列化的問題，而且使得返回的數(shù)據(jù)都符合XML和JSON的規(guī)范。例如，在JSON中，返回的將是如下形式：

{"id": 1001}

如果不加wrapper，JSON返回值將直接是

1001 	

而在XML中，加wrapper后返回值將是：

<registrationResult>
    <id>1002</id>
</registrationResult>

這種wrapper對象其實利用所謂Data Transfer Object（DTO）模式，采用DTO還能對傳輸數(shù)據(jù)做更多有用的定制。

定制序列化

如上所述，REST的底層實現(xiàn)會在service的對象和JSON/XML數(shù)據(jù)格式之間自動做序列化/反序列化。但有些場景下，如果覺得這種自動轉換不滿足要求，可以對其做定制。

Dubbo中的REST實現(xiàn)是用JAXB做XML序列化，用Jackson做JSON序列化，所以在對象上添加JAXB或Jackson的annotation即可以定制映射。

例如，定制對象屬性映射到XML元素的名字：

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class User implements Serializable {
    
    @XmlElement(name="username") 
    private String name;  
}

定制對象屬性映射到JSON字段的名字：

public class User implements Serializable {
    
    @JsonProperty("username")
    private String name;
}

更多資料請參考JAXB和Jackson的官方文檔，或自行google。

配置REST Server的實現(xiàn)

目前在dubbo中，我們支持5種嵌入式rest server的實現(xiàn)，并同時支持采用外部應用服務器來做rest server的實現(xiàn)。rest server的實現(xiàn)是通過如下server這個XML屬性來選擇的：

<dubbo:protocol name="rest" server="jetty"/>

以上配置選用了嵌入式的jetty來做rest server，同時，如果不配置server屬性，rest協(xié)議默認也是選用jetty。jetty是非常成熟的java servlet容器，并和dubbo已經有較好的集成（目前5種嵌入式server中只有jetty和后面所述的tomcat、tjws，與dubbo監(jiān)控系統(tǒng)等完成了無縫的集成），所以，如果你的dubbo系統(tǒng)是單獨啟動的進程，你可以直接默認采用jetty即可。

<dubbo:protocol name="rest" server="tomcat"/>

以上配置選用了嵌入式的tomcat來做rest server。在嵌入式tomcat上，REST的性能比jetty上要好得多（參見后面的基準測試），建議在需要高性能的場景下采用tomcat。

<dubbo:protocol name="rest" server="netty"/>

以上配置選用嵌入式的netty來做rest server。（TODO more contents to add）

<dubbo:protocol name="rest" server="tjws"/> (tjws is now deprecated)
<dubbo:protocol name="rest" server="sunhttp"/>

以上配置選用嵌入式的tjws或Sun HTTP server來做rest server。這兩個server實現(xiàn)非常輕量級，非常方便在集成測試中快速啟動使用，當然也可以在負荷不高的生產環(huán)境中使用。 注：tjws目前已經被deprecated掉了，因為它不能很好的和servlet 3.1 API工作。

如果你的dubbo系統(tǒng)不是單獨啟動的進程，而是部署到了Java應用服務器中，則建議你采用以下配置：

<dubbo:protocol name="rest" server="servlet"/>

通過將server設置為servlet，dubbo將采用外部應用服務器的servlet容器來做rest server。同時，還要在dubbo系統(tǒng)的web.xml中添加如下配置：

<web-app>
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/classes/META-INF/spring/dubbo-demo-provider.xml</param-value>
    </context-param>
    
    <listener>
        <listener-class>org.apache.dubbo.remoting.http.servlet.BootstrapListener</listener-class>
    </listener>
    
    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>
    
    <servlet>
        <servlet-name>dispatcher</servlet-name>
        <servlet-class>org.apache.dubbo.remoting.http.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    
    <servlet-mapping>
        <servlet-name>dispatcher</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

即必須將dubbo的BootstrapListener和DispatherServlet添加到web.xml，以完成dubbo的REST功能與外部servlet容器的集成。

注意：如果你是用spring的ContextLoaderListener來加載spring，則必須保證BootstrapListener配置在ContextLoaderListener之前，否則dubbo初始化會出錯。

其實，這種場景下你依然可以堅持用嵌入式server，但外部應用服務器的servlet容器往往比嵌入式server更加強大（特別是如果你是部署到更健壯更可伸縮的WebLogic，WebSphere等），另外有時也便于在應用服務器做統(tǒng)一管理、監(jiān)控等等。

獲取上下文（Context）信息

在遠程調用中，值得獲取的上下文信息可能有很多種，這里特別以獲取客戶端IP為例。

在dubbo的REST中，我們有兩種方式獲取客戶端IP。

第一種方式，用JAX-RS標準的@Context annotation：

public User getUser(@PathParam("id") Long id, @Context HttpServletRequest request) {
    System.out.println("Client address is " + request.getRemoteAddr());
} 

用Context修飾getUser()的一個方法參數(shù)后，就可以將當前的HttpServletRequest注入進來，然后直接調用servlet api獲取IP。

注意：這種方式只能在設置server=“tjws"或者server=“tomcat"或者server=“jetty"或者server=“servlet"的時候才能工作，因為只有這幾種REST server的實現(xiàn)才提供了servlet容器。另外，標準的JAX-RS還支持用@Context修飾service類的一個實例字段來獲取HttpServletRequest，但在dubbo中我們沒有對此作出支持。

第二種方式，用dubbo中常用的RpcContext：

public User getUser(@PathParam("id") Long id) {
    System.out.println("Client address is " + RpcContext.getContext().getRemoteAddressString());
} 

注意：這種方式只能在設置server=“jetty"或者server=“tomcat"或者server=“servlet"或者server=“tjws"的時候才能工作。另外，目前dubbo的RpcContext是一種比較有侵入性的用法，未來我們很可能會做出重構。

如果你想保持你的項目對JAX-RS的兼容性，未來脫離dubbo也可以運行，請選擇第一種方式。如果你想要更優(yōu)雅的服務接口定義，請選用第二種方式。

此外，在最新的dubbo rest中，還支持通過RpcContext來獲取HttpServletRequest和HttpServletResponse，以提供更大的靈活性來方便用戶實現(xiàn)某些復雜功能，比如在dubbo標準的filter中訪問HTTP Header。用法示例如下：

if (RpcContext.getContext().getRequest() != null && RpcContext.getContext().getRequest() instanceof HttpServletRequest) {
    System.out.println("Client address is " + ((HttpServletRequest) RpcContext.getContext().getRequest()).getRemoteAddr());
}

if (RpcContext.getContext().getResponse() != null && RpcContext.getContext().getResponse() instanceof HttpServletResponse) {
    System.out.println("Response object from RpcContext: " + RpcContext.getContext().getResponse());
}

注意：為了保持協(xié)議的中立性，RpcContext.getRequest()和RpcContext.getResponse()返回的僅僅是一個Object類，而且可能為null。所以，你必須自己做null和類型的檢查。

注意：只有在設置server=“jetty"或者server=“tomcat"或者server=“servlet"的時候，你才能通過以上方法正確的得到HttpServletRequest和HttpServletResponse，因為只有這幾種server實現(xiàn)了servlet容器。

為了簡化編程，在此你也可以用泛型的方式來直接獲取特定類型的request/response：

if (RpcContext.getContext().getRequest(HttpServletRequest.class) != null) {
    System.out.println("Client address is " + RpcContext.getContext().getRequest(HttpServletRequest.class).getRemoteAddr());
}

if (RpcContext.getContext().getResponse(HttpServletResponse.class) != null) {
    System.out.println("Response object from RpcContext: " + RpcContext.getContext().getResponse(HttpServletResponse.class));
}

如果request/response不符合指定的類型，這里也會返回null。

配置端口號和Context Path

dubbo中的rest協(xié)議默認將采用80端口，如果想修改端口，直接配置：

<dubbo:protocol name="rest" port="8888"/>

另外，如前所述，我們可以用@Path來配置單個rest服務的URL相對路徑。但其實，我們還可以設置一個所有rest服務都適用的基礎相對路徑，即java web應用中常說的context path。

只需要添加如下contextpath屬性即可：

<dubbo:protocol name="rest" port="8888" contextpath="services"/>

以前面代碼為例：

@Path("users")
public class UserServiceImpl implements UserService {
       
    @POST
    @Path("register")
    @Consumes({MediaType.APPLICATION_JSON})
    public void registerUser(User user) {
        // save the user...
    }	
}

現(xiàn)在registerUser()的完整訪問路徑為：

http://localhost:8888/services/users/register

注意：如果你是選用外部應用服務器做rest server，即配置:

<dubbo:protocol name="rest" port="8888" contextpath="services" server="servlet"/>

則必須保證這里設置的port、contextpath，與外部應用服務器的端口、DispatcherServlet的上下文路徑（即webapp path加上servlet url pattern）保持一致。例如，對于部署為tomcat ROOT路徑的應用，這里的contextpath必須與web.xml中DispacherServlet的<url-pattern/>完全一致：

<servlet-mapping>
     <servlet-name>dispatcher</servlet-name>
     <url-pattern>/services/*</url-pattern>
</servlet-mapping>

配置線程數(shù)和IO線程數(shù)

可以為rest服務配置線程池大?。?/p>

<dubbo:protocol name="rest" threads="500"/>

注意：目前線程池的設置只有當server=“netty"或者server=“jetty"或者server=“tomcat"的時候才能生效。另外，如果server=“servlet”，由于這時候啟用的是外部應用服務器做rest server，不受dubbo控制，所以這里的線程池設置也無效。

如果是選用netty server，還可以配置Netty的IO worker線程數(shù)：

<dubbo:protocol name="rest" iothreads="5" threads="100"/>

配置長連接

Dubbo中的rest服務默認都是采用http長連接來訪問，如果想切換為短連接，直接配置：

<dubbo:protocol name="rest" keepalive="false"/>

注意：這個配置目前只對server=“netty"和server=“tomcat"才能生效。

配置最大的HTTP連接數(shù)

可以配置服務器提供端所能同時接收的最大HTTP連接數(shù)，防止REST server被過多連接撐爆，以作為一種最基本的自我保護機制：

<dubbo:protocol name="rest" accepts="500" server="tomcat/>

注意：這個配置目前只對server=“tomcat"才能生效。

配置每個消費端的超時時間和HTTP連接數(shù)

如果rest服務的消費端也是dubbo系統(tǒng)，可以像其他dubbo RPC機制一樣，配置消費端調用此rest服務的最大超時時間以及每個消費端所能啟動的最大HTTP連接數(shù)。

<dubbo:service interface="xxx" ref="xxx" protocol="rest" timeout="2000" connections="10"/>

當然，由于這個配置針對消費端生效的，所以也可以在消費端配置：

<dubbo:reference id="xxx" interface="xxx" timeout="2000" connections="10"/>

但是，通常我們建議配置在服務提供端提供此類配置。按照dubbo官方文檔的說法：“Provider上盡量多配置Consumer端的屬性，讓Provider實現(xiàn)者一開始就思考Provider服務特點、服務質量的問題?！?/p>

注意：如果dubbo的REST服務是發(fā)布給非dubbo的客戶端使用，則這里上的配置完全無效，因為這種客戶端不受dubbo控制。

GZIP數(shù)據(jù)壓縮

Dubbo的REST支持用GZIP壓縮請求和響應的數(shù)據(jù)，以減少網(wǎng)絡傳輸時間和帶寬占用，但這種方式會也增加CPU開銷。

TODO more contents to add

用Annotation取代部分Spring XML配置

以上所有的討論都是基于dubbo在spring中的xml配置。但是，dubbo/spring本身也支持用annotation來作配置，所以我們也可以按dubbo官方文檔中的步驟，把相關annotation加到REST服務的實現(xiàn)中，取代一些xml配置，例如：

@Service(protocol = "rest")
@Path("users")
public class UserServiceImpl implements UserService {

    @Autowired
    private UserRepository userRepository;
       
    @POST
    @Path("register")
    @Consumes({MediaType.APPLICATION_JSON})
    public void registerUser(User user) {
        // save the user
        userRepository.save(user);
    }	
}

annotation的配置更簡單更精確，經常也更便于維護（當然現(xiàn)代IDE都可以在xml中支持比如類名重構，所以就這里的特定用例而言，xml的維護性也很好）。而xml對代碼的侵入性更小一些，尤其有利于動態(tài)修改配置，特別是比如你要針對單個服務配置連接超時時間、每客戶端最大連接數(shù)、集群策略、權重等等。另外，特別對復雜應用或者模塊來說，xml提供了一個中心點來涵蓋的所有組件和配置，更一目了然，一般更便于項目長時期的維護。

當然，選擇哪種配置方式沒有絕對的優(yōu)劣，和個人的偏好也不無關系。

添加自定義的Filter、Interceptor等

Dubbo的REST也支持JAX-RS標準的Filter和Interceptor，以方便對REST的請求與響應過程做定制化的攔截處理。

其中，F(xiàn)ilter主要用于訪問和設置HTTP請求和響應的參數(shù)、URI等等。例如，設置HTTP響應的cache header：

public class CacheControlFilter implements ContainerResponseFilter {

    public void filter(ContainerRequestContext req, ContainerResponseContext res) {
        if (req.getMethod().equals("GET")) {
            res.getHeaders().add("Cache-Control", "someValue");
        }
    }
}

Interceptor主要用于訪問和修改輸入與輸出字節(jié)流，例如，手動添加GZIP壓縮：

public class GZIPWriterInterceptor implements WriterInterceptor {
 
    @Override
    public void aroundWriteTo(WriterInterceptorContext context)
                    throws IOException, WebApplicationException {
        OutputStream outputStream = context.getOutputStream();
        context.setOutputStream(new GZIPOutputStream(outputStream));
        context.proceed();
    }
}

在標準JAX-RS應用中，我們一般是為Filter和Interceptor添加@Provider annotation，然后JAX-RS runtime會自動發(fā)現(xiàn)并啟用它們。而在dubbo中，我們是通過添加XML配置的方式來注冊Filter和Interceptor：

<dubbo:protocol name="rest" port="8888" extension="xxx.TraceInterceptor, xxx.TraceFilter"/>

在此，我們可以將Filter、Interceptor和DynamicFeature這三種類型的對象都添加到extension屬性上，多個之間用逗號分隔。（DynamicFeature是另一個接口，可以方便我們更動態(tài)的啟用Filter和Interceptor，感興趣請自行google。）

當然，dubbo自身也支持Filter的概念，但我們這里討論的Filter和Interceptor更加接近協(xié)議實現(xiàn)的底層，相比dubbo的filter，可以做更底層的定制化。

注：這里的XML屬性叫extension，而不是叫interceptor或者filter，是因為除了Interceptor和Filter，未來我們還會添加更多的擴展類型。

如果REST的消費端也是dubbo系統(tǒng)（參見下文的討論），則也可以用類似方式為消費端配置Interceptor和Filter。但注意，JAX-RS中消費端的Filter和提供端的Filter是兩種不同的接口。例如前面例子中服務端是ContainerResponseFilter接口，而消費端對應的是ClientResponseFilter:

public class LoggingFilter implements ClientResponseFilter {
 
    public void filter(ClientRequestContext reqCtx, ClientResponseContext resCtx) throws IOException {
        System.out.println("status: " + resCtx.getStatus());
	    System.out.println("date: " + resCtx.getDate());
	    System.out.println("last-modified: " + resCtx.getLastModified());
	    System.out.println("location: " + resCtx.getLocation());
	    System.out.println("headers:");
	    for (Entry<String, List<String>> header : resCtx.getHeaders().entrySet()) {
     	    System.out.print("\t" + header.getKey() + " :");
	        for (String value : header.getValue()) {
	            System.out.print(value + ", ");
	        }
	        System.out.print("\n");
	    }
	    System.out.println("media-type: " + resCtx.getMediaType().getType());
    } 
}

添加自定義的Exception處理

Dubbo的REST也支持JAX-RS標準的ExceptionMapper，可以用來定制特定exception發(fā)生后應該返回的HTTP響應。

public class CustomExceptionMapper implements ExceptionMapper<NotFoundException> {

    public Response toResponse(NotFoundException e) {     
        return Response.status(Response.Status.NOT_FOUND).entity("Oops! the requested resource is not found!").type("text/plain").build();
    }
}

和Interceptor、Filter類似，將其添加到XML配置文件中即可啟用：

<dubbo:protocol name="rest" port="8888" extension="xxx.CustomExceptionMapper"/>

配置HTTP日志輸出

Dubbo rest支持輸出所有HTTP請求/響應中的header字段和body消息體。

在XML配置中添加如下自帶的REST filter：

<dubbo:protocol name="rest" port="8888" extension="org.apache.dubbo.rpc.protocol.rest.support.LoggingFilter"/>

然后在logging配置中至少為org.apache.dubbo.rpc.protocol.rest.support打開INFO級別日志輸出，例如，在log4j.xml中配置：

<logger name="org.apache.dubbo.rpc.protocol.rest.support">
    <level value="INFO"/>
    <appender-ref ref="CONSOLE"/>
</logger>

當然，你也可以直接在ROOT logger打開INFO級別日志輸出：

<root>
	<level value="INFO" />
	<appender-ref ref="CONSOLE"/>
</root>

然后在日志中會有類似如下的內容輸出：

The HTTP headers are: 
accept: application/json;charset=UTF-8
accept-encoding: gzip, deflate
connection: Keep-Alive
content-length: 22
content-type: application/json
host: 192.168.1.100:8888
user-agent: Apache-HttpClient/4.2.1 (java 1.5)

The contents of request body is: 
{"id":1,"name":"dang"}

打開HTTP日志輸出后，除了正常日志輸出的性能開銷外，也會在比如HTTP請求解析時產生額外的開銷，因為需要建立額外的內存緩沖區(qū)來為日志的輸出做數(shù)據(jù)準備。

輸入?yún)?shù)的校驗

dubbo的rest支持采用Java標準的bean validation annotation（JSR 303)來做輸入校驗http://beanvalidation.org/

為了和其他dubbo遠程調用協(xié)議保持一致，在rest中作校驗的annotation必須放在服務的接口上，例如：

public interface UserService {
   
    User getUser(@Min(value=1L, message="User ID must be greater than 1") Long id);
}

當然，在很多其他的bean validation的應用場景都是將annotation放到實現(xiàn)類而不是接口上。把annotation放在接口上至少有一個好處是，dubbo的客戶端可以共享這個接口的信息，dubbo甚至不需要做遠程調用，在本地就可以完成輸入校驗。

然后按照dubbo的標準方式在XML配置中打開驗證：

<dubbo:service interface=xxx.UserService" ref="userService" protocol="rest" validation="true"/>

在dubbo的其他很多遠程調用協(xié)議中，如果輸入驗證出錯，是直接將RpcException拋向客戶端，而在rest中由于客戶端經常是非dubbo，甚至非java的系統(tǒng)，所以不便直接拋出Java異常。因此，目前我們將校驗錯誤以XML的格式返回：

<violationReport>
    <constraintViolations>
        <path>getUserArgument0</path>
        <message>User ID must be greater than 1</message>
        <value>0</value>
    </constraintViolations>
</violationReport>

稍后也會支持其他數(shù)據(jù)格式的返回值。至于如何對驗證錯誤消息作國際化處理，直接參考bean validation的相關文檔即可。

如果你認為默認的校驗錯誤返回格式不符合你的要求，可以如上面章節(jié)所述，添加自定義的ExceptionMapper來自由的定制錯誤返回格式。需要注意的是，這個ExceptionMapper必須用泛型聲明來捕獲dubbo的RpcException，才能成功覆蓋dubbo rest默認的異常處理策略。為了簡化操作，其實這里最簡單的方式是直接繼承dubbo rest的RpcExceptionMapper，并覆蓋其中處理校驗異常的方法即可：

public class MyValidationExceptionMapper extends RpcExceptionMapper {

    protected Response handleConstraintViolationException(ConstraintViolationException cve) {
        ViolationReport report = new ViolationReport();
        for (ConstraintViolation cv : cve.getConstraintViolations()) {
            report.addConstraintViolation(new RestConstraintViolation(
                    cv.getPropertyPath().toString(),
                    cv.getMessage(),
                    cv.getInvalidValue() == null ? "null" : cv.getInvalidValue().toString()));
        }
        // 采用json輸出代替xml輸出
        return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(report).type(ContentType.APPLICATION_JSON_UTF_8).build();
    }
}

然后將這個ExceptionMapper添加到XML配置中即可：

<dubbo:protocol name="rest" port="8888" extension="xxx.MyValidationExceptionMapper"/>

是否應該透明發(fā)布REST服務

Dubbo的REST調用和dubbo中其它某些RPC不同的是，需要在服務代碼中添加JAX-RS的annotation（以及JAXB、Jackson的annotation），如果你覺得這些annotation一定程度“污染”了你的服務代碼，你可以考慮編寫額外的Facade和DTO類，在Facade和DTO上添加annotation，而Facade將調用轉發(fā)給真正的服務實現(xiàn)類。當然事實上，直接在服務代碼中添加annotation基本沒有任何負面作用，而且這本身是Java EE的標準用法，另外JAX-RS和JAXB的annotation是屬于java標準，比我們經常使用的spring、dubbo等等annotation更沒有vendor lock-in的問題，所以一般沒有必要因此而引入額外對象。

另外，如果你想用前述的@Context annotation，通過方法參數(shù)注入HttpServletRequest（如public User getUser(@PathParam("id") Long id, @Context HttpServletRequest request)），這時候由于改變了服務的方法簽名，并且HttpServletRequest是REST特有的參數(shù)，所以如果你的服務要支持多種RPC機制的話，則引入額外的Facade類是比較適當?shù)摹?/p>

當然，在沒有添加REST調用之前，你的服務代碼可能本身已經就充當了Facade和DTO的角色（至于為什么有些場景需要這些角色，有興趣可參考微觀SOA：服務設計原則及其實踐方式）。這種情況下，在添加REST之后，如果你再額外添加與REST相關的Facade和DTO，就相當于對原有代碼對再一次包裝，即形成如下調用鏈：

RestFacade/RestDTO -> Facade/DTO -> Service

這種體系比較繁瑣，數(shù)據(jù)轉換之類的工作量也不小，所以一般應盡量避免如此。

dubbo的提供端在調用REST服務時使用header

Dubbo通過RpcContextFilter將header取出分解之后設置到RpcContext的attachments，所以在提供端可以直接從RpcContext的attachments中獲取到消費端設置的header信息：

    RpcContext.getContext().getAttachment(key1)
    RpcContext.getContext().getAttachment(key2)

REST服務消費端詳解

這里我們用三種場景來分別討論：

1. 非dubbo的消費端調用dubbo的REST服務（non-dubbo –> dubbo）
2. dubbo消費端調用dubbo的REST服務 （dubbo –> dubbo）
3. dubbo的消費端調用非dubbo的REST服務 （dubbo –> non-dubbo）

場景1：非dubbo的消費端調用dubbo的REST服務

這種場景的客戶端與dubbo本身無關，直接選用相應語言和框架中合適的方式即可。

如果是還是java的客戶端（但沒用dubbo），可以考慮直接使用標準的JAX-RS Client API或者特定REST實現(xiàn)的Client API來調用REST服務。下面是用JAX-RS Client API來訪問上述的UserService的registerUser()：

User user = new User();
user.setName("Larry");

Client client = ClientBuilder.newClient();
WebTarget target = client.target("http://localhost:8080/services/users/register.json");
Response response = target.request().post(Entity.entity(user, MediaType.APPLICATION_JSON_TYPE));

try {
    if (response.getStatus() != 200) {
        throw new RuntimeException("Failed with HTTP error code : " + response.getStatus());
    }
    System.out.println("The generated id is " + response.readEntity(RegistrationResult.class).getId());
} finally {
    response.close();
    client.close(); // 在真正開發(fā)中不要每次關閉client，比如HTTP長連接是由client持有的
}

上面代碼片段中的User和RegistrationResult類都是消費端自己編寫的，JAX-RS Client API會自動對它們做序列化/反序列化。

當然，在java中也可以直接用自己熟悉的比如HttpClient，F(xiàn)astJson，XStream等等各種不同技術來實現(xiàn)REST客戶端，在此不再詳述。

場景2：dubbo消費端調用dubbo的REST服務

這種場景下，和使用其他dubbo的遠程調用方式一樣，直接在服務提供端和服務消費端共享Java服務接口，并添加spring xml配置（當然也可以用spring/dubbo的annotation配置），即可透明的調用遠程REST服務：

<dubbo:reference id="userService" interface="xxx.UserService"/>

如前所述，這種場景下必須把JAX-RS的annotation添加到服務接口上，這樣在dubbo在消費端才能共享相應的REST配置信息，并據(jù)之做遠程調用:

@Path("users")
public interface UserService {
    
    @GET
    @Path("{id : \\d+}")
    @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
    User getUser(@PathParam("id") Long id);
}

如果服務接口的annotation中配置了多種數(shù)據(jù)格式，這里由于兩端都是dubbo系統(tǒng)，REST的大量細節(jié)被屏蔽了，所以不存在用前述URL后綴之類選擇數(shù)據(jù)格式的可能。目前在這種情況下，排名最靠前的數(shù)據(jù)格式將直接被使用。

因此，我們建議你在定義annotation的時候最好把最合適的數(shù)據(jù)格式放到前面，比如以上我們是把json放在xml前面，因為json的傳輸性能優(yōu)于xml。

場景3：dubbo的消費端調用非dubbo的REST服務

這種場景下，可以直接用場景1中描述的Java的方式來調用REST服務。但其實也可以采用場景2中描述的方式，即更透明的調用REST服務，即使這個服務并不是dubbo提供的。

如果用場景2的方式，由于這里REST服務并非dubbo提供，一般也就沒有前述的共享的Java服務接口，所以在此我們需要根據(jù)外部REST服務的情況，自己來編寫Java接口以及相應參數(shù)類，并添加JAX-RS、JAXB、Jackson等的annotation，dubbo的REST底層實現(xiàn)會據(jù)此去自動生成請求消息，自動解析響應消息等等，從而透明的做遠程調用?；蛘哌@種方式也可以理解為，我們嘗試用JAX-RS的方式去仿造實現(xiàn)一遍外部的REST服務提供端，然后把寫成服務接口放到客戶端來直接使用，dubbo的REST底層實現(xiàn)就能像調用dubbo的REST服務一樣調用其他REST服務。

例如，我們要調用如下的外部服務

http://api.foo.com/services/users/1001
http://api.foo.com/services/users/1002

獲取不同ID的用戶資料，返回格式是JSON

{
    "id": 1001,
    "name": "Larry"
}

我們可根據(jù)這些信息，編寫服務接口和參數(shù)類即可：

@Path("users")
public interface UserService {
    
    @GET
    @Path("{id : \\d+}")
    @Produces({MediaType.APPLICATION_JSON})
    User getUser(@PathParam("id") Long id);
}

public class User implements Serializable {

    private Long id;

    private String name;

    // …
}

對于spring中的配置，因為這里的REST服務不是dubbo提供的，所以無法使用dubbo的注冊中心，直接配置外部REST服務的url地址即可（如多個地址用逗號分隔）：

<dubbo:reference id="userService" interface="xxx.UserService" url="rest://api.foo.com/services/"/>

注意：這里協(xié)議必須用rest://而不是http://之類。如果外部的REST服務有context path，則在url中也必須添加上（除非你在每個服務接口的@Path annotation中都帶上context path），例如上面的/services/。同時這里的services后面必須帶上/，這樣才能使dubbo正常工作。

另外，這里依然可以配置客戶端可啟動的最大連接數(shù)和超時時間：

<dubbo:reference id="userService" interface="xxx.UserService" url="rest://api.foo.com/services/" timeout="2000" connections="10"/>

dubbo的消費端在調用REST服務時配置自定義header

Dubbo進行rest調用的時候，采用的是將RpcContext的attachment轉換為header的方式，所以，dubbo消費端可以按以下方式進行自定義header的設置：

    RpcContext.getContext().setAttachment("key1", "value1");
    RpcContext.getContext().setAttachment("key2", "value2");

即可設置如下格式的header:

    key1=value1
    key2=value2

Dubbo中JAX-RS的限制

Dubbo中的REST開發(fā)是完全兼容標準JAX-RS的，但其支持的功能目前是完整JAX-RS的一個子集，部分因為它要受限于dubbo和spring的特定體系。

在dubbo中使用的JAX-RS的局限包括但不限于：

1. 服務實現(xiàn)只能是singleton的，不能支持per-request scope和per-lookup scope
2. 不支持用@Context annotation對服務的實例字段注入 ServletConfig、ServletContext、HttpServletRequest、HttpServletResponse等等，但可以支持對服務方法參數(shù)的注入。但對某些特定REST server實現(xiàn)，（祥見前面的敘述），也不支持對服務方法參數(shù)的注入。

REST常見問題解答（REST FAQ）

Dubbo REST的服務能和Dubbo注冊中心、監(jiān)控中心集成嗎？

可以的，而且是自動集成的，也就是你在dubbo中開發(fā)的所有REST服務都會自動注冊到注冊中心和監(jiān)控中心，可以通過它們做管理。

但是，只有當REST的消費端也是基于dubbo的時候，注冊中心中的許多服務治理操作才能完全起作用。而如果消費端是非dubbo的，自然不受注冊中心管理，所以其中很多操作是不會對消費端起作用的。

Dubbo REST中如何實現(xiàn)負載均衡和容錯（failover）？

如果dubbo REST的消費端也是dubbo的，則Dubbo REST和其他dubbo遠程調用協(xié)議基本完全一樣，由dubbo框架透明的在消費端做load balance、failover等等。

如果dubbo REST的消費端是非dubbo的，甚至是非java的，則最好配置服務提供端的軟負載均衡機制，目前可考慮用LVS、HAProxy、 Nginx等等對HTTP請求做負載均衡。

JAX-RS中重載的方法能夠映射到同一URL地址嗎？

http://stackoverflow.com/questions/17196766/can-resteasy-choose-method-based-on-query-params

JAX-RS中作POST的方法能夠接收多個參數(shù)嗎？

http://stackoverflow.com/questions/5553218/jax-rs-post-multiple-objects

Dubbo當前體系的不足之處（與REST相關的）

我認為dubbo當前體系中顯然也有不少不足之處，這里列出幾個與REST有關的、并影響用戶使用的問題（不包括內部實現(xiàn)的問題），供參考評論，為下一步重構作準備。

RpcContext的侵入性

在前文，前面我們已經提到過RpcContext用法的侵入性，由于它是用單例的方式來訪問上下文信息，這完全不符合spring應用的一般風格，不利于應用擴展和單元測試。未來我們可能用依賴注入方式注入一個接口，再用它去訪問ThreadLocal中的上下文信息。

Protocol配置的局限性

dubbo支持多種遠程調用方式，但所有調用方式都是用<dubbo:protocol/>來配置的，例如：

<dubbo:protocol name="dubbo" port="9090" server="netty" client="netty" codec="dubbo" serialization="hessian2" 
    charset="UTF-8" threadpool="fixed" threads="100" queues="0" iothreads="9" buffer="8192" accepts="1000" payload="8388608"/>

其實，上面很多屬性實際上dubbo RPC遠程調用方式特有的，很多dubbo中的其它遠程調用方式根本就不支持例如server, client, codec, iothreads, accepts, payload等等（當然，有的是條件所限不支持，有的是根本沒有必要支持）。這給用戶的使用徒增很多困惑，用戶也并不知道有些屬性（比如做性能調優(yōu)）添加了實際上是不起作用的。

另一方面，各種遠程調用方式往往有大量自己獨特的配置需要，特別是我們逐步為每種遠程調用方式都添加更豐富、更高級的功能，這就不可避免的擴展<protocol/>中的屬性（例如目前我們在REST中已經添加了keepalive和extension兩個屬性），到最后會導致<protocol/>臃腫不堪，用戶的使用也更加困惑。

當然，dubbo中有一種擴展<protocol/>的方式是用<dubbo:parameter/>，但這種方式顯然很有局限性，而且用法復雜，缺乏schema校驗。

所以，最好的方式是為每種遠程調用方式設置自己的protocol元素，比如<protocol-dubbo/>，<protocol-rest/>等等，每種元素用XML schema規(guī)定自己的屬性（當然屬性在各種遠程調用方式之間能通用是最好的）。

如此一來，例如前面提到過的extension配置也可以用更自由的方式，從而更清楚更可擴展（以下只是舉例，當然也許有更好的方式）:

<dubbo:protocol-rest port="8080">
    <dubbo:extension>someInterceptor</dubbo:extension>
    <dubbo:extension>someFilter</dubbo:extension>
    <dubbo:extension>someDynamicFeature</dubbo:extension>
    <dubbo:extension>someEntityProvider</dubbo:extension>
</dubbo:protocol-rest>

XML命名不符合spring規(guī)范

dubbo的XML配置中大量命名都不符合spring規(guī)范，比如：

<dubbo:protocol name="dubbo" port="9090" server="netty" client="netty" codec="dubbo" serialization="hessian2" 
    charset="UTF-8" threadpool="fixed" threads="100" queues="0" iothreads="9" buffer="8192" accepts="1000" payload="8388608"/>

上面threadpool應該改為thread-pool，iothreads應該改為io-threads，單詞之間應該用”-“分隔。這雖然看起來是個小問題，但也涉及到了可讀性，特別是可擴展性，因為有時候我們不可避免要用更多單詞來描述XML元素和屬性。

其實dubbo本身也是建議遵守spring到XML的命名規(guī)范。

REST最佳實踐

TODO

性能基準測試

測試環(huán)境

粗略如下：

• 兩臺獨立服務器
• 4核Intel(R) Xeon(R) CPU E5-2603 0 @ 1.80GHz
• 8G內存
• 服務器之間網(wǎng)絡通過百兆交換機
• CentOS 5
• JDK 7
• Tomcat 7
• JVM參數(shù)-server -Xms1g -Xmx1g -XX:PermSize=64M -XX:+UseConcMarkSweepGC

測試腳本

和dubbo自身的基準測試保持接近：

10個并發(fā)客戶端持續(xù)不斷發(fā)出請求：

• 傳入嵌套復雜對象（但單個數(shù)據(jù)量很小），不做任何處理，原樣返回
• 傳入50K字符串，不做任何處理，原樣返回（TODO：結果尚未列出）

進行5分鐘性能測試。（引用dubbo自身測試的考慮：“主要考察序列化和網(wǎng)絡IO的性能，因此服務端無任何業(yè)務邏輯。取10并發(fā)是考慮到http協(xié)議在高并發(fā)下對CPU的使用率較高可能會先打到瓶頸?！保?/p>

測試結果

下面的結果主要對比的是REST和dubbo RPC兩種遠程調用方式，并對它們作不同的配置，例如：

• “REST: Jetty + XML + GZIP”的意思是：測試REST，并采用jetty server，XML數(shù)據(jù)格式，啟用GZIP壓縮。
• “Dubbo: hessian2”的意思是：測試dubbo RPC，并采用hessian2序列化方式。

針對復雜對象的結果如下（響應時間越小越好，TPS越大越好）：

僅就目前的結果，一點簡單總結：

• dubbo RPC（特別是基于高效java序列化方式如kryo，fst）比REST的響應時間和吞吐量都有較顯著優(yōu)勢，內網(wǎng)的dubbo系統(tǒng)之間優(yōu)先選擇dubbo RPC。
• 在REST的實現(xiàn)選擇上，僅就性能而言，目前tomcat7和netty最優(yōu)（當然目前使用的jetty和netty版本都較低）。tjws和sun http server在性能測試中表現(xiàn)極差，平均響應時間超過200ms，平均tps只有50左右（為了避免影響圖片效果，沒在上面列出）。
• 在REST中JSON數(shù)據(jù)格式性能優(yōu)于XML（數(shù)據(jù)暫未在以上列出）。
• 在REST中啟用GZIP對企業(yè)內網(wǎng)中的小數(shù)據(jù)量復雜對象幫助不大，性能反而有下降（數(shù)據(jù)暫未在以上列出）。

性能優(yōu)化建議

如果將dubbo REST部署到外部Tomcat上，并配置server=“servlet”，即啟用外部的tomcat來做為rest server的底層實現(xiàn)，則最好在tomcat上添加如下配置：

<Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
               connectionTimeout="20000"
               redirectPort="8443"
               minSpareThreads="20"
               enableLookups="false"
               maxThreads="100"
               maxKeepAliveRequests="-1"
               keepAliveTimeout="60000"/>

特別是maxKeepAliveRequests="-1”，這個配置主要是保證tomcat一直啟用http長連接，以提高REST調用性能。但是請注意，如果REST消費端不是持續(xù)的調用REST服務，則一直啟用長連接未必是最好的做法。另外，一直啟用長連接的方式一般不適合針對普通webapp，更適合這種類似rpc的場景。所以為了高性能，在tomcat中，dubbo REST應用和普通web應用最好不要混合部署，而應該用單獨的實例。

TODO more contents to add

擴展討論

REST與Thrift、Protobuf等的對比

TODO

REST與傳統(tǒng)WebServices的對比

TODO

JAX-RS與Spring MVC的對比

初步看法，摘自http://www.infoq.com/cn/news/2014/10/dubbox-open-source?utm_source=infoq&utm_medium=popular_links_homepage#theCommentsSection

謝謝，對于jax-rs和spring mvc，其實我對spring mvc的rest支持還沒有太深入的看過，說點初步想法，請大家指正：spring mvc也支持annotation的配置，其實和jax-rs看起來是非常非常類似的。我個人認為spring mvc相對更適合于面向web應用的restful服務，比如被AJAX調用，也可能輸出HTML之類的，應用中還有頁面跳轉流程之類，spring mvc既可以做好正常的web頁面請求也可以同時處理rest請求。但總的來說這個restful服務是在展現(xiàn)層或者叫web層之類實現(xiàn)的而jax-rs相對更適合純粹的服務化應用，也就是傳統(tǒng)Java EE中所說的中間層服務，比如它可以把傳統(tǒng)的EJB發(fā)布成restful服務。在spring應用中，也就把spring中充當service之類的bean直接發(fā)布成restful服務?？偟膩碚f這個restful服務是在業(yè)務、應用層或者facade層。而MVC層次和概念在這種做比如（后臺）服務化的應用中通常是沒有多大價值的。當然jax-rs的有些實現(xiàn)比如jersey，也試圖提供mvc支持，以更好的適應上面所說的web應用，但應該是不如spring mvc。在dubbo應用中，我想很多人都比較喜歡直接將一個本地的spring service bean（或者叫manager之類的）完全透明的發(fā)布成遠程服務，則這里用JAX-RS是更自然更直接的，不必額外的引入MVC概念。當然，先不討論透明發(fā)布遠程服務是不是最佳實踐，要不要添加facade之類。當然，我知道在dubbo不支持rest的情況下，很多朋友采用的架構是spring mvc restful調用dubbo (spring) service來發(fā)布restful服務的。這種方式我覺得也非常好，只是如果不修改spring mvc并將其與dubbo深度集成，restful服務不能像dubbo中的其他遠程調用協(xié)議比如webservices、dubbo rpc、hessian等等那樣，享受諸多高級的服務治理的功能，比如：注冊到dubbo的服務注冊中心，通過dubbo監(jiān)控中心監(jiān)控其調用次數(shù)、TPS、響應時間之類，通過dubbo的統(tǒng)一的配置方式控制其比如線程池大小、最大連接數(shù)等等，通過dubbo統(tǒng)一方式做服務流量控制、權限控制、頻次控制。另外spring mvc僅僅負責服務端，而在消費端，通常是用spring restTemplate，如果restTemplate不和dubbo集成，有可能像dubbo服務客戶端那樣自動或者人工干預做服務降級。如果服務端消費端都是dubbo系統(tǒng)，通過spring的rest交互，如果spring rest不深度整合dubbo，則不能用dubbo統(tǒng)一的路由分流等功能。當然，其實我個人認為這些東西不必要非此即彼的。我聽說spring創(chuàng)始人rod johnson總是愛說一句話，the customer is always right，其實與其非要探討哪種方式更好，不如同時支持兩種方式就是了，所以原來在文檔中也寫過計劃支持spring rest annoation，只是不知道具體可行性有多高。

未來

稍后可能要實現(xiàn)的功能：

• spring mvc的rest annotation支持
• 安全
• OAuth
• 異步調用
• 完善gzip
• 最大payload限制