dubbo支持多種遠程調用方式,例如dubbo RPC(二進位序列化 + tcp協議)、http invoker(二進位序列化 + http協議,至少在開源版本沒發現對文本序列化的支持)、hessian(二進位序列化 + http協議)、WebServices (文本序列化 + http協議)等等,... ...
概述
dubbo支持多種遠程調用方式,例如dubbo RPC(二進位序列化 + tcp協議)、http invoker(二進位序列化 + http協議,至少在開源版本沒發現對文本序列化的支持)、hessian(二進位序列化 + http協議)、WebServices (文本序列化 + http協議)等等,但缺乏對當今特別流行的REST風格遠程調用(文本序列化 + http協議)的支持。
有鑒於此,我們基於標準的Java REST API——JAX-RS 2.0(Java API for RESTful Web Services的簡寫),為dubbo提供了接近透明的REST調用支持。由於完全相容Java標準API,所以為dubbo開發的所有REST服務,未來脫離dubbo或者任何特定的REST底層實現一般也可以正常運行。
特別值得指出的是,我們並不需要完全嚴格遵守REST的原始定義和架構風格。即使著名的Twitter REST API也會根據情況做適度調整,而不是機械的遵守原始的REST風格。
附註:我們將這個功能稱之為REST風格的遠程調用,即RESTful Remoting(抽象的遠程處理或者調用),而不是叫RESTful RPC(具體的遠程“過程”調用),是因為REST和RPC本身可以被認為是兩種不同的風格。在dubbo的REST實現中,可以說有兩個面向,其一是提供或消費正常的REST服務,其二是將REST作為dubbo RPC體系中一種協議實現,而RESTful Remoting同時涵蓋了這個面向。
REST的優點
以下摘自維基百科:
-
可更高效利用緩存來提高響應速度
-
通訊本身的無狀態性可以讓不同的伺服器的處理一系列請求中的不同請求,提高伺服器的擴展性
-
瀏覽器即可作為客戶端,簡化軟體需求
-
相對於其他疊加在HTTP協議之上的機制,REST的軟體依賴性更小
-
不需要額外的資源發現機制
-
在軟體技術演進中的長期的相容性更好
這裡我還想特別補充REST的顯著優點:基於簡單的文本格式消息和通用的HTTP協議,使它具備極廣的適用性,幾乎所有語言和平臺都對它提供支持,同時其學習和使用的門檻也較低。
應用場景
正是由於REST在適用性方面的優點,所以在dubbo中支持REST,可以為當今多數主流的遠程調用場景都帶來(顯著)好處:
-
顯著簡化企業內部的異構系統之間的(跨語言)調用。此處主要針對這種場景:dubbo的系統做服務提供端,其他語言的系統(也包括某些不基於dubbo的java系統)做服務消費端,兩者通過HTTP和文本消息進行通信。即使相比Thrift、ProtoBuf等二進位跨語言調用方案,REST也有自己獨特的優勢(詳見後面討論)
-
顯著簡化對外Open API(開放平臺)的開發。既可以用dubbo來開發專門的Open API應用,也可以將原內部使用的dubbo service直接“透明”發佈為對外的Open REST API(當然dubbo本身未來最好可以較透明的提供諸如許可權控制、頻次控制、計費等諸多功能)
-
顯著簡化手機(平板)APP或者PC桌面客戶端開發。類似於2,既可以用dubbo來開發專門針對無線或者桌面的伺服器端,也可以將原內部使用的dubbo service直接”透明“的暴露給手機APP或桌面程式。當然在有些項目中,手機或桌面程式也可以直接訪問以上場景2中所述的Open API。
-
顯著簡化瀏覽器AJAX應用的開發。類似於2,既可以用dubbo來開發專門的AJAX伺服器端,也可以將原內部使用的dubbo service直接”透明“的暴露給瀏覽器中JavaScript。當然,很多AJAX應用更適合與web框架協同工作,所以直接訪問dubbo service在很多web項目中未必是一種非常優雅的架構。
-
為企業內部的dubbo系統之間(即服務提供端和消費端都是基於dubbo的系統)提供一種基於文本的、易讀的遠程調用方式。
-
一定程度簡化dubbo系統對其它異構系統的調用。可以用類似dubbo的簡便方式“透明”的調用非dubbo系統提供的REST服務(不管服務提供端是在企業內部還是外部)
需要指出的是,我認為1~3是dubbo的REST調用最有價值的三種應用場景,並且我們為dubbo添加REST調用,其最主要到目的也是面向服務的提供端,即開發REST服務來提供給非dubbo的(異構)消費端。
借用Java過去最流行的宣傳語,為dubbo添加REST調用後,可以實現服務的”一次編寫,到處訪問“,理論上可以面向全世界開放,從而真正實現比較理想化的面向服務架構(SOA)。
當然,傳統的WebServices(WSDL/SOAP)也基本同樣能滿足以上場景(除了場景4)的要求(甚至還能滿足那些需要企業級特性的場景),但由於其複雜性等問題,現在已經越來越少被實際採用了。
快速入門
在dubbo中開發一個REST風格的服務會比較簡單,下麵以一個註冊用戶的簡單服務為例說明。
這個服務要實現的功能是提供如下URL(註:這個URL不是完全符合REST的風格,但是更簡單實用):
http://localhost:8080/users/register
而任何客戶端都可以將包含用戶信息的JSON字元串POST到以上URL來完成用戶註冊。
首先,開發服務的介面:
public class UserService { void registerUser(User user); }
然後,開發服務的實現:
@Path("users")public class UserServiceImpl implements UserService { @POST @Path("register") @Consumes({MediaType.APPLICATION_JSON}) public void registerUser(User user) { // save the user... } }
上面的服務實現代碼非常簡單,但是由於REST服務是要被髮布到特定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格式的數據。REST框架會自動將JSON數據反序列化為User對象
最後,在spring配置文件中添加此服務,即完成所有服務開發工作:
<!-- 用rest協議在8080埠暴露服務 --><dubbo:protocol name="rest" port="8080"/><!-- 聲明需要暴露的服務介面 --><dubbo:service interface="xxx.UserService" ref="userService"/><!-- 和本地bean一樣實現服務 --><bean id="userService" class="xxx.UserServiceImpl" />
標準Java REST API:JAX-RS簡介
JAX-RS是標準的Java REST API,得到了業界的廣泛支持和應用,其著名的開源實現就有很多,包括Oracle的Jersey,RedHat的RestEasy,Apache的CXF和Wink,以及restlet等等。另外,所有支持JavaEE 6.0以上規範的商用JavaEE應用伺服器都對JAX-RS提供了支持。因此,JAX-RS是一種已經非常成熟的解決方案,並且採用它沒有任何所謂vendor lock-in的問題。
JAX-RS在網上的資料非常豐富,例如下麵的入門教程:
-
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實現所涉及的版本。
REST服務提供端詳解
下麵我們擴充“快速入門”中的UserService,進一步展示在dubbo中REST服務提供端的開發要點。
HTTP POST/GET的實現
REST服務中雖然建議使用HTTP協議中四種標準方法POST、DELETE、PUT、GET來分別實現常見的“增刪改查”,但實際中,我們一般情況直接用POST來實現“增改”,GET來實現“刪查”即可(DELETE和PUT甚至會被一些防火牆阻擋)。
前面已經簡單演示了POST的實現,在此,我們為UserService添加一個獲取註冊用戶資料的功能,來演示GET的實現。
這個功能就是要實現客戶端通過訪問如下不同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路徑中包含查詢參數的形式(http://localhost:8080/users/1001) 更符合REST的一般習慣,所以更推薦大家來使用。下麵我們就為UserService添加一個getUser()方法來實現這種形式的URL訪問:
@GET@Path("{id : \\d+}") @Produces({MediaType.APPLICATION_JSON})public User getUser(@PathParam("id") Long id) { // ...}
@GET:指定用HTTP GET方法訪問
@Path("{id : \d+}"):根據上面的功能需求,訪問getUser()的URL應當是“http://localhost:8080/users/ + 任意數字",並且這個數字要被做為參數傳入getUser()方法。 這裡的annotation配置中,@Path中間的{id: xxx}指定URL相對路徑中包含了名為id參數,而它的值也將被自動傳遞給下麵用@PathParam("id")修飾的方法參數id。{id:後面緊跟的\d+是一個正則表達式,指定了id參數必須是數字。
@Produces({MediaType.APPLICATION_JSON}):指定getUser()輸出JSON格式的數據。框架會自動將User對象序列化為JSON數據。
Annotation放在介面類還是實現類
在Dubbo中開發REST服務主要都是通過JAX-RS的annotation來完成配置的,在上面的示例中,我們都是將annotation放在服務的實現類中。但其實,我們完全也可以將annotation放到服務的介面上,這兩種方式是完全等價的,例如:
@Path("users")public interface UserService { @GET @Path("{id : \\d+}") @Produces({MediaType.APPLICATION_JSON}) User getUser(@PathParam("id") Long id); }
在一般應用中,我們建議將annotation放到服務實現類,這樣annotation和java實現代碼位置更接近,更便於開發和維護。另外更重要的是,我們一般傾向於避免對介面的污染,保持介面的純凈性和廣泛適用性。
但是,如後文所述,如果我們要用dubbo直接開發的消費端來訪問此服務,則annotation必須放到介面上。
如果介面和實現類都同時添加了annotation,則實現類的annotation配置會生效,介面上的annotation被直接忽略。
JSON、XML等多數據格式的支持
在dubbo中開發的REST服務可以同時支持傳輸多種格式的數據,以給客戶端提供最大的靈活性。其中我們目前對最常用的JSON和XML格式特別添加了額外的功能。
比如,我們要讓上例中的getUser()方法支持分別返回JSON和XML格式的數據,只需要在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);
如果所有方法都支持同樣類型的輸入輸出數據格式,則我們無需在每個方法上做配置,只需要在服務類上添加annotation即可:
@Path("users") @Consumes({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) @Produces({MediaType.APPLICATION_JSON, MediaType.TEXT_XML})public class UserServiceImpl implements UserService { // ...}
在一個REST服務同時對多種數據格式支持的情況下,根據JAX-RS標準,一般是通過HTTP中的MIME header(content-type和accept)來指定當前想用的是哪種格式的數據。
但是在dubbo中,我們還自動支持目前業界普遍使用的方式,即用一個URL尾碼(.json和.xml)來指定想用的數據格式。例如,在添加上述annotation後,直接訪問http://localhost:8888/users/1001.json則表示用json格式,直接訪問http://localhost:8888/users/1002.xml則表示用xml格式,比用HTTP Header更簡單直觀。Twitter、微博等的REST API都是採用這種方式。
如果你既不加HTTP header,也不加尾碼,則dubbo的REST會優先啟用在以上annotation定義中排位最靠前的那種數據格式。
註意:這裡要支持XML格式數據,在annotation中既可以用MediaType.TEXT_XML,也可以用MediaType.APPLICATION_XML,但是TEXT_XML是更常用的,並且如果要利用上述的URL尾碼方式來指定數據格式,只能配置為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數據格式的額外要求
由於JAX-RS的實現一般都用標準的JAXB(Java API for XML Binding)來序列化和反序列化XML格式數據,所以我們需要為每一個要用XML傳輸的對象添加一個類級別的JAXB annotation,否則序列化將報錯。例如為getUser()中返回的User添加如下:
@XmlRootElementpublic class User implements Serializable { // ...}
此外,如果service方法中的返回值是Java的 primitive類型(如int,long,float,double等),最好為它們添加一層wrapper對象,因為JAXB不能直接序列化primitive類型。
例如,我們想讓前述的registerUser()方法返回伺服器端為用戶生成的ID號:
long registerUser(User user);
由於primitive類型不被JAXB序列化支持,所以添加一個wrapper對象:
@XmlRootElementpublic 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序列化的問題,而且使得返回的數據都符合XML和JSON的規範。例如,在JSON中,返回的將是如下形式:
{"id": 1001}
如果不加wrapper,JSON返回值將直接是
1001
而在XML中,加wrapper後返回值將是:
<registrationResult> <id>1002</id> </registrationResult>
這種wrapper對象其實利用所謂Data Transfer Object(DTO)模式,採用DTO還能對傳輸數據做更多有用的定製。
定製序列化
如上所述,REST的底層實現會在service的對象和JSON/XML數據格式之間自動做序列化/反序列化。但有些場景下,如果覺得這種自動轉換不滿足要求,可以對其做定製。
Dubbo中的REST實現是用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的實現
目前在dubbo中,我們支持5種嵌入式rest server的實現,並同時支持採用外部應用伺服器來做rest server的實現。rest server的實現是通過如下server這個XML屬性來選擇的:
<dubbo:protocol name="rest" server="jetty"/>
以上配置選用了嵌入式的jetty來做rest server,同時,如果不配置server屬性,rest協議預設也是選用jetty。jetty是非常成熟的java servlet容器,並和dubbo已經有較好的集成(目前5種嵌入式server中只有jetty和後面所述的tomcat、tjws,與dubbo監控系統等完成了無縫的集成),所以,如果你的dubbo系統是單獨啟動的進程,你可以直接預設採用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實現非常輕量級,非常方便在集成測試中快速啟動使用,當然也可以在負荷不高的生產環境中使用。 註:tjws目前已經被deprecated掉了,因為它不能很好的和servlet 3.1 API工作。
如果你的dubbo系統不是單獨啟動的進程,而是部署到了Java應用伺服器中,則建議你採用以下配置:
<dubbo:protocol name="rest" server="servlet"/>
通過將server設置為servlet,dubbo將採用外部應用伺服器的servlet容器來做rest server。同時,還要在dubbo系統的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>com.alibaba.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>com.alibaba.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等),另外有時也便於在應用伺服器做統一管理、監控等等。
獲取上下文(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()的一個方法參數後,就可以將當前的HttpServletRequest註入進來,然後直接調用servlet api獲取IP。
註意:這種方式只能在設置server="tjws"或者server="tomcat"或者server="jetty"或者server="servlet"的時候才能工作,因為只有這幾種REST server的實現才提供了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也可以運行,請選擇第一種方式。如果你想要更優雅的服務介面定義,請選用第二種方式。
此外,在最新的dubbo rest中,還支持通過RpcContext來獲取HttpServletRequest和HttpServletResponse,以提供更大的靈活性來方便用戶實現某些複雜功能,比如在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()); }
註意:為了保持協議的中立性,RpcContext.getRequest()和RpcContext.getResponse()返回的僅僅是一個Object類,而且可能為null。所以,你必須自己做null和類型的檢查。
註意:只有在設置server="jetty"或者server="tomcat"或者server="servlet"的時候,你才能通過以上方法正確的得到HttpServletRequest和HttpServletResponse,因為只有這幾種server實現了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協議預設將採用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... } }
現在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>
配置線程數和IO線程數
可以為rest服務配置線程池大小:
<dubbo:protocol name="rest" threads="500"/>
註意:目前線程池的設置只有當server="netty"或者server="jetty"或者server="tomcat"的時候才能生效。另外,如果server="servlet",由於這時候啟用的是外部應用伺服器做rest server,不受dubbo控制,所以這裡的線程池設置也無效。
如果是選用netty server,還可以配置Netty的IO worker線程數:
<dubbo:protocol name="rest" iothreads="5" threads="100"/>
配置長連接
Dubbo中的rest服務預設都是採用http長連接來訪問,如果想切換為短連接,直接配置:
<dubbo:protocol name="rest" keepalive="false"/>
註意:這個配置目前只對server="netty"和server="tomcat"才能生效。
配置最大的HTTP連接數
可以配置伺服器提供端所能同時接收的最大HTTP連接數,防止REST server被過多連接撐爆,以作為一種最基本的自我保護機制:
<dubbo:protocol name="rest" accepts="500" server="tomcat/>
註意:這個配置目前只對server="tomcat"才能生效。
配置每個消費端的超時時間和HTTP連接數
如果rest服務的消費端也是dubbo系統,可以像其他dubbo RPC機制一樣,配置消費端調用此rest服務的最大超時時間以及每個消費端所能啟動的最大HTTP連接數。
<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實現者一開始就思考Provider服務特點、服務質量的問題。”
註意:如果dubbo的REST服務是發佈給非dubbo的客戶端使用,則這裡
<dubbo:service/>
上的配置完全無效,因為這種客戶端不受dubbo控制。
GZIP數據壓縮
Dubbo的REST支持用GZIP壓縮請求和響應的數據,以減少網路傳輸時間和帶寬占用,但這種方式會也增加CPU開銷。
TODO more contents to add
用Annotation取代部分Spring XML配置
以上所有的討論都是基於dubbo在spring中的xml配置。但是,dubbo/spring本身也支持用annotation來作配置,所以我們也可以按dubbo官方文檔中的步驟,把相關annotation加到REST服務的實現中,取代一些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的配置更簡單更精確,經常也更便於維護(當然現代IDE都可以在xml中支持比如類名重構,所以就這裡的特定用例而言,xml的維護性也很好)。而xml對代碼對侵入性更小一些,尤其有利於動態修改配置,特別是比如你要針對單個服務配置連接超時時間、每客戶端最大連接數、集群策略、權重等等。另外,特別對複雜應用或者模塊來說,xml提供了一個中心點來涵蓋的所有組件和配置,更一目瞭然,一般更便於項目長時期的維護。
當然,選擇哪種配置方式沒有絕對的優劣,和個人的偏好也不無關係。
添加自定義的Filter、Interceptor等
Dubbo的REST也支持JAX-RS標準的Filter和Interceptor,以方便對REST的請求與響應過程做定製化的攔截處理。
其中,Filter主要用於訪問和設置HTTP請求和響應的參數、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主要用於訪問和修改輸入與輸出位元組流,例如,手動添加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會自動發現並啟用它們。而在dubbo中,我們是通過添加XML配置的方式來註冊Filter和Interceptor:
<dubbo:protocol name="rest" port="8888" extension="xxx.TraceInterceptor, xxx.TraceFilter"/>
在此,我們可以將Filter、Interceptor和DynamicFuture這三種類型的對象都添加到extension屬性上,多個之間用逗號分隔。(DynamicFuture是另一個介面,可以方便我們更動態的啟用Filter和Interceptor,感興趣請自行google。)
當然,dubbo自身也支持Filter的概念,但我們這裡討論的Filter和Interceptor更加接近協議實現的底層,相比dubbo的filter,可以做更底層的定製化。
註:這裡的XML屬性叫extension,而不是叫interceptor或者filter,是因為除了Interceptor和Filter,未來我們還會添加更多的擴展類型。
如果REST的消費端也是dubbo系統(參見下文的討論),則也可以用類似方式為消費端配置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發生後應該返回的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="com.alibaba.dubbo.rpc.protocol.rest.support.LoggingFilter"/>
然後配置在logging配置中至少為com.alibaba.dubbo.rpc.protocol.rest.support打開INFO級別日誌輸出,例如,在log4j.xml中配置:
<logger name="com.alibaba.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請求解析時產生額外的開銷,因為需要建立額外的記憶體緩衝區來為日誌的輸出做數據準備。
輸入參數的校驗
dubbo的rest支持採用Java標準的bean validation annotation(JSR 303)來做輸入校驗http://beanvalidation.org/
為了和其他dubbo遠程調用協議保持一致,在rest中作校驗的annotation必須放在服務的介面上,例如:
public interface UserService { User getUser(@Min(value=1L, message="User ID must be greater than 1") Long id); }
當然,在很多其他的bean validation的應用場景都是將annotation放到實現類而不是介面上。把annotation放在介面上至少有一個好處是,dubbo的客戶端可以共用這個介面的信息,dubbo甚至不需要做遠程調用,在本地就可以完成輸入校驗。
然後按照dubbo的標準方式在XML配置中打開驗證:
<dubbo:service interface=xxx.UserService" ref="userService" protocol="rest" validation="true"/>
在dubbo的其他很多遠程調用協議中,如果輸入驗證出錯,是直接將RpcException
拋向客戶端,而在rest中由於客戶端經常是非dubbo,甚至非java的系統,所以不便直接拋出Java異常。因此,目前我們將校驗錯誤以XML的格式返回:
<violationReport> <constraintViolations> <path>getUserArgument0</path> <message>User ID must be greater than 1</message> <value>0</value> </constraintViolations> </violationReport>
稍後也會支持其他數據格式的返回值。至於如何對驗證錯誤消息作國際化處理,直接參考bean validation的相關文檔即可。
如果你認為預設的校驗錯誤返回格式不符合你的要求,可以如上面章節所述,添加自定義的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"/>
是否應該透明發佈REST服務
Dubbo的REST調用和dubbo中其它某些RPC不同的是,需要在服務代碼中添加JAX-RS的annotation(以及JAXB、Jackson的annotation),如果你覺得這些annotation一定程度“污染”了你的服務代碼,你可以考慮編寫額外的Facade和DTO類,在Facade和DTO上添加annotation,而Facade將調用轉發給真正的服務實現類。當然事實上,直接在服務代碼中添加annotation基本沒有任何負面作用,而且這本身是Java EE的標準用法,另外JAX-RS和JAXB的annotation是屬於java標準,比我們經常使用的spring、dubbo等等annotation更沒有vendor lock-in的問題,所以一般沒有必要因此而引入額外對象。
另外,如果你想用前述的@Context annotation,通過方法參數註入HttpServletRequest(如public User getUser(@PathParam("id") Long id, @Context HttpServletRequest request)
),這時候由於改變了服務的方法簽名,並且HttpServletRequest是REST特有的參數,如果你的服務要支持多種RPC機制的話,則引入額外的Facade類是比較適當的。
當然,在沒有添加REST調用之前,你的服務代碼可能本身已經就充當了Facade和DTO的角色(至於為什麼有些場景需要這些角色,有興趣可參考微觀SOA:服務設計原則及其實踐方式)。這種情況下,在添加REST之後,如果你再額外添加與REST相關的Facade和DTO,就相當於對原有代碼對再一次包裝,即形成如下調用鏈:
RestFacade/RestDTO -> Facade/DTO -> Service
這種體系比較繁瑣,數據轉換之類的工作量也不小,所以一般應儘量避免如此。
REST服務消費端詳解
這裡我們用三種場景來分別討論:
-
非dubbo的消費端調用dubbo的REST服務(non-dubbo --> dubbo)
-
dubbo消費端調用dubbo的REST服務 (dubbo --> dubbo)
-
dubbo的消費端調用非dubbo的REST服務 (dubbo --> non-dubbo)
場景1:非dubbo的消費端調用dubbo的REST服務
這種場景的客戶端與dubbo本身無關,直接選用相應語言和框架中合適的方式即可。
如果是還是java的客戶端(但沒用dubbo),可以考慮直接使用標準的JAX-RS Client API或者特定REST實現的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(); // 在真正開發中不要每次關閉client,比如HTTP長連接是由client持有的}
上面代碼片段中的User和RegistrationResult類都是消費端自己編寫的,JAX-RS Client API會自動對它們做序列化/反序列化。
當然,在java中也可以直接用自己熟悉的比如HttpClient,FastJson,XStream等等各種不同技術來實現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配置信息,並據之做遠程調用:
@Path("users")public interface UserService { @GET @Path("{id : \\d+}") @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) User getUser(@PathParam("id") Long id); }
如果服務介面的annotation中配置了多種數據格式,這裡由於兩端都是dubbo系統,REST的大量細節被屏蔽了,所以不存在用前述URL尾碼之類選擇數據格式的可能。目前在這種情況下,排名最靠前的數據格式將直接被使用。
因此,我們建議你在定義annotation的時候最好把最合適的數據格式放到前面,比如以上我們是把json放在xml前面,因為json的傳輸性能優於xml。
場景3:dubbo的消費端調用非dubbo的REST服務
這種場景下,可以直接用場景1中描述的Java的方式來調用REST服務。但其實也可以採用場景2中描述的方式,即更透明的調用REST服務,即使這個服務並不是dubbo提供的。
如果用場景2的方式,由於這裡REST服務並非dubbo提供,一般也就沒有前述的共用的Java服務介面,所以在此我們需要根據外部REST服務的情況,自己來編寫Java介面以及相應參數類,並添加JAX-RS、JAXB、Jackson等的annotation,dubbo的REST底層實現會據此去自動生成請求消息,自動解析響應消息等等,從而透明的做遠程調用。或者這種方式也可以理解為,我們嘗試用JAX-RS的方式去仿造實現一遍外部的REST服務提供端,然後把寫成服務介面放到客戶端來直接使用,dubbo的REST底層實現就能像調用dubbo的REST服務一樣調用其他REST服務。
例如,我們要調用如下的外部服務
http://api.foo.com/services/users/1001 http://api.foo.com/services/users/1002
獲取不同ID的用戶資料,返回格式是JSON
{ "id": 1001, "name": "Larry"}
我們可根據這些信息,編寫服務介面和參數類即可:
@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/"/>
註意:這裡協議必須用rest://而不是http://之類。如果外部的REST服務有context path,則在url中也必須添加上(除非你在每個服務介面的@Pathannotation中都帶上context path),例如上面的/services/。同時這裡的services後面必須帶上/,這樣才能使dubbo正常工作。
另外,這裡依然可以配置客戶端可啟動的最大連接數和超時時間:
<dubbo:reference id="userService" interface="xxx.UserService" url="rest://api.foo.com/services/" timeout="2000" connections="10"/>
Dubbo中JAX-RS的限制
Dubbo中的REST開發是完全相容標準JAX-RS的,但其支持的功能目前是完整JAX-RS的一個子集,部分因為它要受限於dubbo和spring的特定體系。
在dubbo中使用的JAX-RS的局限包括但不限於:
-
服務實現只能是singleton的,不能支持per-request scope和per-lookup scope
-
不支持用@Context annotation對服務的實例欄位註入 ServletConfig、ServletContext、HttpServletRequest、HttpServletResponse等等,但可以支持對服務方法參數的註入。但對某些特定REST server實現,(祥見前面的敘述),也不支持對服務方法參數的註入。
REST常見問題解答(REST FAQ)
Dubbo REST的服務能和Dubbo註冊中心、監控中心集成嗎?
可以的,而且是自動集成的,也就是你在dubbo中開發的所有REST服務都會自動註冊到服務冊中心和監控中心,可以通過它們做管理。
但是,只有當REST的消費端也是基於dubbo的時候,註冊中心中的許多服務治理操作才能完全起作用。而如果消費端是非dubbo的,自然不受註冊中心管理,所以其中很多操作是不會對消費端起作用的。
Dubbo REST中如何實現負載均衡和容錯(failover)?
如果dubbo REST的消費端也是dubbo的,則Dubbo REST和其他dubbo遠程調用協議基本完全一樣,由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的方法能夠接收多個參數嗎?
http://stackoverflow.com/questions/5553218/jax-rs-post-multiple-objects
Dubbo當前體系的不足之處(與REST相關的)
我認為dubbo當前體系中顯然也有不少不足之處,這裡列出幾個與REST有關的、並影響用戶使用的問題(不包括內部實現的問題),供參考評論,為下一步重構作准備。
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等等(當然,有的是條件所限不支持,有的是根本沒有必要支持)。這給用戶的使用徒增很多困惑,用戶也並不知道有些屬性(比如做性能調優)添加了實際上是不起作用的。
另一方面,各種遠程調用方式往往有大量自己獨特的配置需要,特別是我們逐步為每種遠程調用方式都添加更豐富、更高級的功能,這就不可避免的擴展<protocol/>
中的屬性(例如目前我們在REST中已經添加了keepalive和extension兩個屬性),到最後會導致<protocol/>
臃腫不堪,用戶的使用也更加困惑。
當然,dubbo中有一種擴展<protocol/>
的方式是用<dubbo:parameter/>
,但這種方式顯然很有局限性,而且用法複雜,缺乏schema校驗。
所以,最好的方式是為每種遠程調用方式設置自己的protocol元素,比如<protocol-dubbo/>
,<protocol-rest/>
等等,每種元素用XML schema規定自己的屬性(當然屬性在各種遠程調用方式之間能通用是最好的)。
如此一來,例如前面提到過的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規範
dubbo的XML配置中大量命名都不符合spring規範,比如:
<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的命名規範。
REST最佳實踐
TODO
性能基準測試
測試環境
粗略如下:
-
兩台獨立伺服器
-
4核Intel(R) Xeon(R) CPU E5-2603 0 @ 1.80GHz
-
8G記憶體
-
伺服器之間網路通過百兆交換機
-
CentOS 5
-
JDK 7
-
Tomcat 7
-
JVM參數-server -Xms1g -Xmx1g -XX:PermSize=64M -XX:+UseConcMarkSweepGC
測試腳本
和dubbo自身的基準測試保持接近:
10個併發客戶端持續不斷發出請求:
-
傳入嵌套複雜對象(但單個數據量很小),不做任何處理,原樣返回
-
傳入50K字元串,不做任何處理,原樣返回(TODO:結果尚未列出)
進行5分鐘性能測試。(引用dubbo自身測試的考慮:“主要考察序列化和網路IO的性能,因此服務端無任何業務邏輯。取10併發是考慮到http協議在高併發下對CPU的使用率較高可能會先打到瓶頸。”)
測試結果
下麵的結果主要對比的是REST和dubbo RPC兩種遠程調用方式,並對它們作不同的配