2.x 升级至 3.x

Dubbo 3 升级与兼容性指南

升级到 Dubbo 3.X 的收益

Dubbo3 依旧保持了 2.x 的经典架构，以解决微服务进程间通信为主要职责，通过丰富的服务治理（如地址发现、流量管理等）能力来更好的管控微服务集群；Dubbo3 对原有框架的升级是全面的，体现在核心 Dubbo 特性的几乎每个环节，通过升级实现了稳定性、性能、伸缩性、易用性的全面提升。

architecture-1

通用的通信协议。 全新的 RPC 协议应摒弃私有协议栈，以更通用的 HTTP/2 协议为传输层载体，借助 HTTP 协议的标准化特性，解决流量通用性、穿透性等问题，让协议能更好的应对前后端对接、网关代理等场景；支持 Stream 通信模式，满足不同业务通信模型诉求的同时给集群带来更大的吞吐量。
面向百万集群实例，集群高度可伸缩。 随着微服务实践的推广，微服务集群实例的规模也在不停的扩展，这得益于微服务轻量化、易于水平扩容的特性，同时也给整个集群容量带来了负担，尤其是一些中心化的服务治理组件；Dubbo3 需要解决实例规模扩展带来的种种资源瓶颈问题，实现真正的无限水平扩容。
全面拥抱云原生。

Dubbo 3.0 新特性

Dubbo 3.0 提供的新特性包括：

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

升级前的兼容性检查

在跨版本升级的过程中，存在的风险点从大到小分别有：直接修改 Dubbo 源码 -> 基于 Dubbo SPI 扩展点进行扩展 -> 基于 API 或者 Spring 的使用方式。

1. 直接修改 Dubbo 源码

对于直接修改 Dubbo 源码这部分的需要修改方自行判断是否在高版本中正常工作，对于这种非标准行为，Dubbo 无法保证其先前的兼容性。此外，通过 javagent 或者 asm 等通过运行时对 Dubbo 的修改也在此范围内。此类修改大部分可以通过后文提供的扫描工具检测出来。

2. SPI 扩展

不兼容项

对于 SPI 扩展的，除了应用级服务方向和 EventDispatcher 两个机制在 3.x 中做了破坏性的修改，在 2.7.x 中提供的绝大多数的扩展在 3.x 中也都提供。此部分需要关注的有两个方面：

事件总线：出于事件管理的复杂度原因，EventDispatcher 和 EventListener 在 Dubbo 3.x 的支持已经删除。如果有对应扩展机制的使用请考虑重构为对应 Dubbo 功能的扩展。
应用级服务发现：Dubbo 2.7 中的应用级服务发现的整体机制在 Dubbo 3.x 中已经被完整重构，功能的性能与稳定性有了很大程度上的提高。因此我们建议您不要使用 Dubbo 2.7 中的应用级服务发现机制，如果有对应的扩展可以在升级到 Dubbo 3.x 之后基于新的代码重新验证实现（绝大多数应用级服务发现的 API 是向前兼容的）。

优化项（可选）

此外，Dubbo 3.x 中对部分扩展点的工作机制进行了优化，可以较大程度上提升应用的性能。

1）拦截器机制

Dubbo 中可以基于 Filter 拦截器对请求进行拦截处理。在 Dubbo 2.7 中支持在路由选址后再对请求进行拦截处理。Dubbo 3.x 中抽象了全新的 ClusterFilter 机制，可以在很大程度上降低内存的占用，对与超大规模集群有较大的收益。如果您有一些 Consumer 侧的拦截器是基于 Filter 机制实现的，如果没有和远端的 IP 地址强绑定的逻辑，我们建议您将对应的 org.apache.dubbo.rpc.Filter SPI 扩展点迁移到 org.apache.dubbo.rpc.cluster.filter.ClusterFilter 这个新的 SPI 扩展点。两个接口的方法定义是完全一样的。

2）Router -> StateRouter

Dubbo 中提供了 Router 这个可以动态进行选址路由的能力，同时绝大多数的服务治理能力也都是基于这个 Router 扩展点实现的。在 Dubbo 3.x 中，Dubbo 在 Router 的基础上抽象了全新的 StateRouter 机制，可以在选址性能以及内存占用上有大幅优化。关于 StateRouter 的更多介绍我们会在后续的文档中发布。

3. API / Spring 使用

对于基于 API 或者 Spring 的使用，Dubbo 3.x 和 2.7.x 的使用方式是对齐的，在 Dubbo 3.x 中对部分无效的配置进行了强校验，这部分异常会在启动过程中直接报错，请按照提示修改即可。

升级流程

1. 依赖升级

如果使用 Nacos 作为注册中心，由于 Nacos 特性支持的原因，在升级到 Dubbo 3.x 之前需要将 Nacos Server 升级到 2.x（参考文档 https://nacos.io/zh-cn/docs/v2/upgrading/2.0.0-upgrading.html），然后再将应用的 Nacos Client 也对应升级。如果使用 Zookeeper 注册中心则不需要处理。如果您是使用 Spring Cloud Alibaba Dubbo 进行接入的，由于 Dubbo 部分内部 API 进行了变更，请升级到 xxx。

Dubbo 依赖请升级到最新的 3.1.3 版本，Dubbo 和对应的 springboot starter GAV 如下所示。

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

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

2. 灰度升级

Dubbo 3 升级对于发布流程没有做特殊限制，按照正常业务发布即可。由于 Dubbo 是进行跨大版本的变更升级，发布中请尽可能多分批次发布，同时拉大第一批和第二批发布的时间间隔，做好充足的观察。发布过程中，我们建议您先升级应用的下游（也即是服务提供者），在验证服务处理正常以后再继续后续发布。

3. 升级观测指标

在发布的过程中，有以下几个纬度的指标可以判断升级是否出现问题。

机器的 CPU、内存使用情况
接口请求成功率
接口请求 RT
日志的报错信息
自定义扩展行为是否符合预期

注意事项

1. 应用级服务发现

由于 Dubbo 2.7 的应用级服务发现模型存在设计上的问题，在 Dubbo 3.x 中做了大量格式上的修改，所以 2.7.x 和 3.x 的应用级服务发现可能存在无法互相订阅调用的可能性。虽然 Dubbo 会剔除识别不了的实例，但是从稳定性的角度出发，如果您在 2.7.x 中开启了应用级服务发现特性（在 2.7.x 中非默认注册），我们建议先在 2.7.x 中关闭，待升级到 3.x 之后再开启。

最后修改 September 10, 2024: Fix links (f6d9e2e3f52)