Dubbo 官方 Java SDK 版本发布信息截图
本次涉及超过 100 个 Dubbo 后端服务的升级，过程沉淀了一些素材，也踩了不少坑。由于一些客观限制，无法提供太多系统截图，但我会将关键信息整理成文，希望能为有类似升级需求的同学提供一份参考资料。
01 Dubbo 升级背景与要求
由于安全合规要求，我们需要将服务注册中心从自建的 Nacos 迁移到阿里云 MSE Nacos。但云上 MSE Nacos 对客户端的 Dubbo 版本有最低要求，我们现有的服务基于 Dubbo 3.0.10，因此必须至少升级到 3.1.x 版本。本文将重点分享从 3.0.10 升级到 3.1.11，以及进一步升级到 3.2.16 的过程和注意事项。
02 官方版本推荐
进行版本升级前，首要任务是确定目标版本。我们参考了 Dubbo 官方的版本推荐页面：https://cn.dubbo.apache.org/zh-cn/download/
截止 2026 年 3 月 17 日，官方推荐的最稳定版本如下：
- 3.1.11: 3.1.x 系列的当前仅进行安全维护的版本。
- 3.2.19: 3.x 用户建议升级到的最新稳定版本。
- 3.3.6: 包含了最新特性的版本。
因此，我们的升级目标非常明确。但在直接跳转到这些推荐版本之前，充分了解中间各个版本的变更至关重要。
03 版本升级路径与详细变更
为了彻底评估升级带来的影响，我梳理了从 3.0.10 到目标版本之间所有中间版本的 Release Notes，重点关注修复的 Bug 和新增的 Feature。这有助于提前预判风险。
整个升级路径主要跨越三个大版本线：3.1.x, 3.2.x, 3.3.x。鉴于 3.3.x 引入较多新特性，我们选择先升级到 3.1.11 或 3.2.16/19 作为稳定目标。
1. 3.0.10 -> 3.0.15 (最后的小版本迭代)
2. 3.1.0 -> 3.1.11 (目标版本线之一)
3. 3.2.0 -> 3.2.16 (另一目标版本线)
注意：大版本的更新跨度较大，在升级时要特别注意 API 和配置的向后兼容性问题，这也是 后端 & 架构 迭代中常遇到的挑战。
04 升级注意事项与踩坑记录
实际升级过程远不止修改版本号那么简单，下面是我们遇到的一些典型问题。
4.1 踩坑细节汇总
| 问题现象 |
可能原因 |
解决/规避方案 |
MetadataInfo#getParameter #NPE |
Fastjson2 对特殊字符反序列化失败 |
排除 Fastjson2 依赖 |
日志不断输出 disconnected、established |
dubbo 3.2.16 对日志修改，会打印 K8s 存活探针日志、NettyServerHandler 的 disconnect 日志 |
调整相关日志级别 |
| REST 实现变动：servlet server -> netty server |
3.2 版本改动了 REST server 的实现，移除所有 servlet 的 server |
可切换实现类，但可能不兼容上层应用的 API |
Unsupported protocol 协议不支持 |
由问题MetadataInfo#getParameter #NPE 导致，生成 empty//xxx 协议 |
排除 Fastjson2 依赖 |
No Provider 服务找不到（偶现） |
多种原因共同导致 |
排除上述 NPE 问题；且升级后未重现 |
4.2 3.2.x 版本的重点变化 (REST 协议)
如果你使用了 Dubbo 的 REST 协议，升级到 3.2.x 需要特别注意，这是一个破坏性变更：
- REST Server 只支持 Netty，配置成其他最终实例化都是使用
NettyHttpRestServer。
- 原生 REST 协议（Netty Server）不支持设置 HTTP Status Code。
- 不能直接使用 JAX-RS 标准的
@Context 注解获取 Servlet 上下文信息。
- 不能使用 JAX-RS 标准的
ExceptionMapper。
- 不能输出 HTTP 日志。
dubbo-rpc-rest 包依赖了 JAX-RS 的实现 RESTEasy，但不能处理 javax.ws.rs.core.Response。
虽然可以通过 RpcContext.getContext().getRequest(NettyRequestFacade.class) 来获取请求上下文进行兼容，但在上下游服务未全部升级的灰度过程中，一旦有未升级的服务参与调用链，上下文获取可能会失败，导致调用异常或数据丢失。
4.3 序列化协议升级
在 3.1.0 版本中，Dubbo 默认支持的序列化协议新增了对 Fastjson2 的支持。在 3.2.0 版本中，默认序列化方式从 hessian2 切换为了 fastjson2。
服务端和客户端版本不一致可能导致序列化协议不匹配。好在 3.2.0 引入了 prefer-serialization 配置，可以完美解决服务端序列化升级带来的风险。
官方关于序列化升级的注意事项：https://cn.dubbo.apache.org/zh-cn/overview/mannual/java-sdk/reference-manual/serialization/serialization-upgrade/
4.4 GitHub 上的相关讨论
4.5 关键兼容性检查项
请在升级前，务必检查并处理以下配置：
| 检查项目 |
具体描述与操作 |
检查 application.yml 是否配置了 dubbo.registry.group |
从 Dubbo 3.1.0 开始，dubbo.registry.group 属性被重新启用，用于对齐 Nacos 注册中心中的分组。如果原先没配，可以跳过；如果原先配置了，则需要确保升级后该配置生效。 |
| 添加序列化检查降级配置 |
在升级 Dubbo 3.2.0 版本前，建议在 JVM 参数或配置中添加 -Ddubbo.application.serialize-check-status=WARN，以保证最佳的兼容性，避免因序列化白名单强校验导致的问题。 |
| 处理默认序列化变更 |
Dubbo 3.2.0 开始默认序列化方式从 hessian2 切换为 fastjson2。如果对序列化有要求，可以在服务提供者端配置 dubbo.provider.prefer-serialization=fastjson2,hessian2，以兼容老版本消费者。 |
4.6 其他常见问题索引
05 K8s 存活探针日志优化（额外项）
在 Kubernetes 环境中，如果使用了 Dubbo 的 Qos 端口作为存活探针（liveness probe）的检查端点，默认日志级别下会打印大量探测日志。建议屏蔽以减少日志噪声。
参考文章：
K8s 存活探针日志配置示例截图
logback.xml 配置示例：
<!-- k8s liveness probe qos日志很多，不打印 -->
<logger name="org.apache.dubbo.qos.command" level="warn" additivity="false"/>
application.yml 配置示例：
logging:
level:
org.apache.dubbo.qos.command: warn
06 充分的测试是保障
大规模框架升级离不开充分、多维度的测试。绝对不能只修改版本号就匆忙上线。以下是一些必须覆盖的测试视角：
- 单服务测试：确保升级后的服务能独立正常启动、注册、提供和消费服务。
- 集群测试：测试服务在集群部署下的行为，包括负载均衡、容错等。
- 消费者/提供者交叉测试：验证新版本消费者调用老版本提供者，以及老版本消费者调用新版本提供者等多种场景。
- 注册模式测试：如果使用了
instance 或 all 等不同的注册模式，需分别验证。
- 全链路灰度：在真实业务流量下进行小规模灰度发布，观察监控指标和错误日志。
只有测试到位，才能最大程度避免升级带来的兼容性风险对线上业务造成影响。
结语：从 Dubbo 3.0.10 跨越到 3.1.x 或 3.2.x，不仅是为了满足某个中间件的版本要求，更是对整套 Java 微服务体系的一次梳理和升级。过程中遇到的序列化、REST 协议变更等问题，都是深入理解 Dubbo 框架内部机制的契机。希望这份来自实战的总结，能在你的升级之路上提供一些切实的帮助。如果你有更多经验或问题，欢迎到 云栈社区 与更多开发者交流探讨。
发表于 1 小时前
|
查看: 5|
回复: 0
