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.
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
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
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
hessian-lite will become more and more difficult to maintain in the future, we decided to switch the default serialization method from
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
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
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
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
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
dubbo-allby default, but use transitive dependency transfer instead. If you don’t need to use
hessian-litein your application, you can remove
- From version 3.2.0 of Dubbo,
fastjsondependencies are no longer passed in
dubbo-all, if you need to use
fastjsonin your application, please manually install
fastjson` Dependencies are added to the application.
- Dubbo 3.2.0 version passes
5. Default internal serialization tool switch
Since version 3.2.0 of Dubbo, the default internal serialization tool is switched from
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
gson. For compatibility reasons, the default internal serialization tool is switched to
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
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
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?
- 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.
- 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?
-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.