3.1 Upgrade to 3.2 Operation Guide

Quickly understand the upgrade steps and compatibility of Dubbo 3.2

Function modification points

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

2. Default serialization switch

  • Starting from version 3.2.0 of Dubbo, 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. Default internal serialization tool switch

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


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

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

5. Push short protection is disabled by default

  • Dubbo version 3.2.0 starts to disable push protection by default, even if the registration center pushes empty addresses, 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.

Last modified January 2, 2023: Enhance en docs (#1798) (95a9f4f6c)