This document is suitable for users whose services are already running on the Dubbo protocol. Please first refer to the previous document How to Upgrade from Dubbo2 to Dubbo3 to complete the framework version upgrade, and then follow these steps for a smooth migration to the Triple protocol with minimal changes.
Here is the architecture diagram for the protocol upgrade, showing the states of different Dubbo applications during a smooth upgrade process:
In order, the basic upgrade steps are as follows:
dubbo://host:port/DemoService?preferred-protocol=tri
)preferred-protocol=tri
@DubboReference(protocol="tri")
to call the Triple protocolpreferred-protocol
option, require Dubbo 3.3.0+.Assuming we have the following application configuration, which publishes the Dubbo protocol on port 20880:
dubbo:
protocol:
name: dubbo
port: 20880
We need to add two configuration items as follows:
dubbo:
protocol:
name: dubbo
port: 20880
ext-protocol: tri
preferred-protocol: tri
Where:
ext-protocol: tri
specifies that the Triple protocol is additionally published on the original port 20880, which is single-port dual-protocol publishing.preferred-protocol: tri
will synchronize to the Consumer side with the registration center, informing the consumer to prioritize using the Triple protocol for calls.preferred-protocol: tri
configuration is only supported in version 3.3.0 and later, so even if the provider configures this option, it will not take effect for consumer clients before version 3.3.0, which will continue to call the Dubbo protocol.After the provider completes the configuration in Step 1 and restarts, the consumer may be in one of the following three states depending on version and configuration:
1. Consumer is version 3.3.0 or later
This type of consumer will automatically recognize the preferred-protocol: tri
tag on the provider’s URL. If this tag is found, the consumer will automatically use the Triple protocol to call the service; otherwise, it will continue using the Dubbo protocol.
2. Consumer is version 2.x or earlier than 3.3.0
Due to the low version of the Dubbo framework being unable to recognize the preferred-protocol: tri
parameter, these consumers are not affected by the provider’s multi-protocol publishing and will continue to call the Dubbo protocol.
3. Consumer is version 2.x or earlier than 3.3.0, but explicitly specifies the protocol to call
Similar to the second case, but users can explicitly specify which RPC protocol to use for certain services, such as:
@DubboReference(protocol="tri")
private DemoService demoService;
or
<dubbo:reference protocol="tri" />
After configuring protocol="tri"
, the service call will use the Triple protocol. It is important to ensure that the provider has already published support for the Triple protocol before configuring protocol="tri"
; otherwise, the call will fail.
preferred-protocol=tri
, which requires both sides to be upgraded to 3.3.0+.Steps 1 and 2 are very straightforward and ensure a smooth process. Through single-port dual-protocol and automatic switching on the consumer side, the entire upgrade process is ensured to be smooth.
Smooth upgrading means we will go through an intermediate state where both the Dubbo and Triple protocols coexist for a certain period, meaning some service communications are done using the Dubbo protocol while others use the Triple protocol. How can we promote achieving the end goal, which is for all service calls to use the Triple protocol? We recommend using the following two methods to achieve this goal: