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

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

总体来说,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>

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

  1. Nacos 注册中心

    如果您使用的是 Nacos 注册中心,在升级到 Dubbo3 之前,请先确保 Nacos Server 升级到 2.x 版本。除了 Nacos Server 之外,我们还需要升级应用侧的 Nacos Client 依赖。

    如果是 Spring Boot 应用,则可删除 nacos-client 依赖,直接使用 starter:

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

    如果您当前不是 Spring Boot 应用,则直接更新 nacos-client 到 2.x 即可:

    <dependency>
      <groupId>com.alibaba</groupId>
      <artifactId>nacos-client</artifactId>
      <version>2.3.0</version>
    </dependency>
    
  2. Zookeeper 注册中心

    如果是 Spring Boot 应用,则可删除之前老的 Zookeeper 相关依赖,直接使用 starter:

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

    请注意,以上 dubbo-zookeeper-curator5-spring-boot-starter 请搭配 Zookeeper Server 3.8.0+ 版本使用。如果您当前正在使用的 Zookeeper Server 版本是 3.4.x 版本,则使用以下 starter:

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

    如果不是 Spring Boot 应用,则可以使用以下依赖(推荐,需确保 Zookeeper Server 3.8.0 版本及以上):

    <dependency>
      <groupId>org.apache.dubbo</groupId>
      <artifactId>dubbo-dependencies-zookeeper-curator5</artifactId>
    </dependency>
    

    或者(对于 Zookeeper Server 3.4.x 版本用户)

    <dependency>
      <groupId>org.apache.dubbo</groupId>
      <artifactId>dubbo-dependencies-zookeeper</artifactId>
    </dependency>
    
  3. 其它组件升级

    除了注册中心之外,如果您有用到 Dubbo 的其它特性并且依赖第三方组件支持此特性,则您需要根据具体情况升级相应的组件版本,以确保组件能配合 Dubbo3 工作。

步骤三:兼容性检查

检查点一:是否有 SPI 扩展

  1. 以下 SPI 扩展点在 Dubbo3 中已被移除,如有使用请注意:

    • 事件总线。出于事件管理的复杂度原因,EventDispatcher 和 EventListener 在 Dubbo 3.x 的支持已经删除。如果有对应扩展机制的使用请考虑重构为对应 Dubbo 功能的扩展。
  2. 以下 SPI 扩展点的内部工作机制做了实现优化,可按需调整:

    • Filter 拦截器机制。可以基于 Filter 拦截器对请求进行拦截处理,在 2.7 中支持在路由选址后再对请求进行拦截处理。Dubbo3 中新增了 ClusterFilter SPI 定义,相比于之前的 Filter 扩展点,ClusterFilter 可以在很大程度上降低内存的占用,对与超大规模集群有较大的收益。

如果您有一些 Consumer 侧的拦截器是基于 Filter 扩展实现的,如果没有和远端的 IP 地址强绑定的逻辑,我们建议您将对应的 org.apache.dubbo.rpc.Filter SPI 扩展点迁移到 org.apache.dubbo.rpc.cluster.filter.ClusterFilter 这个新的 SPI 扩展点。

检查点二:是否存在源码定制

如果您正在使用的 Dubbo 框架包含一些私有源码定制(通过 javagent 或者 asm 等通过运行时对 Dubbo 的修改也在此范围内),则直接升级到开源 Dubbo3 版本可能有兼容性风险。对于这种非标准行为,Dubbo 无法保证其先前的兼容性,需要用户在升级前对所有源码修改进行检查,确保这部分内容完成对 Dubbo3 版本的适配后再升级上线。

此类问题可通过一些字节码层面的工具实现,如将进程 metaspace 内容遍历导出,过滤出 Dubbo 所有相关类及调用,以识别业务中、二方包中等直接依赖或增强 Dubbo 框架内部源码的位置。判断这些源码调用在 Dubbo3 内部是否仍然存在,以决策下一步升级动作。

步骤四:上线验证

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

  2. 观测应用指标 在发布的过程中,有以下几个纬度的指标可以判断升级是否出现问题。

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

2.6.x 及以下版本升级 Dubbo3

以下内容是针对 2.6.x、2.5.x 及以下版本用户的,帮助了解如何升级到 Dubbo3 版本。对于这些版本的用户而言,80% 的用户都是可以通过替换依赖实现平滑升级的,按以下步骤升级并做好检查即可。

步骤一:升级核心依赖

首先,必须升级之前老的 com.alibaba:dubbo 依赖坐标升级为 org.apache.dubbo:dubbo

如下所示,将 com.alibaba:dubbo 依赖

<dependency>
	<groupId>com.alibaba</groupId>
	<artifactId>dubbo</artifactId>
	<version>2.6.5</version>
</dependency>

替换为 org.apache.dubbo:dubbo 依赖,其它配置文件不用修改,如下所示:

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

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

如果您是 Spring Boot 应用,则也可以使用 org.apache.dubbo:dubbo-spring-boot-starter 替换上面的 org.apache.dubbo:dubbo 依赖:

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

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

您需要升级注册中心(Nacos、Zookeeper或其它)等第三方组件,具体升级方法和目标版本请参考本文前面一节的 2.7.x 版本升级到 Dubbo3 中的详细说明,两者操作方法完全一样。

步骤三:兼容性检查

如果升级依赖后出现API或SPI扩展相关的编译错误,请参考下文。如果您的 Dubbo 用法中有很多 SPI 扩展实现、内部 API 调用、或者改了一些内核源码,则需要重点关注这一部分的兼容性检查。

检查点一:包名改造

Dubbo3 与 2.6.x 及以下版本最大的一个区别就是坐标、包名的变化:

  1. Maven 坐标 GAV

groupId 由 com.alibaba 改为 org.apache.dubbo

  1. package

package 前缀由 com.alibaba.dubbo.* 改为 org.apache.dubbo.*

Maven坐标升级比较直观,只需要修改相应的pom文件就可以了;而package变更则可能会带来编译问题,但好在 Dubbo3 版本继续保留了绝大部分常用基础 API 和 SPI 的 com.alibaba.dubbo 适配支持,因此理论上升级 pom 后项目仍可直接编译成功。

检查点二:API编程接口

  • 注解
注解推荐的新注解说明
@Reference@DubboReference消费端服务引用注解
@Service@DubboService提供端服务暴露注解
@EnableDubbo@EnableDubbo
其他常用Spring注解API其他常用Spring注解API
  • 编程API
API说明
ReferenceConfigService配置采集和引用编程接口
ServiceConfigService配置采集和暴露编程接口
ApplicationConfigApplication配置采集API
RegistryConfig注册中心配置采集API
ConsumerConfig消费端默认配置采集API
ProviderConfig提供端默认配置采集API
ProtocolConfigRPC协议配置采集API
ArgumentConfig服务参数级配置采集API
MethodConfig服务方法级配置采集API
ModuleConfig服务治理Module配置采集API
MonitorConfig监控配置采集API
RpcContext编程上下文API

检查点三:SPI扩展

如果公司内部有维护的自定义SPI扩展库,在业务工程升级到 Dubbo3 上线之前,请务必先确保扩展库与 Dubbo3 的兼容性。如果发现有兼容性问题,建议通过修改包名引用的方式(从实现 com.alibaba.dubbo.* 包名类到实现 org.apache.dubbo.* 包名类 )完成升级,并重新打包。

SPI扩展点说明
Registry包括RegistryFactory, Registry ,RegistryService等扩展点
ProtocolRPC协议扩展
Serialization序列化协议扩展
Cluster集群容错策略扩展,如Failover, Failfast等
Loadbalance负载均衡策略扩展
Transporter传输框架扩展,如Netty等
Monitor监控中心扩展,包括MonitorFactory, Monitor, MonitorService等
Router路由规则扩展
Filter拦截器扩展

步骤四:上线验证

参考本文前面一节的 2.7.x 版本升级到 Dubbo3 中讲到的验证方法。

最后修改 September 13, 2024: Refactor website structure (#2860) (1a4b998f54b)