Upgrade from 3.1 to 3.2

Dubbo 3.2 Upgrade and Compatibility Guide

For the vast majority of users, upgrading to Dubbo 3.2.0 is completely smooth, requiring only changes to the dependency version.

  1. <dependency>
  2.     <groupId>org.apache.dubbo</groupId>
  3.     <artifactId>dubbo</artifactId>
  4.     <version>3.2.0</version>
  5. </dependency>

Or

  1. <dependency>
  2.     <groupId>org.apache.dubbo</groupId>
  3.     <artifactId>dubbo-spring-boot-starter</artifactId>
  4.     <version>3.2.0</version>
  5. </dependency>

Compatibility CheckList

1. Serialization Check Mode (Important!!!)

In Dubbo 3.2.0, Dubbo will enable strong validation of the serialization whitelist by default to improve security and avoid remote command execution issues. For users with large service scales or those using generics, we recommend adding the configuration -Ddubbo.application.serialize-check-status=WARN. After monitoring for a while (via logs, QoS commands), if no security warnings are triggered, strong validation mode can be configured.

For information on configuring a custom whitelist, refer to the official documentation / SDK manual / Java SDK / advanced features and usage / improving security / class checking mechanism.

Q1: Why enable strong validation of the serialization whitelist?

Due to issues with Java’s mechanisms, non-IDL serialization supported by Dubbo inherently allows access to any class, which can lead to the risk of remote command execution (RCE).

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

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

2. Default Serialization Switch

Starting from Dubbo 3.2.0, the default serialization method has switched from hessian2 to fastjson2. For applications upgrading to 3.2.0, Dubbo will automatically attempt to use fastjson2 for serialization.

Q1: Will this affect interoperability with lower versions of Dubbo?

No. Interoperability with lower versions still uses hessian-lite. For more information, refer to the serialization protocol upgrade guide.

Q2: Why switch the default serialization method?

fastjson2 is a high-performance serialization framework that outperforms hessian2, natively supports JDK17, Native, and is fully backward compatible with all functionalities of hessian2. As hessian-lite becomes increasingly difficult to maintain, we decided to switch the default serialization method from hessian2 to fastjson2.

Q3: What is the relationship with native JSON?

In Dubbo, fastjson2 uses the JSONB format, not the native JSON format. JSONB corresponds to JSON and can fully represent it as a binary format. For specific protocol formats, refer to: JSONB Format.

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

If you do not want to use fastjson2, you can configure prefer-serialization to hessian2 to override the default configuration. (e.g., dubbo.provider.prefer-serialization=fastjson2,hessian2). If there are no special requirements, we do not recommend continuing to use hessian2.

3. Default Empty Protection Disabled

Starting from Dubbo 3.2.0, empty protection is disabled by default. Even if the registry pushes empty addresses, Dubbo will not retain the last batch of provider information. To enable empty protection, configure dubbo.application.enable-empty-protection to true.

Q1: What impact does disabling empty protection have?

In the vast majority of scenarios, there is no impact. The purpose of empty protection is to retain the last batch of provider information when the registry fails and actively pushes empty addresses to ensure service availability. However, during most registry failures, the registry also does not push empty addresses, occurring only in special cases. Enabling empty protection, however, can significantly affect Dubbo’s fallback logic, heartbeat logic, etc., causing issues for developers using Dubbo.

Q2: How do I enable empty protection?

If high availability requires enabling empty protection in production, configure dubbo.application.enable-empty-protection to true. Currently, it is known that enabling empty protection can cause server applications from versions 2.6.x, 2.7.x, which only support interface-level service discovery, to rollback to the original version after upgrading to 3.x, leading to exceptions, and in extreme cases, service invocation failures. Additionally, enabling empty protection can cause more heartbeat anomalies and log exceptions when the server address is truly empty.

4. Transitive Dependency Changes

  • Starting from Dubbo 3.2.0, hessian-lite code will no longer be shaded in dubbo-all by default, but passed as transitive dependencies. If your application does not require hessian-lite, you can remove it from dependencies.
  • Starting from Dubbo 3.2.0, gson and fastjson dependencies are no longer passed in dubbo-all. If your application requires gson or fastjson, please manually add them to your application.
  • Dubbo 3.2.0 introduces fastjson2 as a transitive dependency in dubbo-all.

5. Default Internal Serialization Tool Switch

Starting from Dubbo 3.2.0, the default internal serialization tool has switched from fastjson to fastjson2.

Q1: Will this affect RPC request traffic?

No. The internal serialization tool is used when Dubbo internally parses parameters, not for RPC transport serialization protocols.

Q2: Why switch the default internal serialization tool?

Starting from Dubbo 3.2.0, fastjson and gson are no longer passed as transitive dependencies. For compatibility reasons, the default internal serialization tool has switched to fastjson2.

Q3: What if my environment does not have fastjson2?

Dubbo supports various serialization frameworks for automatic switching. If your environment does not have fastjson2, Dubbo will attempt to switch to fastjson or gson.

Q4: How can I specify Dubbo’s internal serialization tool?

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

6. Triple Protocol Support for Custom Exceptions

Starting from Dubbo 3.2.0, the Triple protocol supports returning custom exceptions instead of only returning RpcException. If your service interface may throw exceptions, starting from Dubbo 3.2.0, custom exception objects will be returned by default as per Dubbo protocol.

7. Triple Protocol Version Alignment

Starting from Dubbo 3.2.0, the communication requirements of the Triple protocol mandate that the client and server version numbers and groups must match; otherwise, the service cannot be found. When interoperating with the native gRPC SDK, the Dubbo side cannot configure groups and version numbers.

Q1: How was it before Dubbo 3.2.0?

  1. Triple considers an empty version number to be equivalent to version number 1.0.0; if your server and client version numbers do not match but are both empty or both 1.0.0, they can communicate normally.
  2. For services without matching version numbers, Triple will attempt to match any version; if a service with any version matches, communication can occur normally.

Q2: How to ensure alignment with the original behavior?

By configuring -Ddubbo.rpc.tri.ignore-1.0.0-version=true -Ddubbo.rpc.tri.resolve-fallback-to-default=true, you can achieve alignment with the behavior before Dubbo 3.2.0.

Feedback

Was this page helpful?

Yes No

Last modified September 30, 2024: Update & Translate Overview Docs (#3040) (d37ebceaea7)