协议参考手册 on Apache Dubbo

dubbo 协议

Mon, 01 Jan 0001 00:00:00 +0000

Dubbo 缺省协议采用单一长连接和 NIO 异步通讯，适合于小数据量大并发的服务调用，以及服务消费者机器数远大于服务提供者机器数的情况。

反之，Dubbo 缺省协议不适合传送大数据量的服务，比如传文件，传视频等，除非请求量很低。

Transporter: mina, netty, grizzy
Serialization: dubbo, hessian2, java, json
Dispatcher: all, direct, message, execution, connection
ThreadPool: fixed, cached

特性

缺省协议，使用基于 netty 3.2.5.Final 和 hessian2 3.2.1-fixed-2(Alibaba embed version) 的 tbremoting 交互。

连接个数：单连接
连接方式：长连接
传输协议：TCP
传输方式：NIO 异步传输
序列化：Hessian 二进制序列化
适用范围：传入传出参数数据包较小（建议小于100K），消费者比提供者个数多，单一消费者无法压满提供者，尽量不要用 dubbo 协议传输大文件或超大字符串。
适用场景：常规远程服务方法调用

约束

参数及返回值需实现 Serializable 接口
参数及返回值不能自定义实现 List, Map, Number, Date, Calendar 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。
Hessian 序列化，只传成员属性值和值的类型，不传方法或静态变量，兼容情况 ¹²：

数据通讯	情况	结果
A->B	类A多一种属性（或者说类B少一种属性）	不抛异常，A多的那个属性的值，B没有，其他正常
A->B	枚举A多一种枚举（或者说B少一种枚举），A使用多出来的枚举进行传输	抛异常
A->B	枚举A多一种枚举（或者说B少一种枚举），A不使用多出来的枚举进行传输	不抛异常，B正常接收数据
A->B	A和B的属性名相同，但类型不相同	抛异常
A->B	serialId 不相同	正常传输

接口增加方法，对客户端无影响，如果该方法不是客户端需要的，客户端不需要重新部署。输入参数和结果集中增加属性，对客户端无影响，如果客户端并不需要新属性，不用重新部署。

rest 协议

Mon, 01 Jan 0001 00:00:00 +0000

基于标准的Java REST API——JAX-RS 2.0（Java API for RESTful Web Services的简写）实现的REST调用支持

快速入门

在dubbo中开发一个REST风格的服务会比较简单，下面以一个注册用户的简单服务为例说明。

这个服务要实现的功能是提供如下URL（注：这个URL不是完全符合REST的风格，但是更简单实用）：

http://localhost:8080/users/register

而任何客户端都可以将包含用户信息的JSON字符串POST到以上URL来完成用户注册。

首先，开发服务的接口：

public interface 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 服务是要发布到指定 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" />

REST服务提供端详解

下面我们扩充“快速入门”中的UserService，进一步展示在dubbo中REST服务提供端的开发要点。

http 协议

Mon, 01 Jan 0001 00:00:00 +0000

基于 HTTP 表单的远程调用协议，采用 Spring 的 HttpInvoker 实现

提示

2.3.0 以上版本支持

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：表单序列化
适用范围：传入传出参数数据包大小混合，提供者比消费者个数多，可用浏览器查看，可用表单或URL传入参数，暂不支持传文件。
适用场景：需同时给应用程序和浏览器 JS 使用的服务。

约束

参数及返回值需符合 Bean 规范

配置

配置协议：

<dubbo:protocol name="http" port="8080" />

配置 Jetty Server (默认)：

<dubbo:protocol ... server="jetty" />

配置 Servlet Bridge Server (推荐使用)：

<dubbo:protocol ... server="servlet" />

配置 DispatcherServlet：

<servlet>
 <servlet-name>dubbo</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>dubbo</servlet-name>
 <url-pattern>/*</url-pattern>
</servlet-mapping>

注意，如果使用 servlet 派发请求：

协议的端口 <dubbo:protocol port="8080" /> 必须与 servlet 容器的端口相同，
协议的上下文路径 <dubbo:protocol contextpath="foo" /> 必须与 servlet 应用的上下文路径相同。

hessian 协议

Mon, 01 Jan 0001 00:00:00 +0000

Hessian ¹ 协议用于集成 Hessian 的服务，Hessian 底层采用 Http 通讯，采用 Servlet 暴露服务，Dubbo 缺省内嵌 Jetty 作为服务器实现。

Dubbo 的 Hessian 协议可以和原生 Hessian 服务互操作，即：

提供者用 Dubbo 的 Hessian 协议暴露服务，消费者直接用标准 Hessian 接口调用
或者提供方用标准 Hessian 暴露服务，消费方用 Dubbo 的 Hessian 协议调用。

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：Hessian二进制序列化
适用范围：传入传出参数数据包较大，提供者比消费者个数多，提供者压力较大，可传文件。
适用场景：页面传输，文件传输，或与原生hessian服务互操作

依赖

<dependency>
 <groupId>com.caucho</groupId>
 <artifactId>hessian</artifactId>
 <version>4.0.7</version>
</dependency>

约束

参数及返回值需实现 Serializable 接口
参数及返回值不能自定义实现 List, Map, Number, Date, Calendar 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。

配置

定义 hessian 协议：

<dubbo:protocol name="hessian" port="8080" server="jetty" />

设置默认协议：

redis 协议

Mon, 01 Jan 0001 00:00:00 +0000

基于 Redis ¹ 实现的 RPC 协议。

提示

2.3.0 以上版本支持

注册 redis 服务的地址

RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
registry.register(URL.valueOf("redis://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash"));

在客户端引用

在客户端使用 ²：

<dubbo:reference id="store" interface="java.util.Map" group="member" />

或者，点对点直连：

<dubbo:reference id="store" interface="java.util.Map" url="redis://10.20.153.10:6379" />

也可以使用自定义接口：

<dubbo:reference id="store" interface="com.foo.StoreService" url="redis://10.20.153.10:6379" />

方法名建议和 redis 的标准方法名相同，即：get(key), set(key, value), delete(key)。

如果方法名和 redis 的标准方法名不相同，则需要配置映射关系 ³：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="redis://10.20.153.10:6379" p:set="putFoo" p:get="getFoo" p:delete="removeFoo" />

Redis 是一个高效的 KV 存储服务器 ↩︎
不需要感知 Redis 的地址 ↩︎
其中 “p:xxx” 为 spring 的标准 p 标签 ↩︎

thrift 协议

Mon, 01 Jan 0001 00:00:00 +0000

当前 dubbo 支持的 thrift 协议是对 thrift 原生协议 ¹ 的扩展，在原生协议的基础上添加了一些额外的头信息，比如 service name，magic number 等。

提示

2.3.0 以上版本支持

使用 dubbo thrift 协议同样需要使用 thrift 的 idl compiler 编译生成相应的 java 代码，后续版本中会在这方面做一些增强。

依赖

<dependency>
 <groupId>org.apache.thrift</groupId>
 <artifactId>libthrift</artifactId>
 <version>0.8.0</version>
</dependency>

配置

所有服务共用一个端口 ²：

<dubbo:protocol name="thrift" port="3030" />

使用

可以参考 dubbo 项目中的示例代码

常见问题

Thrift 不支持 null 值，即：不能在协议中传递 null 值

Thrift 是 Facebook 捐给 Apache 的一个 RPC 框架 ↩︎
与原生Thrift不兼容 ↩︎

gRPC 协议

Mon, 01 Jan 0001 00:00:00 +0000

Dubbo 自 2.7.5 版本开始支持 gRPC 协议，对于计划使用 HTTP/2 通信，或者想利用 gRPC 带来的 Stream、反压、Reactive 编程等能力的开发者来说，都可以考虑启用 gRPC 协议。

支持 gRPC 的好处

为期望使用 gRPC 协议的用户带来服务治理能力，方便接入 Dubbo 体系
用户可以使用 Dubbo 风格的，基于接口的编程风格来定义和使用远程服务

如何在 Dubbo 中使用 gRPC

大概需要以下步骤：

使用 IDL 定义服务
配置 compiler 插件，本地预编译
配置暴露/引用 Dubbo 服务

具体可参见以下示例

除了原生 StreamObserver 接口类型之外，Dubbo 还支持 RxJava、Reactor 编程风格的 API

memcached 协议

Mon, 01 Jan 0001 00:00:00 +0000

基于 memcached ¹ 实现的 RPC 协议。

提示

2.3.0 以上版本支持

注册 memcached 服务的地址

RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
registry.register(URL.valueOf("memcached://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash"));

在客户端引用

在客户端使用 ²：

<dubbo:reference id="cache" interface="java.util.Map" group="member" />

或者，点对点直连：

<dubbo:reference id="cache" interface="java.util.Map" url="memcached://10.20.153.10:11211" />

也可以使用自定义接口：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="memcached://10.20.153.10:11211" />

方法名建议和 memcached 的标准方法名相同，即：get(key), set(key, value), delete(key)。

如果方法名和 memcached 的标准方法名不相同，则需要配置映射关系 ³：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="memcached://10.20.153.10:11211" p:set="putFoo" p:get="getFoo" p:delete="removeFoo" />

Memcached 是一个高效的 KV 缓存服务器 ↩︎
不需要感知 Memcached 的地址 ↩︎
其中 “p:xxx” 为 spring 的标准 p 标签 ↩︎

rmi 协议

Mon, 01 Jan 0001 00:00:00 +0000

RMI 协议采用 JDK 标准的 java.rmi.* 实现，采用阻塞式短连接和 JDK 标准序列化方式。

注意：如果正在使用 RMI 提供服务给外部访问 ¹，同时应用里依赖了老的 common-collections 包 ² 的情况下，存在反序列化安全风险 ³。

特性

连接个数：多连接
连接方式：短连接
传输协议：TCP
传输方式：同步传输
序列化：Java 标准二进制序列化
适用范围：传入传出参数数据包大小混合，消费者与提供者个数差不多，可传文件。
适用场景：常规远程服务方法调用，与原生RMI服务互操作

约束

参数及返回值需实现 Serializable 接口
dubbo 配置中的超时时间对 RMI 无效，需使用 java 启动参数设置：-Dsun.rmi.transport.tcp.responseTimeout=3000，参见下面的 RMI 配置

dubbo.properties 配置

dubbo.service.protocol=rmi

RMI配置

java -Dsun.rmi.transport.tcp.responseTimeout=3000

更多 RMI 优化参数请查看 JDK 文档

接口

如果服务接口继承了 java.rmi.Remote 接口，可以和原生 RMI 互操作，即：

提供者用 Dubbo 的 RMI 协议暴露服务，消费者直接用标准 RMI 接口调用，
或者提供方用标准 RMI 暴露服务，消费方用 Dubbo 的 RMI 协议调用。

如果服务接口没有继承 java.rmi.Remote 接口：

缺省 Dubbo 将自动生成一个 com.xxx.XxxService$Remote 的接口，并继承 java.rmi.Remote 接口，并以此接口暴露服务，
但如果设置了 <dubbo:protocol name="rmi" codec="spring" />，将不生成 $Remote 接口，而使用 Spring 的 RmiInvocationHandler 接口暴露服务，和 Spring 兼容。

配置

定义 RMI 协议：

webservice 协议

Mon, 01 Jan 0001 00:00:00 +0000

基于 WebService 的远程调用协议，基于 Apache CXF ¹ 的 frontend-simple 和 transports-http 实现。

提示

2.3.0 以上版本支持

可以和原生 WebService 服务互操作，即：

提供者用 Dubbo 的 WebService 协议暴露服务，消费者直接用标准 WebService 接口调用，
或者提供方用标准 WebService 暴露服务，消费方用 Dubbo 的 WebService 协议调用。

依赖

<dependency>
 <groupId>org.apache.cxf</groupId>
 <artifactId>cxf-rt-frontend-simple</artifactId>
 <version>2.6.1</version>
</dependency>
<dependency>
 <groupId>org.apache.cxf</groupId>
 <artifactId>cxf-rt-transports-http</artifactId>
 <version>2.6.1</version>
</dependency>

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：SOAP 文本序列化
适用场景：系统集成，跨语言调用

约束

参数及返回值需实现 Serializable 接口
参数尽量使用基本类型和 POJO

配置

配置协议：

<dubbo:protocol name="webservice" port="8080" server="jetty" />

配置默认协议：

<dubbo:provider protocol="webservice" />

配置服务协议：

<dubbo:service protocol="webservice" />

多端口：

<dubbo:protocol id="webservice1" name="webservice" port="8080" />
<dubbo:protocol id="webservice2" name="webservice" port="8081" />

直连：