You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@dubbo.apache.org by GitBox <gi...@apache.org> on 2018/04/11 08:12:34 UTC
[GitHub] dongxuwang commented on a change in pull request #14: DubboX New
Features
dongxuwang commented on a change in pull request #14: DubboX New Features
URL: https://github.com/apache/incubator-dubbo-docs/pull/14#discussion_r180667324
##########
File path: dubbo-user-book/rest.md
##########
@@ -0,0 +1,1209 @@
+# 在Dubbo中开发REST风格的远程调用（RESTful Remoting）
+
+**作者：沈理**
+
+**文档版权：[Apache 2.0许可证 署名-禁止演绎](http://www.apache.org/licenses/LICENSE-2.0)**
+
+完善中……
+
+> 本文篇幅较长，因为REST本身涉及面较多。另外，本文参照Spring等的文档风格，不仅仅局限于框架用法的阐述，同时也努力呈现框架的设计理念和优良应用的架构思想。
+
+> 对于想粗略了解dubbo和REST的人，只需浏览 `概述` 至 `标准Java REST API：JAX-RS简介` 几节即可。
+
+TODO 生成可点击的目录
+
+## 目录
+
+* 概述
+* REST的优点
+* 应用场景
+* 快速入门
+* 标准Java REST API：JAX-RS简介
+* REST服务提供端详解
+ * HTTP POST/GET的实现
+ * Annotation放在接口类还是实现类
+ * JSON、XML等多数据格式的支持
+ * 中文字符支持
+ * XML数据格式的额外要求
+ * 定制序列化
+ * 配置REST Server的实现
+ * 获取上下文（Context）信息
+ * 配置端口号和Context Path
+ * 配置线程数和IO线程数
+ * 配置长连接
+ * 配置最大的HTTP连接数
+ * 配置每个消费端的超时时间和HTTP连接数
+ * GZIP数据压缩
+ * 用Annotation取代部分Spring XML配置
+ * 添加自定义的Filter、Interceptor等
+ * 添加自定义的Exception处理
+ * 配置HTTP日志输出
+ * 输入参数的校验
+ * 是否应该透明发布REST服务
+* REST服务消费端详解
+ * 场景1：非dubbo的消费端调用dubbo的REST服务
+ * 场景2：dubbo消费端调用dubbo的REST服务
+ * 场景3：dubbo的消费端调用非dubbo的REST服务
+* Dubbo中JAX-RS的限制
+* REST常见问题解答（REST FAQ）
+ * Dubbo REST的服务能和Dubbo注册中心、监控中心集成吗？
+ * Dubbo REST中如何实现负载均衡和容错（failover）？
+ * JAX-RS中重载的方法能够映射到同一URL地址吗？
+ * JAX-RS中作POST的方法能够接收多个参数吗？
+* Dubbo当前体系可能的不足之处（与REST相关的）
+ * RpcContext的侵入性
+ * Protocol配置的局限性
+ * XML命名不符合spring规范
+* REST最佳实践
+* 性能基准测试
+ * 测试环境
+ * 测试脚本
+ * 测试结果
+* 扩展讨论
+ * REST与Thrift、Protobuf等的对比
+ * REST与传统WebServices的对比
+ * JAX-RS与Spring MVC的对比
+* 未来
+
+## 概述
+
+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，可以为当今多数主流的远程调用场景都带来（显著）好处：
+
+1. 显著简化企业内部的异构系统之间的（跨语言）调用。此处主要针对这种场景：dubbo的系统做服务提供端，其他语言的系统（也包括某些不基于dubbo的java系统）做服务消费端，两者通过HTTP和文本消息进行通信。即使相比Thrift、ProtoBuf等二进制跨语言调用方案，REST也有自己独特的优势（详见后面讨论）
+
+2. 显著简化对外Open API（开放平台）的开发。既可以用dubbo来开发专门的Open API应用，也可以将原内部使用的dubbo service直接“透明”发布为对外的Open REST API（当然dubbo本身未来最好可以较透明的提供诸如权限控制、频次控制、计费等诸多功能）
+
+3. 显著简化手机（平板）APP或者PC桌面客户端开发。类似于2，既可以用dubbo来开发专门针对无线或者桌面的服务器端，也可以将原内部使用的dubbo service直接”透明“的暴露给手机APP或桌面程序。当然在有些项目中，手机或桌面程序也可以直接访问以上场景2中所述的Open API。
+
+4. 显著简化浏览器AJAX应用的开发。类似于2，既可以用dubbo来开发专门的AJAX服务器端，也可以将原内部使用的dubbo service直接”透明“的暴露给浏览器中JavaScript。当然，很多AJAX应用更适合与web框架协同工作，所以直接访问dubbo service在很多web项目中未必是一种非常优雅的架构。
+
+5. 为企业内部的dubbo系统之间（即服务提供端和消费端都是基于dubbo的系统）提供一种基于文本的、易读的远程调用方式。
+
+6. 一定程度简化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来完成用户注册。
+
+首先，开发服务的接口：
+
+```java
+public class UserService {
+ void registerUser(User user);
+}
+```
+
+然后，开发服务的实现：
+
+```java
+@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配置文件中添加此服务，即完成所有服务开发工作：
+
+ ```xml
+<!-- 用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访问：
+
+```java
+@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放到服务的接口上，这两种方式是完全等价的，例如：
+
+```java
+@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中同时包含两种格式即可：
+
+```java
+@Produces({MediaType.APPLICATION_JSON, MediaType.TEXT_XML})
+User getUser(@PathParam("id") Long id);
+```
+
+或者也可以直接用字符串（还支持通配符）表示MediaType：
+
+```java
+@Produces({"application/json", "text/xml"})
+User getUser(@PathParam("id") Long id);
+```
+
+如果所有方法都支持同样类型的输入输出数据格式，则我们无需在每个方法上做配置，只需要在服务类上添加annotation即可：
+
+```java
+@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配置即可：
+
+```java
+@Produces({"application/json; charset=UTF-8", "text/xml; charset=UTF-8"})
+User getUser(@PathParam("id") Long id);
+```
+
+为了方便用户，我们在dubbo REST中直接添加了一个支持类，来定义以上的常量，可以直接使用，减少出错的可能性。
+
+```java
+@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添加如下：
+
+```java
+@XmlRootElement
+public class User implements Serializable {
+ // ...
+}
+```
+
+此外，如果service方法中的返回值是Java的 primitive类型（如int，long，float，double等），最好为它们添加一层wrapper对象，因为JAXB不能直接序列化primitive类型。
+
+例如，我们想让前述的registerUser()方法返回服务器端为用户生成的ID号：
+
+```java
+long registerUser(User user);
+```
+
+由于primitive类型不被JAXB序列化支持，所以添加一个wrapper对象：
+
+```java
+@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方法：
+
+```java
+RegistrationResult registerUser(User user);
+```
+
+这样不但能够解决XML序列化的问题，而且使得返回的数据都符合XML和JSON的规范。例如，在JSON中，返回的将是如下形式：
+
+```javascript
+{"id": 1001}
+```
+
+如果不加wrapper，JSON返回值将直接是
+
+```
+1001
+```
+
+而在XML中，加wrapper后返回值将是：
+
+```xml
+<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元素的名字：
+
+```java
+@XmlRootElement
+@XmlAccessorType(XmlAccessType.FIELD)
+public class User implements Serializable {
+
+ @XmlElement(name="username")
+ private String name;
+}
+```
+
+定制对象属性映射到JSON字段的名字：
+
+```java
+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属性来选择的：
+
+```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即可。
+
+
+```xml
+<dubbo:protocol name="rest" server="tomcat"/>
+```
+
+以上配置选用了嵌入式的tomcat来做rest server。在嵌入式tomcat上，REST的性能比jetty上要好得多（参见后面的基准测试），建议在需要高性能的场景下采用tomcat。
+
+```xml
+<dubbo:protocol name="rest" server="netty"/>
+```
+
+以上配置选用嵌入式的netty来做rest server。（TODO more contents to add）
+
+```xml
+<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应用服务器中，则建议你采用以下配置：
+
+```xml
+<dubbo:protocol name="rest" server="servlet"/>
+```
+
+通过将server设置为servlet，dubbo将采用外部应用服务器的servlet容器来做rest server。同时，还要在dubbo系统的web.xml中添加如下配置：
+
+```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：
+
+```java
+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：
+
+```java
+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。用法示例如下：
+
+```java
+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：
+
+```java
+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端口，如果想修改端口，直接配置：
+
+```xml
+<dubbo:protocol name="rest" port="8888"/>
+```
+
+另外，如前所述，我们可以用@Path来配置单个rest服务的URL相对路径。但其实，我们还可以设置一个所有rest服务都适用的基础相对路径，即java web应用中常说的context path。
+
+只需要添加如下contextpath属性即可：
+
+```xml
+<dubbo:protocol name="rest" port="8888" contextpath="services"/>
+```
+
+以前面代码为例：
+
+```java
+@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，即配置:
+
+```xml
+<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/>`完全一致：
+
+```xml
+<servlet-mapping>
+ <servlet-name>dispatcher</servlet-name>
+ <url-pattern>/services/*</url-pattern>
+</servlet-mapping>
+```
+
+### 配置线程数和IO线程数
+
+可以为rest服务配置线程池大小：
+
+```xml
+<dubbo:protocol name="rest" threads="500"/>
+```
+
+> 注意：目前线程池的设置只有当server="netty"或者server="jetty"或者server="tomcat"的时候才能生效。另外，如果server="servlet"，由于这时候启用的是外部应用服务器做rest server，不受dubbo控制，所以这里的线程池设置也无效。
+
+如果是选用netty server，还可以配置Netty的IO worker线程数：
+
+```xml
+<dubbo:protocol name="rest" iothreads="5" threads="100"/>
+```
+
+### 配置长连接
+
+Dubbo中的rest服务默认都是采用http长连接来访问，如果想切换为短连接，直接配置：
+
+```xml
+<dubbo:protocol name="rest" keepalive="false"/>
+```
+
+> 注意：这个配置目前只对server="netty"和server="tomcat"才能生效。
+
+### 配置最大的HTTP连接数
+
+可以配置服务器提供端所能同时接收的最大HTTP连接数，防止REST server被过多连接撑爆，以作为一种最基本的自我保护机制：
+
+```xml
+<dubbo:protocol name="rest" accepts="500" server="tomcat/>
+```
+
+> 注意：这个配置目前只对server="tomcat"才能生效。
+
+### 配置每个消费端的超时时间和HTTP连接数
+
+如果rest服务的消费端也是dubbo系统，可以像其他dubbo RPC机制一样，配置消费端调用此rest服务的最大超时时间以及每个消费端所能启动的最大HTTP连接数。
+
+```xml
+<dubbo:service interface="xxx" ref="xxx" protocol="rest" timeout="2000" connections="10"/>
+```
+
+当然，由于这个配置针对消费端生效的，所以也可以在消费端配置：
+
+```xml
+<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配置，例如：
+
+```java
+@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提供了一个中心点来涵盖的所有组件和配置，更一目了然，一般更便于项目长时期的维护。
Review comment:
```
-而xml对代码对侵入性更小一些
+而xml对代码的侵入性更小一些
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services