在Dubbo中开发REST风格的远程调用（RESTful Remoting）

源启智能

已于 2023-11-23 14:49:55 修改

阅读量1.5k

点赞数

CC 4.0 BY-SA版权

文章标签： dubbo restful 后端 dubbo框架

于 2017-07-28 13:51:23 首次发布

本文链接：https://blog.youkuaiyun.com/lsb2002/article/details/76252515

本文详细介绍Dubbo框架中REST服务的实现与调用方法，包括核心概念、配置选项及高级功能，帮助开发者掌握如何构建高效、灵活的RESTful API。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

1 dubbo介绍

Dubbo是一个高性能、轻量级的开源Java RPC（Remote Procedure Call）框架。由阿里巴巴开发并贡献给Apache基金会，Dubbo主要用于构建分布式服务应用。它提供了一系列服务治理和运行时特性，旨在通过高效的远程服务调用简化分布式系统的开发和维护。

Dubbo作为一个成熟的分布式服务框架，它的高性能、易用性和强大的服务治理特性使其在构建大规模分布式系统方面极具吸引力。通过简化服务的开发、部署和管理，Dubbo加速了企业级应用的开发过程。随着微服务架构的流行，Dubbo在Java分布式应用开发中的角色愈发重要。

1.1 核心特性

面向接口的远程方法调用： Dubbo基于接口定义服务，实现了透明化的远程方法调用。
智能负载均衡：支持多种负载均衡策略，如随机、轮询、最少活跃调用等。
服务注册与发现：提供服务注册与发现的机制，支持多种注册中心，如ZooKeeper、Nacos等。
高性能：优化了通信协议和序列化机制，提供高性能的服务调用。
服务治理：包括服务的路由、降级、限流等高级特性，便于服务的管理和维护。
插件化设计：提供丰富的扩展接口，允许自定义组件以满足特定需求。
监控与管理：提供监控服务的能力，能够收集服务调用的详细信息，用于性能分析和问题定位。

1.2 架构和组件

Provider（服务提供方）：发布服务到注册中心，并接收并处理消费者的请求。
Consumer（服务消费方）：从注册中心订阅服务，并进行远程调用。
Registry（注册中心）：服务注册和发现的媒介，提供服务的注册与查询功能。
Monitor（监控中心）：收集调用次数和调用时间等数据，用于性能监控。
Container（容器）：服务运行容器，管理服务的生命周期。
Protocol（通信协议）：定义服务之间通信的协议，如Dubbo协议、HTTP协议等。
Filter（过滤器）：对服务请求和响应进行拦截，实现诸如日志记录、权限校验等功能。

1.3 使用Dubbo

定义服务接口：开发者首先定义服务接口，并实现这些接口。
配置服务提供者：配置服务提供者，将服务接口实现发布到注册中心。
配置服务消费者：配置服务消费者，从注册中心订阅所需服务，并进行远程调用。
集群部署： Dubbo支持集群部署，提高服务的可用性和可靠性。

1.4 性能优化

协议选择和优化：根据服务特性选择合适的通信协议，并对协议参数进行调优。
服务拆分和模块化：将大型服务拆分为更小的模块，提高服务的可维护性和扩展性。
负载均衡策略：选择合适的负载均衡策略，优化资源的使用和服务的响应时间。
连接数和线程池管理：合理配置连接数和线程池，提高系统的并发处理能力。

1.5 安全性和事务

访问控制：提供了基于黑白名单的访问控制机制。
服务降级：在系统负载过高时，可以对服务进行降级处理。
分布式事务支持：虽然Dubbo本身不处理分布式事务，但可以与分布式事务解决方案集成。

1.6 社区和生态系统

开源社区： Dubbo拥有一个活跃的开源社区，提供持续的更新和支持。
与其他框架的集成：可以与Spring、Spring Boot等流行框架无缝集成。
丰富的扩展：社区提供了大量的扩展，如限流、降级、路由等。

2 dubbo中的REST调用

借用Java过去最流行的宣传语，为dubbo添加REST调用后，可以实现服务的”一次编写，到处访问“，理论上可以面向全世界开放，从而真正实现比较理想化的面向服务架构（SOA）。

在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@Path@Path("users")：指定访问UserService的URL相对路径是/users，即http://localhost:8080/users
@Path@Path@Path("register")：指定访问registerUser()方法的URL相对路径是/register，再结合上一个@Path@Path@Path为UserService指定的路径，则调用UserService.register()的完整路径为http://localhost:8080/users/register
@POST@POST@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" />

2.1 REST服务提供端详解

2.1.1 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@GET@GET：指定用HTTP GET方法访问
@Path@Path@Path("{id : \d+}")：根据上面的功能需求，访问getUser()的URL应当是“http://localhost:8080/users/ + 任意数字"，并且这个数字要被做为参数传入getUser()方法。这里的annotation配置中，@Path@Path@Path中间的{id: xxx}指定URL相对路径中包含了名为id参数，而它的值也将被自动传递给下面用@PathParam("id")修饰的方法参数id。{id:后面紧跟的\d+是一个正则表达式，指定了id参数必须是数字。
@Produces({MediaType.APPLICATION_JSON})：指定getUser()输出JSON格式的数据。框架会自动将User对象序列化为JSON数据。

2.1.1 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被直接忽略。

2.1.3 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才能生效。

2.1.4 中文字符支持

为了在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);

2.1.5 XML数据格式的额外要求

由于JAX-RS的实现一般都用标准的JAXB（Java API for XML Binding）来序列化和反序列化XML格式数据，所以我们需要为每一个要用XML传输的对象添加一个类级别的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序列化的问题，而且使得返回的数据都符合XML和JSON的规范。例如，在JSON中，返回的将是如下形式：

{"id": 1001}

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

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

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

这种wrapper对象其实利用所谓Data Transfer Object（DTO）模式，采用DTO还能对传输数据做更多有用的定制。

2.1.6 定制序列化

如上所述，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;
}

2.1.7 配置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。

<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等），另外有时也便于在应用服务器做统一管理、监控等等。

2.1.8 获取上下文（Context）信息

在远程调用中，值得获取的上下文信息可能有很多种，这里特别以获取客户端IP为例。

在dubbo的REST中，我们有两种方式获取客户端IP。

第一种方式，用JAX-RS标准的@Context@Context @Contextannotation：

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@Context@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。

2.1.9 配置端口号和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>

2.1.10 配置线程数和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"/>

2.1.11 配置长连接

Dubbo中的rest服务默认都是采用http长连接来访问，如果想切换为短连接，直接配置：

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

注意：这个配置目前只对server="netty"和server="tomcat"才能生效。

2.1.12 配置最大的HTTP连接数

可以配置服务器提供端所能同时接收的最大HTTP连接数，防止REST server被过多连接撑爆，以作为一种最基本的自我保护机制：

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

注意：这个配置目前只对server="tomcat"才能生效。

2.1.13 配置每个消费端的超时时间和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控制。

2.1.14 用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提供了一个中心点来涵盖的所有组件和配置，更一目了然，一般更便于项目长时期的维护。

当然，选择哪种配置方式没有绝对的优劣，和个人的偏好也不无关系。

2.1.15 添加自定义的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());
    } 
}

2.1.16 添加自定义的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"/>

2.1.17 配置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请求解析时产生额外的开销，因为需要建立额外的内存缓冲区来为日志的输出做数据准备。

2.1.18 输入参数的校验

dubbo的rest支持采用Java标准的bean validation annotation（JSR 303)来做输入校验

为了和其他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"/>

2.1.20 是否应该透明发布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的角色。这种情况下，在添加REST之后，如果你再额外添加与REST相关的Facade和DTO，就相当于对原有代码对再一次包装，即形成如下调用链：

RestFacade/RestDTO -> Facade/DTO -> Service

这种体系比较繁琐，数据转换之类的工作量也不小，所以一般应尽量避免如此。

2.2 REST服务消费端详解

这里我们用三种场景来分别讨论：

非dubbo的消费端调用dubbo的REST服务（non-dubbo --> dubbo）
dubbo消费端调用dubbo的REST服务（dubbo --> dubbo）
dubbo的消费端调用非dubbo的REST服务（dubbo --> non-dubbo）

2.2.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.2.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。

2.2.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中也必须添加上（除非你在每个服务接口的@Path
annotation中都带上context path），例如上面的/services/。同时这里的services后面必须带上/，这样才能使dubbo正常工作。

另外，这里依然可以配置客户端可启动的最大连接数和超时时间：

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