升级和兼容性 on Apache Dubbo

从 dubbo2 升级到 dubbo3（涵盖 2.5.x、2.6.x、2.7.x 等版本）

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

总体来说，Dubbo2 升级到 Dubbo3 后的核心能力都是兼容的，对于 90% 以上的常规用户而言（指未做深度 SPI 扩展或源码定制的用户），可以非常简单的完成升级。

2.7.x 升级 Dubbo3

步骤一：升级核心依赖

首先，在应用中增加 bom 依赖管理：

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-dependencies-bom</artifactId>
 <version>3.3.0</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

如果您之前用的是 org.apache.dubbo:dubbo 依赖，请升级到以下版本（如果项目中还有其它 dubbo 子模块依赖，请一并升级版本号）：

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

如果之前的应用是 Spring Boot，建议使用以下 starter 依赖方式并升级到最新版本（如果之前未使用 starter，请删除所有老的 dubbo 模块依赖，直接使用以下配置即可）：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
</dependency>

Dubbo3 相关的 Spring、Spring Boot 版本升级说明

Dubbo3 支持的 Spring、Spring Boot 版本兼容范围非常广：

既支持 Spring 3.x ~ Spring 5.x 相关版本，同时也支持 Spring Boot 1.x ~ Spring Boot 2.x 版本。如果遇到应用无法升级高版本 Spring、Spring Boot 的情况下，可排掉 dubbo-spring-boot-starter 或 dubbo 中传递的高版本 Spring 依赖，指定项目可接受的 Spring 版本依赖即可。
Spring Boot 3.x 和 Spring 6 版本由于需要 JDK 17 及以上版本，请参考 Dubbo Spring Boot 手册 了解详情。

步骤二：升级其它组件依赖

Nacos 注册中心

升级到triple协议

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

请注意

本文档内容并不是升级 Dubbo3 必须的，您完全可以只升级框架并继续使用 dubbo 通信协议。
如果您是 Dubbo 新用户，强烈建议直接使用 triple 协议即可。

本文档适合服务已经运行在 dubbo 协议之上的老用户，请先参考上一篇文档如何从 Dubbo2 升级到 Dubbo3 完成框架版本升级，然后遵循以下步骤以最小改动平滑迁移到 triple 协议。

以下是协议升级的架构图，展示了平滑升级过程中不同 Dubbo 应用的状态：

按先后顺序，升级基本步骤如下：

Provider 提供者侧配置单端口双协议（dubbo、triple）发布
Provider 提供者侧配置首选协议为 triple（此时，提供者注册的URL地址为 dubbo://host:port/DemoService?preferred-protocol=tri）
Consumer 消费者升级，根据情况不同有以下两种方式：
- 升级消费者到 3.3 版本，消费者会根据 preferred-protocol=tri 优先调用 triple 协议
- 无法升级到 3.3 版本的消费者应用，可以配置 @DubboReference(protocol="tri") 调用 triple 协议
推动所有应用升级到最新 Dubbo3 版本，最终所有流量都是 triple 协议

请注意

请注意，以上提到的单端口多协议、识别 preferred-protocol 首选协议等功能，需要 Dubbo 3.3.0+ 版本！

步骤一：提供者双协议发布

假设我们有以下应用配置，即在 20880 端口发布 dubbo 协议：

dubbo:
 protocol:
 name: dubbo
 port: 20880

我们需要增加两个配置项，如下所示：

升级到应用级服务发现

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

请注意

本文档内容并不是升级 Dubbo3 必须的，您完全可以只升级框架并使用框架的服务发现默认行为。
本文档更适用于 Dubbo2 老用户，用于了解在升级到 Dubbo3 版本后，框架中的服务发现模型切换过程与工作原理。新用户请直接配置启用应用级服务发现。

对于 Dubbo2 老用户而言，在升级 Dubbo3 时有以下两个选择，而决策的考虑因素仅有一个：性能。

如果您的集群规模不算大，之前使用 Dubbo2 未遇到任何地址推送等性能问题，完全可以继续使用接口级别服务发现
如果您集群规模较大，之前使用 Dubbo2 遇到服务发现负载飙高等问题，则建议迁移到新的应用级服务发现

基于以上决策结论，请在升级 Dubbo3 框架时调整以下配置。

继续使用接口级服务发现

在升级到 Dubbo3 框架时，您需要调整应用配置如下，（仅仅是一个配置项调整，提供者应用必须配置、消费者应用可选）：

<dubbo:application name="xxx" register-mode="interface">

或者

dubbo:
 application:
 name: xxx
 register-mode: interface #表示继续使用老版本服务发现模型，可选值 interface、instance、all

或者，以上是全局默认配置，可以根据每个注册中心来单独配置

<dubbo:registry address="nacos://localhost:8848" register-mode="interface">

或者

dubbo:
 registry:
 address: nacos://localhost:8848
 register-mode: interface #表示继续使用老版本服务发现模型，可选值 interface、instance、all

启用应用级服务发现(默认)

对于老用户而言，如果要启用应用级服务发现，就需要一个平滑迁移的过程。这时需要让新升级的 Dubbo3 应用进行双注册双订阅（当前框架默认行为，因此用户无需修改任何配置，以下内容均会自行发生，注意：未来版本可能切换为应用级单注册单订阅），以确保新老服务发现模型都能兼顾。

请注意

对于新用户而言，可以直接配置 dubbo.application.register-mode=instance，即在一开始就配置仅使用应用级服务发现。

提供者端注册行为

在默认情况下，Dubbo3 框架会同时注册接口级、应用级两种服务发现地址，因此，集群中的新老应用都能够正常的发现改应用地址，并正常发起调用。如下图所示：

消费者端订阅行为

在默认情况下，Dubbo3 框架具备同时发现 Dubbo2 与 Dubbo3 地址列表的能力。在默认情况下，如果集群中存在可以消费的 Dubbo3 的地址，将自动消费 Dubbo3 的地址，如果不存在新地址则自动消费 Dubbo2 的地址（Dubbo3 提供了开关来控制这个行为），具体如下图所示：