Upgrading from Dubbo2 to Dubbo3 (covering versions such as 2.5.x, 2.6.x, 2.7.x)

Overall, the core capabilities after upgrading from Dubbo2 to Dubbo3 are compatible, and for over 90% of regular users (referring to users who have not made deep SPI extensions or source customizations), upgrading can be quite simple.

Upgrading from 2.7.x to Dubbo3

Step 1: Upgrade Core Dependencies

First, add the BOM dependency management in the application:

<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>

If you previously used the org.apache.dubbo:dubbo dependency, please upgrade to the following version (if there are other Dubbo submodule dependencies in the project, upgrade their versions as well):

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

If the previous application was Spring Boot, it is recommended to use the following starter dependency and upgrade to the latest version (if you previously did not use starters, please remove all old Dubbo module dependencies and directly use the following configuration):

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

Step 2: Upgrade Other Component Dependencies

1. Nacos Registry

   If you are using Nacos as the registry, ensure that the Nacos Server is upgraded to version 2.x before upgrading to Dubbo3. In addition to the Nacos Server, you also need to upgrade the Nacos Client dependency for the application.

   If it is a Spring Boot application, you can remove the nacos-client dependency and directly use the starter:

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

   If you are not currently using Spring Boot, simply update nacos-client to 2.x:

   <dependency>
     <groupId>com.alibaba</groupId>
     <artifactId>nacos-client</artifactId>
     <version>2.3.0</version>
   </dependency>
   

2. Zookeeper Registry

   If it is a Spring Boot application, you can remove the old Zookeeper-related dependencies and directly use the starter:

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

   Please note that the above dubbo-zookeeper-curator5-spring-boot-starter should be used with Zookeeper Server version 3.8.0 or higher. If you are currently using Zookeeper Server version 3.4.x, then use the following starter:

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

   If it is not a Spring Boot application, you can use the following dependencies (recommended, ensure Zookeeper Server 3.8.0 or above):

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

   Or (for Zookeeper Server 3.4.x users)

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

   Zookeeper Upgrade Precautions

   Please ensure that when managing the Zookeeper client dependencies in this way, you clean up any other zookeeper, curator dependencies in the project and fully adopt the versions provided by Dubbo.
   

3. Other Component Upgrades

   In addition to the registry, if you are using other features of Dubbo and depend on third-party components to support these features, you need to upgrade the corresponding component versions based on specific circumstances to ensure that the components work with Dubbo3.

Step 3: Compatibility Checks

Checkpoint 1: Are there SPI extensions?

1. The following SPI extension points have been removed in Dubbo3; please take note if used:

   • Event Bus. Due to the complexity of event management, EventDispatcher and EventListener support has been removed in Dubbo 3.x. If there is an extension mechanism, consider refactoring to the corresponding Dubbo function extension.

2. The internal working mechanism of the following SPI extension points has been optimized and can be adjusted as needed:

   • Filter Interceptor Mechanism. You can intercept requests based on the Filter interceptor. In 2.7, this was supported after routing; in Dubbo3, a new ClusterFilter SPI definition has been added. Compared to the previous Filter extension point, ClusterFilter can significantly reduce memory usage, benefiting large-scale clusters.

If you have some consumer-side interceptors implemented based on Filter extensions and there is no strong binding logic to remote IP addresses, we recommend migrating the corresponding org.apache.dubbo.rpc.Filter SPI extension point to org.apache.dubbo.rpc.cluster.filter.ClusterFilter.

Checkpoint 2: Is there source customization?

If the Dubbo framework you are using contains some private source customizations (modifications to Dubbo at runtime via javagent or asm also fall into this category), directly upgrading to the open-source Dubbo3 version may pose compatibility risks. For this kind of non-standard behavior, Dubbo cannot guarantee its previous compatibility. Users need to inspect all source modifications before upgrading and ensure that these modifications are compatible with the Dubbo3 version before going live.

Such issues can be addressed with some bytecode-level tools, such as exporting the content of the process metaspace, filtering out all relevant Dubbo classes and calls, to identify the locations of direct dependencies or enhancements to the Dubbo framework’s internal source in the business and secondary packages. Determine if these source calls still exist internally in Dubbo3 to decide the next upgrade steps.

Step 4: Go Live Verification

1. Gray Release There are no special restrictions on the release process for upgrading to Dubbo 3, and you can follow the normal business release. Due to the cross-major version changes, try to release in as many batches as possible, while increasing the time interval between the first and second batch releases and ensuring adequate observation. During the release process, we recommend upgrading the downstream of the application first (i.e., the service provider). After confirming that the service is functioning correctly, continue with subsequent releases.

2. Monitor Application Metrics During the release process, the following metrics can be evaluated to determine if issues arise from the upgrade.

• CPU and memory usage of machines
• API request success rate
• API request response time (RT)
• Error messages in the logs
• Whether customized extension behaviors meet expectations

Upgrading from 2.6.x and Below to Dubbo3

The following content is aimed at users of versions 2.6.x, 2.5.x, and below, to help understand how to upgrade to Dubbo3. For users of these versions, 80% can achieve a smooth upgrade by simply replacing dependencies; follow the steps below and ensure to perform the checks.

Step 1: Upgrade Core Dependencies

First, you must upgrade the old com.alibaba:dubbo dependency coordinate to org.apache.dubbo:dubbo.

As shown, replace the com.alibaba:dubbo dependency

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

with the org.apache.dubbo:dubbo dependency, and do not modify other configuration files, as shown below:

<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>

If you are using a Spring Boot application, you can also use org.apache.dubbo:dubbo-spring-boot-starter to replace the above org.apache.dubbo:dubbo dependency:

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

Step 2: Upgrade Other Component Dependencies

You need to upgrade the registry (Nacos, Zookeeper, or others) and other third-party components; please refer to the detailed instructions for upgrading discussed in the previous section about Upgrading from 2.7.x to Dubbo3. The operations in both cases are exactly the same.

Step 3: Compatibility Checks

If API or SPI extension-related compilation errors occur after upgrading dependencies, refer to the following. If your usage of Dubbo includes many SPI extension implementations, internal API calls, or changes to some core source code, focus on this part for compatibility checks.

Checkpoint 1: Package Name Changes

The biggest difference between Dubbo3 and versions 2.6.x and below is the changes in coordinates and package names:

1. Maven Coordinates GAV

groupId changed from com.alibaba to org.apache.dubbo

2. Package

package prefix changed from com.alibaba.dubbo.* to org.apache.dubbo.*

Upgrading Maven coordinates is straightforward; you only need to modify the relevant pom files. However, changes in packages may lead to compilation issues, but fortunately, Dubbo3 continues to support the majority of commonly used basic APIs and SPIs with compatibility for com.alibaba.dubbo, so theoretically upgrading the pom should still allow the project to compile successfully.

Checkpoint 2: API Programming Interface

• Annotations

• Programming APIs

Checkpoint 3: SPI Extensions

If your company maintains a custom SPI extension library, be sure to ensure its compatibility with Dubbo3 before upgrading the business project to Dubbo3. If compatibility issues are found, it is recommended to complete the upgrade by adopting package name references (from com.alibaba.dubbo.* to org.apache.dubbo.*) and repackaging.

Step 4: Go Live Verification

Refer to the verification methods discussed in the previous section about Upgrading from 2.7.x to Dubbo3.