版本变更记录 on Apache Dubbo

2.x 升级至 3.x

Mon, 01 Jan 0001 00:00:00 +0000

升级到 Dubbo 3.X 的收益

Dubbo3 依旧保持了 2.x 的经典架构，以解决微服务进程间通信为主要职责，通过丰富的服务治理（如地址发现、流量管理等）能力来更好的管控微服务集群；Dubbo3 对原有框架的升级是全面的，体现在核心 Dubbo 特性的几乎每个环节，通过升级实现了稳定性、性能、伸缩性、易用性的全面提升。

通用的通信协议。 全新的 RPC 协议应摒弃私有协议栈，以更通用的 HTTP/2 协议为传输层载体，借助 HTTP 协议的标准化特性，解决流量通用性、穿透性等问题，让协议能更好的应对前后端对接、网关代理等场景；支持 Stream 通信模式，满足不同业务通信模型诉求的同时给集群带来更大的吞吐量。
面向百万集群实例，集群高度可伸缩。 随着微服务实践的推广，微服务集群实例的规模也在不停的扩展，这得益于微服务轻量化、易于水平扩容的特性，同时也给整个集群容量带来了负担，尤其是一些中心化的服务治理组件；Dubbo3 需要解决实例规模扩展带来的种种资源瓶颈问题，实现真正的无限水平扩容。
全面拥抱云原生。

Dubbo 3.0 新特性

Dubbo 3.0 提供的新特性包括：

新的地址发现模型（应用级服务发现）。
- 查看应用级服务发现迁移示例。
- 查看应用级服务发现的迁移步骤
- 查看应用级服务发现地址迁移规则说明
下一代基于 HTTP/2 的 Triple 协议。
- 查看Triple 协议迁移步骤
- 查看 Triple 协议使用方式
- 查看 Triple 协议设计与实现。
统一的路由规则。
- 查看统一路由规则设计与实现

升级前的兼容性检查

在跨版本升级的过程中，存在的风险点从大到小分别有：直接修改 Dubbo 源码 -> 基于 Dubbo SPI 扩展点进行扩展 -> 基于 API 或者 Spring 的使用方式。

1. 直接修改 Dubbo 源码

对于直接修改 Dubbo 源码这部分的需要修改方自行判断是否在高版本中正常工作，对于这种非标准行为，Dubbo 无法保证其先前的兼容性。此外，通过 javagent 或者 asm 等通过运行时对 Dubbo 的修改也在此范围内。此类修改大部分可以通过后文提供的扫描工具检测出来。

3.0 升级至 3.1

Mon, 01 Jan 0001 00:00:00 +0000

功能修改点

1. Nacos Group 对齐（应用级服务发现）

在 Dubbo 2.7.x 中，配置在 Nacos Registry URL 上的 group 值是对齐 Nacos 注册中心中的 group 分组的。（group 可以当成类似 namespace 的软隔离）

在 Dubbo 3.0.x 中，配置在 Nacos Registry URL 上的 group 默认不使用，全部使用 DEFAULT_GROUP。（group 不再提供隔离功能）

在 Dubbo 3.1.x 中，配置在 Nacos Registry URL 上的 group 值将会重新对齐 Nacos 注册中心中的 group 分组的。

注意事项：

请检查注册中心 URL 上是否已经配置了 group 属性，如果是的话需要检查服务端和消费端的 group 是否都一致，如果不一致请修改为一致
如果不希望 group 重新对齐到 Nacos 注册中心中的 group 分组，可以配置 dubbo.nacos-service-discovery.use-default-group=false 全局属性值忽略该功能

3.1 升级至 3.2

Mon, 01 Jan 0001 00:00:00 +0000

对于绝大多数的用户，升级到 Dubbo 3.2.0 是完全平滑的，仅需要修改依赖包版本即可。

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

或者

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

兼容性 CheckList

1. 序列化检查模式（重要！！！）

在 Dubbo 3.2.0 版本中，Dubbo 将默认开启序列化白名单的强校验，以提升 Dubbo 的安全性，避免远程命令执行的问题。对于一些使用了泛型等可能存在扫描不全或者是服务规模较大的用户，我们建议您添加 -Ddubbo.application.serialize-check-status=WARN 配置。观察一段时间后（通过日志、QoS 命令），如果没有触发安全告警，则可以配置强校验模式。

关于自定义白名单的配置，可以参考官网的文档 / SDK 手册 / Java SDK / 高级特性和用法 / 提升安全性 / 类检查机制一文进行配置。

Q1：为什么要开启序列化白名单的强校验？

由于 Java 本身机制的问题，Dubbo 支持的非 IDL 序列化天然允许访问任意类，这将可能导致远程命令执行（RCE）风险。

Q2：升级到 3.2 的最佳实践是什么？

我们建议所有用户在升级 Dubbo 3.2.0 版本前添加 -Ddubbo.application.serialize-check-status=WARN 配置以保证最佳的兼容性。否则可能导致线上数据异常的情况！

2. 默认序列化切换

Dubbo 3.2.0 版本开始默认序列化方式从 hessian2 切换为 fastjson2，对于升级到 3.2.0 的应用，Dubbo 会自动尝试采用 fastjson2 进行序列化。

3.2 升级至 3.3

Mon, 01 Jan 0001 00:00:00 +0000

对于绝大多数的用户，升级到 Dubbo 3.3.0 是完全平滑的，仅需要修改依赖包版本即可。

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

或者

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

兼容性 CheckList

1. 默认序列化切换

Dubbo 3.3.0 版本开始默认序列化方式从 fastjson2 切换为 hessian2，对于升级到 3.3.0 的应用，Dubbo 会自动尝试采用 hessian2 进行序列化。

Q1：为什么要切换默认序列化方式？

hessian2 为 Dubbo 3.1.x 及以下版本中默认的序列化，长期的生产验证了其稳定性和兼容性，在评估了向前兼容性和长期可维护性后，Dubbo 团队决定将 hessian-lite 升级到最新 hessian4 主干版本，以支持 JDK17 和 JDK21。

升级到 Dubbo 3.3.0 以后，依赖的 hessian-lite 版本将同步升级为 4.0.x，主要包含以下修改：

同步 hessian 到上游 4.0.66 版本
修复 JDK17 及 JDK21 下类可见性带来的兼容性问题
支持 Record、ImmutableCollections 等 JDK9+ 特性

Q2：会不会影响和低版本的 Dubbo 互通？

部分场景下可能会有影响，具体如下：