3.1 upgrade to 3.2

For the vast majority of users, upgrading to Dubbo 3.2.0 is completely smooth, and only needs to modify the version of the dependent package.

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

or

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

Compatibility CheckList

1. Serialization check mode (important!!!)

In Dubbo 3.2.0 version, Dubbo will enable the strong verification of the serialized whitelist by default to improve the security of Dubbo and avoid the problem of remote command execution. For some users who use generics and may have incomplete scanning or large service scale, we recommend that you add -Ddubbo.application.serialize-check-status=WARN configuration. After observing for a period of time (via logs and QoS commands), if no security alarm is triggered, you can configure the strong check mode.

For the configuration of the custom whitelist, please refer to Documentation/SDK Manual/Java SDK/Advanced Features and Usage/Improve Security/Class Inspection Mechanism article to configure.

Q1: Why do you need to enable strong verification of the serialization whitelist?

Due to the problem of Java’s own mechanism, the non-IDL serialization supported by Dubbo naturally allows access to arbitrary classes, which may lead to remote command execution (RCE) risks.

Q2: What are the best practices for upgrading to 3.2?

We recommend all users to add -Ddubbo.application.serialize-check-status=WARN configuration before upgrading Dubbo 3.2.0 to ensure the best compatibility. Otherwise, it may lead to abnormal online data!

2. Default serialization switch

Starting from Dubbo version 3.2.0, the default serialization method is switched from hessian2 to fastjson2. For applications upgraded to 3.2.0, Dubbo will automatically try to use fastjson2 for serialization.

Q1: Will it affect the intercommunication with lower versions of Dubbo?

Won’t. Interoperability with lower versions still uses hessian-lite. For the principle, please refer to Serialization Protocol Upgrade Guide.

Q2: Why switch the default serialization method?

fastjson2 is a high-performance serialization framework with better performance than hessian2, natively supports JDK17, Native, etc., and is fully forward compatible with all functions of hessian2. Since hessian-lite will become more and more difficult to maintain in the future, we decided to switch the default serialization method from hessian2 to fastjson2.

Q3: What is the relationship with native JSON?

Dubbo uses the JSONB format of fastjson2 instead of the native JSON format. The JSONB format corresponds to the JSON format, can fully represent JSON, and is a binary format. For the specific protocol format, please refer to: JSONB format

Q4: What if I don’t want to use fastjson2?

If you don’t want to use fastjson2, you can configure prefer-serialization to override the default configuration for hessian2. (such as dubbo.provider.prefer-serialization=fastjson2,hessian2) If there is no special requirement, we do not recommend continuing to use hessian2.

3. Push short protection is disabled by default

Since version 3.2.0 of Dubbo, the push protection is turned off by default. Even if the registration center pushes an empty address, Dubbo will not keep the last batch of provider information. If you need to enable empty protection, you can configure dubbo.application.enable-empty-protection to true.

Q1: How does disabling push short protection affect me?

In most scenarios it has no effect. The purpose of push empty protection is that when the registration center fails and actively pushes empty addresses, Dubbo keeps the last batch of provider information to ensure service availability. However, when most registration centers fail, the registration center will not push empty addresses, only in some special cases. However, if the push short protection is turned on, it will have a greater impact on Dubbo’s Fallback logic, heartbeat logic, etc., and bring troubles to the development and use of Dubbo.

Q2: I want to enable short push protection, what should I do?

If you need to enable push empty protection for high availability in production, you can configure dubbo.application.enable-empty-protection to true. At present, it is known that turning on the push-out protection will cause the server-side application to upgrade from `2.6. In this scenario, the service call will fail. In addition, after the push-to-empty protection is turned on, when the server address is really empty, there will be more heartbeat exceptions and log exceptions.

4. Transitive dependency changes

• Dubbo version 3.2.0 no longer shade hessian-lite code in dubbo-all by default, but use transitive dependency transfer instead. If you don’t need to use hessian-lite in your application, you can remove hessian-lite from dependencies.
• From version 3.2.0 of Dubbo, gson, fastjson dependencies are no longer passed in dubbo-all, if you need to use gson, fastjson in your application, please manually install gson, fastjson ` Dependencies are added to the application.
• Dubbo 3.2.0 version passes fastjson2 dependency in dubbo-all.

5. Default internal serialization tool switch

Since version 3.2.0 of Dubbo, the default internal serialization tool is switched from fastjson to fastjson2.

Q1: Will it affect the RPC request traffic?

Won’t. The internal serialization tool is used when Dubbo internally parses parameters, not the RPC transmission serialization protocol.

Q2: Why switch the default internal serialization tool?

From version 3.2.0 of Dubbo, the default transitive dependencies no longer pass fastjson and gson. For compatibility reasons, the default internal serialization tool is switched to fastjson2.

Q3: What if there is no fastjson2 in my environment?

Dubbo supports automatic switching of various serialization frameworks. If there is no fastjson2 in your environment, Dubbo will automatically try to switch to fastsjon or gson.

Q4: I want to specify the internal serialization tool of Dubbo, what should I do?

You can configure dubbo.json-framework.prefer parameters, such as -Ddubbo.json-framework.prefer=gson.

6. Triple protocol supports passing custom exceptions

Starting from Dubbo version 3.2.0, the Triple protocol supports returning custom exceptions instead of only returning RpcException. If the service interface throws an exception, after Dubbo 3.2.0, the custom exception object will be returned by default according to the Dubbo protocol.

7. Triple protocol version number alignment

Starting from Dubbo version 3.2.0, the communication of the Triple protocol requires the version number and grouping of the client and server to be consistent, otherwise the service will not be found. When interoperating with the native gRPC SDK, the Dubbo side cannot configure groups and version numbers.

Q1: How was Dubbo before 3.2.0?

1. Triple will think that the empty version number is consistent with the 1.0.0 version number. If your server and client version numbers are inconsistent, but they are both empty version numbers or 1.0.0 version numbers, they can communicate normally.
2. For a service that does not match a version number, Triple will try to match a service with any version number. If it matches a service with any version number, it can also communicate normally.

Q2: How to ensure that it is aligned with the original behavior?

By configuring -Ddubbo.rpc.tri.ignore-1.0.0-version=true -Ddubbo.rpc.tri.resolve-fallback-to-default=true, the previous behavior of Dubbo 3.2.0 can be achieved.