Apache Dubbo – 升级和兼容性

Java-Sdk: 2.x升级至3.x操作指南

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

无需改动任何代码，直接升级到 Dubbo 3.0。

在 3.0 版本的设计与开发之初，我们就定下了兼容老版本 Dubbo 用户（2.5、2.6、2.7）的目标。因此，往 3.0 版本的升级过程将会是完全透明的，用户无需做任何业务改造，升级 3.x 后的框架行为将保持与 2.x 版本完全一致。

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
 <version>3.0.0</version>
</dependency>

但也要注意，透明升级仅仅是通往 3.0 的第一步，因为 “框架行为保持一致” 也就意味着用户将无法体验到 3.0 的新特性。如果要启用 3.0 的带来的新特性，用户则需要进行一定的改造，我们称这个过程为迁移，这是一个按需开启的过程。

因此，对老用户而言，有两条不同的迁移路径：

分两步走，先以兼容模式推动业务升级到 3.0 版本（无需改造），之后在某些时机按需启用新特性（按需改造）；
升级与迁移同步完成，在业务升级到 3.0 版本的同时，完成改造并启用新特性；

Dubbo 3.0 提供的新特性包括：

新的地址发现模型（应用级服务发现）。
- 查看应用级服务发现的迁移步骤
- 查看应用级服务发现的使用方式
- 查看应用级服务发现设计与实现。
下一代基于 HTTP/2 的 Triple 协议。
- 查看Triple 协议迁移步骤
- 查看 Triple 协议使用方式
- 查看 Triple 协议设计与实现。
统一的路由规则。
- 查看统一路由规则的迁移步骤
- 查看统一路由规则使用方式
- 查看统一路由规则设计与实现

Java-Sdk: Dubbo协议迁移至Triple协议指南

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

Triple 介绍

Triple 协议的格式和原理请参阅 RPC 通信协议

根据 Triple 设计的目标，Triple 协议有以下优势:

具备跨语言交互的能力，传统的多语言多 SDK 模式和 Mesh 化跨语言模式都需要一种更通用易扩展的数据传输协议。
提供更完善的请求模型，除了支持传统的 Request/Response 模型（Unary 单向通信），还支持 Stream（流式通信）和 Bidirectional（双向通信）。
易扩展、穿透性高，包括但不限于 Tracing / Monitoring 等支持，也应该能被各层设备识别，网关设施等可以识别数据报文，对 Service Mesh 部署友好，降低用户理解难度。
完全兼容 grpc，客户端/服务端可以与原生grpc客户端打通。
可以复用现有 grpc 生态下的组件, 满足云原生场景下的跨语言、跨环境、跨平台的互通需求。

当前使用其他协议的 Dubbo 用户，框架提供了兼容现有序列化方式的迁移能力，在不影响线上已有业务的前提下，迁移协议的成本几乎为零。

需要新增对接 Grpc 服务的 Dubbo 用户，可以直接使用 Triple 协议来实现打通，不需要单独引入 grpc client 来完成，不仅能保留已有的 Dubbo 易用性，也能降低程序的复杂度和开发运维成本，不需要额外进行适配和开发即可接入现有生态。

对于需要网关接入的 Dubbo 用户，Triple 协议提供了更加原生的方式，让网关开发或者使用开源的 grpc 网关组件更加简单。网关可以选择不解析 payload ，在性能上也有很大提高。在使用 Dubbo 协议时，语言相关的序列化方式是网关的一个很大痛点，而传统的 HTTP 转 Dubbo 的方式对于跨语言序列化几乎是无能为力的。同时，由于 Triple 的协议元数据都存储在请求头中，网关可以轻松的实现定制需求，如路由和限流等功能。

Dubbo2 协议迁移流程

Dubbo2 的用户使用 dubbo 协议 + 自定义序列化，如 hessian2 完成远程调用。

而 Grpc 的默认仅支持 Protobuf 序列化，对于 Java 语言中的多参数以及方法重载也无法支持。

Dubbo3的之初就有一条目标是完美兼容 Dubbo2，所以为了 Dubbo2 能够平滑升级， Dubbo 框架侧做了很多工作来保证升级的无感，目前默认的序列化和 Dubbo2 保持一致为hessian2。

所以，如果决定要升级到 Dubbo3 的 Triple 协议，只需要修改配置中的协议名称为 tri (注意: 不是triple)即可。

接下来我们我们以一个使用 Dubbo2 协议的工程来举例，如何一步一步安全的升级。

仅使用 dubbo 协议启动 provider 和 consumer，并完成调用。
使用 dubbo 和 tri 协议启动provider，以 dubbo 协议启动 consumer，并完成调用。
仅使用 tri 协议启动 provider和 consumer，并完成调用。

定义服务

定义接口

public interface IWrapperGreeter {

 //...

 /**
 * 这是一个普通接口，没有使用 pb 序列化
 */
 String sayHello(String request);

}

实现类如下

public class IGreeter2Impl implements IWrapperGreeter {

 @Override
 public String sayHello(String request) {
 return "hello," + request;
 }
}

仅使用 dubbo 协议

为保证兼容性，我们先将部分 provider 升级到 dubbo3 版本并使用 dubbo 协议。

使用 dubbo 协议启动一个 Provider 和 Consumer ,完成调用，输出如下:

同时使用 dubbo 和 triple 协议

对于线上服务的升级，不可能一蹴而就同时完成 provider 和 consumer 升级, 需要按步操作，保证业务稳定。第二步, provider 提供双协议的方式同时支持 dubbo + tri 两种协议的客户端。

结构如图所示:

按照推荐升级步骤，provider 已经支持了tri协议，所以 dubbo3的 consumer 可以直接使用 tri 协议

使用dubbo协议和triple协议启动Provider和Consumer,完成调用，输出如下:

仅使用 triple 协议

当所有的 consuemr 都升级至支持 Triple 协议的版本后，provider 可切换至仅使用 Triple 协议启动

结构如图所示:

Provider 和 Consumer 完成调用，输出如下:

实现原理

通过上面介绍的升级过程，我们可以很简单的通过修改协议类型来完成升级。框架是怎么帮我们做到这些的呢？

通过对 Triple 协议的介绍，我们知道Dubbo3的 Triple 的数据类型是 protobuf 对象，那为什么非 protobuf 的 java 对象也可以被正常传输呢。

这里 Dubbo3 使用了一个巧妙的设计，首先判断参数类型是否为 protobuf 对象，如果不是。用一个 protobuf 对象将 request 和 response 进行 wrapper，这样就屏蔽了其他各种序列化带来的复杂度。在 wrapper 对象内部声明序列化类型，来支持序列化的扩展。

wrapper 的protobuf的 IDL如下:

syntax = "proto3";

package org.apache.dubbo.triple;

message TripleRequestWrapper {
 // hessian4
 // json
 string serializeType = 1;
 repeated bytes args = 2;
 repeated string argTypes = 3;
}

message TripleResponseWrapper {
 string serializeType = 1;
 bytes data = 2;
 string type = 3;
}

对于请求，使用TripleRequestWrapper进行包装，对于响应使用TripleResponseWrapper进行包装。

对于请求参数，可以看到 args 被repeated修饰，这是因为需要支持 java 方法的多个参数。当然，序列化只能是一种。序列化的实现沿用 Dubbo2 实现的 spi

多语言用户 (正在使用 Protobuf)

建议新服务均使用该方式

对于 Dubbo3 和 Triple 来说，主推的是使用 protobuf 序列化，并且使用 proto 定义的 IDL 来生成相关接口定义。以 IDL 做为多语言中的通用接口约定，加上 Triple 与 Grpc 的天然互通性，可以轻松地实现跨语言交互，例如 Go 语言等。

将编写好的 .proto 文件使用 dubbo-compiler 插件进行编译并编写实现类，完成方法调用：

从上面升级的例子我们可以知道，Triple 协议使用 protbuf 对象序列化后进行传输，所以对于本身就是 protobuf 对象的方法来说，没有任何其他逻辑。

使用 protobuf 插件编译后接口如下：

public interface PbGreeter {

 static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
 static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";

 static final boolean inited = PbGreeterDubbo.init();

 org.apache.dubbo.sample.tri.GreeterReply greet(org.apache.dubbo.sample.tri.GreeterRequest request);

 default CompletableFuture<org.apache.dubbo.sample.tri.GreeterReply> greetAsync(org.apache.dubbo.sample.tri.GreeterRequest request){
 return CompletableFuture.supplyAsync(() -> greet(request));
 }

 void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);

 org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterRequest> greetStream(org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
}

开启 Triple 新特性 —— Stream (流)

Stream 是 Dubbo3 新提供的一种调用类型，在以下场景时建议使用流的方式:

接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送
流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的
推送类场景，多个消息在同一个调用的上下文中被发送和处理

Stream 分为以下三种:

SERVER_STREAM(服务端流)
CLIENT_STREAM(客户端流)
BIDIRECTIONAL_STREAM(双向流)

由于 java 语言的限制，BIDIRECTIONAL_STREAM 和 CLIENT_STREAM 的实现是一样的。

在 Dubbo3 中，流式接口以 SteamObserver 声明和使用，用户可以通过使用和实现这个接口来发送和处理流的数据、异常和结束。

对于 Dubbo2 用户来说，可能会对StreamObserver感到陌生，这是Dubbo3定义的一种流类型，Dubbo2 中并不存在 Stream 的类型，所以对于迁移场景没有任何影响。

流的语义保证

提供消息边界，可以方便地对消息单独处理
严格有序，发送端的顺序和接收端顺序一致
全双工，发送不需要等待
支持取消和超时

非 PB 序列化的流

public interface IWrapperGreeter {

 StreamObserver<String> sayHelloStream(StreamObserver<String> response);

 void sayHelloServerStream(String request, StreamObserver<String> response);
}

Stream 方法的方法入参和返回值是严格约定的，为防止写错而导致问题，Dubbo3 框架侧做了对参数的检查, 如果出错则会抛出异常。对于 双向流(BIDIRECTIONAL_STREAM), 需要注意参数中的 StreamObserver 是响应流，返回参数中的 StreamObserver 为请求流。

实现类

public class WrapGreeterImpl implements WrapGreeter {

 //...

 @Override
 public StreamObserver<String> sayHelloStream(StreamObserver<String> response) {
 return new StreamObserver<String>() {
 @Override
 public void onNext(String data) {
 System.out.println(data);
 response.onNext("hello,"+data);
 }

 @Override
 public void onError(Throwable throwable) {
 throwable.printStackTrace();
 }

 @Override
 public void onCompleted() {
 System.out.println("onCompleted");
 response.onCompleted();
 }
 };
 }

 @Override
 public void sayHelloServerStream(String request, StreamObserver<String> response) {
 for (int i = 0; i < 10; i++) {
 response.onNext("hello," + request);
 }
 response.onCompleted();
 }
}

调用方式

delegate.sayHelloServerStream("server stream", new StreamObserver<String>() {
 @Override
 public void onNext(String data) {
 System.out.println(data);
 }

 @Override
 public void onError(Throwable throwable) {
 throwable.printStackTrace();
 }

 @Override
 public void onCompleted() {
 System.out.println("onCompleted");
 }
});


StreamObserver<String> request = delegate.sayHelloStream(new StreamObserver<String>() {
 @Override
 public void onNext(String data) {
 System.out.println(data);
 }

 @Override
 public void onError(Throwable throwable) {
 throwable.printStackTrace();
 }

 @Override
 public void onCompleted() {
 System.out.println("onCompleted");
 }
});
for (int i = 0; i < n; i++) {
 request.onNext("stream request" + i);
}
request.onCompleted();

使用 Protobuf 序列化的流

对于 Protobuf 序列化方式，推荐编写 IDL 使用 compiler 插件进行编译生成。生成的代码大致如下:

public interface PbGreeter {

 static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
 static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";

 static final boolean inited = PbGreeterDubbo.init();

 //...

 void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);

 org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterRequest> greetStream(org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
}

流的实现原理

Triple协议的流模式是怎么支持的呢？

从协议层来说，Triple 是建立在 HTTP2 基础上的，所以直接拥有所有 HTTP2 的能力，故拥有了分 stream 和全双工的能力。
框架层来说，StreamObserver 作为流的接口提供给用户，用于入参和出参提供流式处理。框架在收发 stream data 时进行相应的接口调用, 从而保证流的生命周期完整。

Triple 与应用级注册发现

关于 Triple 协议的应用级服务注册和发现和其他语言是一致的，可以通过下列内容了解更多。

与 GRPC 互通

通过对于协议的介绍，我们知道 Triple 协议是基于 HTTP2 并兼容 GRPC。为了保证和验证与GRPC互通能力，Dubbo3 也编写了各种从场景下的测试。详细的可以通过这里了解更多。

未来: Everything on Stub

用过 Grpc 的同学应该对 Stub 都不陌生。 Grpc 使用 compiler 将编写的 proto 文件编译为相关的 protobuf 对象和相关 rpc 接口。默认的会同时生成几种不同的 stub

blockingStub
futureStub
reactorStub
…

stub 用一种统一的使用方式帮我们屏蔽了不同调用方式的细节。不过目前 Dubbo3 暂时只支持传统定义接口并进行调用的使用方式。

在不久的未来，Triple 也将实现各种常用的 Stub，让用户写一份proto文件，通过 comipler 可以在任意场景方便的使用，请拭目以待。

Java-Sdk: 接口级服务发现迁移至应用级服务发现指南

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

总体上来说，在地址注册与发现环节，3.x 是完全兼容 2.x 版本的，这意味着，用户可以选择将集群内任意数量的应用或机器升级到 3.x，同时在这个过程中保持与 2.x 版本的互操作性。

1 快速升级步骤

简单的修改 pom.xml 到最新版本就可以完成升级，如果要迁移到应用级地址，只需要调整开关控制 3.x 版本的默认行为。

升级 Provider 应用到最新 3.x 版本依赖，配置双注册开关dubbo.application.register-mode=all（建议通过全局配置中心设置，默认已自动开启），完成应用发布。
升级 Consumer 应用到最新 3.x 版本依赖，配置双订阅开关dubbo.application.service-discovery.migration=APPLICATION_FIRST（建议通过全局配置中心设置，默认已自动开启），完成应用发布。
在确认 Provider 的上有 Consumer 全部完成应用级地址迁移后，Provider 切到应用级地址单注册。完成升级

以下是关于迁移流程的详细描述。

2 Provider 端升级过程详解

在不改变任何 Dubbo 配置的情况下，可以将一个应用或实例升级到 3.x 版本，升级后的 Dubbo 实例会默保保证与 2.x 版本的兼容性，即会正常注册 2.x 格式的地址到注册中心，因此升级后的实例仍会对整个集群仍保持可见状态。

同时新的地址发现模型（注册应用级别的地址）也将会自动注册。

通过 -D 参数，可以指定 provider 启动时的注册行为

-Ddubbo.application.register-mode=all
# 可选值 interface、instance、all，默认是 all，即接口级地址、应用级地址都注册

另外，可以在配置中心修改全局默认行为，来控制所有 3.x 实例注册行为。其中，全局性开关的优先级低于 -D 参数。

为了保证平滑迁移，即升级到 3.x 的实例能同时被 2.x 与 3.x 的消费者实例发现，3.x 实例需要开启双注册；当所有上游的消费端都迁移到 3.x 的地址模型后，提供端就可以切换到 instance 模式（只注册应用级地址）。对于如何升级消费端到 3.x 请参见下一小节。

2.1 双注册带来的资源消耗

双注册不可避免的会带来额外的注册中心存储压力，但考虑到应用级地址发现模型的数据量在存储方面的极大优势，即使对于一些超大规模集群的用户而言，新增的数据量也并不会带来存储问题。总体来说，对于一个普通集群而言，数据增长可控制在之前数据总量的 1/100 ~ 1/1000

以一个中等规模的集群实例来说： 2000 实例、50个应用（500 个 Dubbo 接口，平均每个应用 10 个接口）。

假设每个接口级 URL 地址平均大小为 5kb，每个应用级 URL 平均大小为 0.5kb

老的接口级地址量：2000 * 500 * 5kb ≈ 4.8G

新的应用级地址量：2000 * 50 * 0.5kb ≈ 48M

双注册后仅仅增加了 48M 的数据量。

3 Consumer 端升级过程

对于 2.x 的消费者实例，它们看到的自然都是 2.x 版本的提供者地址列表；

对于 3.x 的消费者，它具备同时发现 2.x 与 3.x 提供者地址列表的能力。在默认情况下，如果集群中存在可以消费的 3.x 的地址，将自动消费 3.x 的地址，如果不存在新地址则自动消费 2.x 的地址。Dubbo3 提供了开关来控制这个行为：

dubbo.application.service-discovery.migration=APPLICATION_FIRST
# 可选值
# FORCE_INTERFACE，只消费接口级地址，如无地址则报错，单订阅 2.x 地址
# APPLICATION_FIRST，智能决策接口级/应用级地址，双订阅
# FORCE_APPLICATION，只消费应用级地址，如无地址则报错，单订阅 3.x 地址

dubbo.application.service-discovery.migration 支持通过 -D 以及 全局配置中心 两种方式进行配置。

接下来，我们就具体看一下，如何通过双订阅模式（APPLICATION_FIRST）让升级到 3.x 的消费端迁移到应用级别的地址。在具体展开之前，先明确一条消费端的选址行为：对于双订阅的场景，消费端虽然可同时持有 2.x 地址与 3.x 地址，但选址过程中两份地址是完全隔离的：要么用 2.x 地址，要么用 3.x 地址，不存在两份地址混合调用的情况，这个决策过程是在收到第一次地址通知后就完成了的。

下面，我们看一个APPLICATION_FIRST策略的具体操作过程。

首先，提前在全局配置中心 Nacos 配置一条配置项（所有消费端都将默认执行这个选址策略）：

紧接着，升级消费端到 3.x 版本并启动，这时消费端读取到APPLICATION_FIRST配置后，执行双订阅逻辑（订阅 2.x 接口级地址与 3.x 应用级地址）

至此，升级操作就完成了，剩下的就是框架内部的执行了。在调用发生前，框架在消费端会有一个“选址过程”，注意这里的选址和之前 2.x 版本是有区别的，选址过程包含了两层筛选：

先进行地址列表（ClusterInvoker）筛选（接口级地址 or 应用级地址）
再进行实际的 provider 地址（Invoker）筛选。

ClusterInvoker 筛选的依据，可以通过 MigrationAddressComparator SPI 自行定义，目前官方提供了一个简单的地址数量比对策略，即当 应用级地址数量 == 接口级地址数量 满足时则进行迁移。

其实 FORCE_INTERFACE、APPLICATION_FIRST、FORCE_APPLICATION 控制的都是这里的 ClusterInvoker 类型的筛选策略

3.1 双订阅带来的资源消耗

双订阅不可避免的会增加消费端的内存消耗，但由于应用级地址发现在地址总量方面的优势，这个过程通常是可接受的，我们从两个方面进行分析：

双订阅带来的地址推送数据量增长。这点我们在 ”双注册资源消耗“ 一节中做过介绍，应用级服务发现带来的注册中心数据量增长非常有限。
双订阅带来的消费端内存增长。要注意双订阅只存在于启动瞬态，在ClusterInvoker选址决策之后其中一份地址就会被完全销毁；对单个服务来说，启动阶段双订阅带来的内存增长大概能控制在原内存量的 30% ~ 40%，随后就会下降到单订阅水平，如果切到应用级地址，能实现内存 50% 的下降。

3.2 消费端更细粒度的控制

除了全局的迁移策略之外，Dubbo 在消费端提供了更细粒度的迁移策略支持。控制单位可以是某一个消费者应用，它消费的服务A、服务B可以有各自独立的迁移策略，具体是用方式是在消费端配置迁移规则：

key: demo-consumer
step: APPLICATION_FIRST
applications:
 - name: demo-provider
 step: FORCE_APPLICATION
services:
 - serviceKey: org.apache.dubbo.config.api.DemoService:1.0.0
 step: FORCE_INTERFACE

使用这种方式能做到比较精细迁移控制，但是当下及后续的改造成本会比较高，除了一些特别场景，我们不太推荐启用这种配置方式。 (迁移指南) 官方推荐使用的全局的开关式的迁移策略，让消费端实例在启动阶段自行决策使用哪份可用的地址列表。

4 迁移状态的收敛

为了同时兼容 2.x 版本，升级到 3.x 版本的应用在一段时间内要么处在双注册状态，要么处在双订阅状态。

解决这个问题，我们还是从 Provider 视角来看，当所有的 Provider 都切换到应用级地址注册之后，也就不存在双订阅的问题了。

4.1 不同的升级策略影响很大

毫无疑问越早越彻底的升级，就能尽快摆脱这个局面。设想，如果可以将组织内所有的应用都升级到 3.x 版本，则版本收敛就变的非常简单：升级过程中 Provider 始终保持双注册，当所有的应用都升级到 3.x 之后，就可以调整全局默认行为，让 Provider 都变成应用级地址单注册了，这个过程并不会给 Consumer 应用带来困扰，因为它们已经是可以识别应用级地址的 3.x 版本了。

如果没有办法做到应用的全量升级，甚至在相当长的时间内只能升级一部分应用，则不可避免的迁移状态要持续比较长的时间。在这种情况下，我们追求的只能是尽量保持已升级应用的上下游实现版本及功能收敛。推动某些 Provider 的上游消费者都升级到 Dubbo3，这样就可以解除这部分 Provider 的双注册，要做到这一点，可能需要一些辅助统计工具的支持。

要能分析出应用间的依赖关系，比如一个 Provdier 应用被哪些消费端应用消费，这可以通过 Dubbo 提供的服务元数据上报能力来实现。
要能知道每个应用当前使用的 dubbo 版本，可以通过扫描或者主动上报手段。