RPC协议 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 不相同	正常传输

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

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

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" />

多端口：

Triple 协议

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

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

Triple 协议是 Dubbo3 的主力协议，完整兼容 gRPC over HTTP/2，并在协议层面扩展了负载均衡和流量控制相关机制。本文档旨在指导用户正确的使用 Triple 协议。

在开始前，需要决定服务使用的序列化方式，如果为新服务，推荐使用 protobuf 作为默认序列化，在性能和跨语言上的效果都会更好。如果是原有服务想进行协议升级，Triple 协议也已经支持其他序列化方式，如 Hessian / JSON 等

Protobuf

编写 IDL 文件

syntax = "proto3";

option java_multiple_files = true;
option java_package = "org.apache.dubbo.hello";
option java_outer_classname = "HelloWorldProto";
option objc_class_prefix = "HLW";

package helloworld;

// The request message containing the user's name.
message HelloRequest {
 string name = 1;
}

// The response message containing the greetings
message HelloReply {
 string message = 1;
}

添加编译 protobuf 的 extension 和 plugin (以 maven 为例)

开发 REST 应用

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

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

作者：沈理

文档版权：Apache 2.0许可证署名-禁止演绎

本文篇幅较长，因为REST本身涉及面较多。另外，本文参照 Spring 等的文档风格，不仅仅局限于框架用法的阐述，同时也努力呈现框架的设计理念和优良应用的架构思想。对于想粗略了解 dubbo 和 REST 的人，只需浏览概述至标准Java REST API：JAX-RS简介几节即可。

概述
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服务
- 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注册中心、监控中心集成吗？
- 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协议）的支持。

RPC协议 on Apache Dubbo

dubbo 协议

特性

约束

http 协议

提示

特性

约束

配置

hessian 协议

特性

依赖

约束

配置

redis 协议

提示

注册 redis 服务的地址

在客户端引用

thrift 协议

提示

依赖

配置

使用

常见问题

gRPC 协议

支持 gRPC 的好处

如何在 Dubbo 中使用 gRPC

memcached 协议

提示

注册 memcached 服务的地址

在客户端引用

rmi 协议

特性

约束

RMI配置

接口

配置

webservice 协议

提示

依赖

特性

约束

配置

Triple 协议

Protobuf

开发 REST 应用

目录

概述