升级与兼容性 on Apache Dubbo

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 协议设计与实现。
统一的路由规则。
- 查看统一路由规则的迁移步骤
- 查看统一路由规则使用方式
- 查看统一路由规则设计与实现

应用级地址发现迁移指南

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 请参见下一小节。

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 完成远程调用。

统一路由规则升级指南

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

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