---
title: Dubbo 序列化机制深度解析
author: Aias
date: 2026-07-08
coverImage: imgs/cover.png
---

# Dubbo 序列化机制深度解析

本文将 Dubbo 序列化作为调用路径决策进行分析，而非仅作为可插拔编解码器列表。核心区别在于：经典 Dubbo 二进制协议的线头携带 5 位序列化 ID，而 Triple/HTTP2 的 HTTP/2/gRPC 封装固定，但内部载荷可以是原生 protobuf 或 Dubbo 包装器，后者再委托回序列化 SPI。

## 当前实现映射

核心 SPI 是 `org.apache.dubbo.common.serialize.Serialization`。它暴露：

- `getContentTypeId()`：Dubbo 协议头使用的数字 ID。Javadoc 明确警告自定义 ID 不能超过 `ExchangeCodec.SERIALIZATION_MASK`（`31`），因为只有 5 位可用
- `getContentType()`：文本媒体类型
- `serialize(URL, OutputStream)` 和 `deserialize(URL, InputStream)`：`ObjectOutput` 和 `ObjectInput` 的自适应工厂

ID 表位于 `dubbo-serialization-api` `Constants`。当前重要 ID：

| 序列化器 | ID | 当前主仓库模块 |
| --- | ---: | --- |
| Hessian2 | `2` | `dubbo-serialization-hessian2` |
| Fastjson2 | `23` | `dubbo-serialization-fastjson2` |
| Kryo | `8` | 历史/移出 |
| FST | `9` | 历史/移出 |
| Kryo 优化版 | `25` | 历史/移出 |

当前主仓库 SPI 文件只注册：

- `hessian2=org.apache.dubbo.common.serialize.hessian2.Hessian2Serialization`
- `fastjson2=org.apache.dubbo.common.serialize.fastjson2.FastJson2Serialization`
- `wrapper=org.apache.dubbo.common.serialize.DefaultSerializationExceptionWrapper`

这意味着常量比当前内置模块更广。它们保留线兼容性和扩展 ID 分配，但不应解读为"所有序列化器今天都捆绑在这里"。

![serialization-id-table.png](https://developer.qcloudimg.com/http-save/yehe-7136204/0ddf68b1cb963c7883f1f91e822b8b98.png)

## Dubbo 协议路径

经典 Dubbo RPC 使用 `ExchangeCodec` 和 `DubboCodec`。

编码时：

1. `ExchangeCodec` 解析 `Serialization` 扩展
2. 请求标志存储 `FLAG_REQUEST | serialization.getContentTypeId()`；响应在同一标志字节只存序列化器 ID
3. `DubboCodec.encodeRequestData` 通过 `ObjectOutput` 写 Dubbo 版本、服务名、服务版本、方法名、参数描述符、参数和附件
4. `DubboCodec.encodeResponseData` 写响应标记字节，然后返回值或异常，再写支持的响应附件

解码时：

1. `DubboCodec.decodeBody` 提取 `proto = header[2] & SERIALIZATION_MASK`
2. `DecodeableRpcInvocation` 和 `DecodeableRpcResult` 调用 `CodecSupport.getSerialization(serializationType).deserialize(...)`
3. 解码调用存储 `SERIALIZATION_ID_KEY`；响应解码检查响应使用与请求相同的序列化 ID
4. 提供者端解码还通过序列化 keeper 路径验证请求的序列化对该服务允许

操作含义：序列化器协商是分布式契约。双方需要相同扩展 ID、相同扩展实现和兼容对象 schema。错误 ID 会造成线级解码失败，而非优雅降级问题。

![dubbo-protocol-flow.png](https://developer.qcloudimg.com/http-save/yehe-7136204/62284b5fe3bf13eae7dea7b6d732ad2a.png)

## Hessian2

`Hessian2Serialization` 仍被代码文档称为默认 Dubbo 序列化协议。返回 ID `2` 和内容类型 `x-application/hessian2`。

现代 Hessian2 路径非裸 Hessian 工厂。`Hessian2FactoryManager` 每个类加载器创建 `Hessian2SerializerFactory` 实例，对最近类加载器有粘性缓存，其余在映射中。工厂在两处集成 `DefaultSerializeClassChecker`：

- 类加载：`loadSerializedClass` 委托给 Dubbo 类检查器
- 对象序列化器/反序列化器选择：类预先检查，必须通过 `Serializable` 检查（除非显式允许非序列化）

安全控制由配置驱动：

- `dubbo.hessian.whitelist=true` 将 Hessian 类工厂切换到白名单模式，并将 Dubbo 序列化检查设为 `STRICT`
- `dubbo.hessian.allow` 添加接受的包/类模式
- `dubbo.hessian.deny` 在白名单模式未激活时添加拒绝模式
- `dubbo.hessian.allowNonSerializable=false` 是默认值

性能方面，Hessian2 对 Java 到 Java RPC 仍是好默认，因为紧凑、二进制、面向对象。风险是它也是通用对象反序列化器。其安全依赖保持 Dubbo 类检查启用并将生产工作负载转向严格白名单。

兼容方面，Hessian2 对许多 Java bean 变化宽容，但非 schema-first。重命名、类型变更、类加载器差异、非标准构造器、Record 和 JDK 模块行为仍可表现为运行时解码失败。提交 `7618e10199`（"Fix unable to deserialize Record using Hessian2"，2024-10-28）是新 Java 语言形态仍需序列化器工作的具体例子。

## Fastjson2

`FastJson2Serialization` 返回 ID `23` 和内容类型 `text/jsonb`。尽管内容类型看起来像文本，实现使用 Fastjson2 `JSONB`。`FastJson2ObjectOutput.writeObject` 将每个值序列化为：

1. 带 `WriteClassName`、`FieldBased`、引用检测、null 写入、符号名和可选 `ErrorOnNoneSerializable` 的 JSONB 字节
2. 4 字节大端长度前缀
3. JSONB 载荷

`FastJson2ObjectInput` 镜像此形状：读 4 字节长度、读载荷、用 `JSONReader` 特性解析、验证结果类型与预期类兼容。

Fastjson2 主安全边界是 AutoType。Dubbo 通过 Fastjson2 的 `ContextAutoTypeBeforeHandler` 将 `Fastjson2SecurityManager.Handler` 连接到 `SerializeSecurityManager`：

- 白名单名直接接受
- `STRICT` 拒绝未列类
- `WARN` 记录未列类但仍允许（如果可加载）
- 禁止前缀在正常类加载前就拒绝
- 可选 `ErrorOnNoneSerializable` 强制 Serializable 兼容

Fastjson2 在团队想要更 JSON 模型或 JSONB 性能特征时有用，但携带比 schema-first 格式更锐利的类名兼容表面。因 Dubbo 写类元数据并使用基于字段解析，类/包重命名和字段类型变更需显式兼容规划。

## Kryo 和 FST 历史

Kryo 和 FST 是历史 Dubbo 序列化器，非当前主仓库内置模块。最重要提交是 `8bdecea7ef`（"Move some SPI extensions to apache/dubbo-spi-extensions, add sub package modules"，2020-08-17），从主仓库移除许多序列化器模块，包括：

- `dubbo-serialization-kryo`
- `dubbo-serialization-fst`
- `dubbo-serialization-avro`
- `dubbo-serialization-fastjson`
- `dubbo-serialization-gson`
- `dubbo-serialization-protostuff`
- protobuf 序列化器支持模块

历史提交显示为何 Kryo/FST 通常是性能驱动选择，而非保守默认：

- `89f6d6d262`（"Fix ContentTypeId conflict"，2019-05-05）调整多序列化器 ID，含 FST 和 Kryo。凸显序列化器 ID 是公共线契约部分
- `2dabc7a841`（"Remove reuse ID"，2020-01-08）添加独立 ID，含优化 Kryo 路径（`KRYO_SERIALIZATION2_ID = 25`），再次强化 ID 重用一旦数据上线就不安全
- `bcacaf72c6`（"Fix the problem that occurs when using kryo to deserialize Attachments"，2021-05-22）修复 Kryo 附件反序列化问题，显示框架元数据和用户载荷共享高性能对象序列化器时出现的边界情况

权衡轮廓清晰：

- Kryo/FST 在受控 Java 专用部署中可快且紧凑
- 它们跨类演进、JDK 升级、类加载器差异、注册选择和反射/unsafe 行为更脆弱
- 它们对广泛互操作是差选择
- 安全视角，它们仍是对象反序列化器。视为可信内部格式，除非扩展显式集成 Dubbo 现代类检查控制

## Triple 和 HTTP2 编码

Triple 分离传输帧与对象序列化。

对于 gRPC 兼容 Triple 流量，`RequestMetadata.toHeaders()` 写 `content-type: application/grpc+proto`、`te: trailers`、`:path`、超时、服务版本/分组、应用元数据和压缩头。体用标准 gRPC 消息封装：

- 1 字节压缩标志
- 4 字节大端消息长度
- 消息字节

`GrpcStreamingDecoder` 强制首字节保留位并在压缩标志设置时处理解压。`GrpcCompositeCodec.encode` 写相同 1 + 4 封装并将内部消息委托给 `PackableMethod`。

有两种内部载荷模式：

![triple-modes.png](https://developer.qcloudimg.com/http-save/yehe-7136204/8012e506d9f7e0c0062e60724e6266e6.png)

1. **原生 protobuf 模式**：如果方法参数和返回类型是生成的 protobuf 消息，`ReflectionPackableMethod` 用 `PbArrayPacker` 和 `PbUnpack`。载荷是 protobuf 字节，由 `Message.writeTo` 或 `Message.toByteArray` 生成。这是最安全最可互操作的 Triple 路径
2. **包装器模式**：如果方法是普通 Java 方法、`$echo`、泛型调用或其他非纯 protobuf，`ReflectionPackableMethod` 将请求/响应包装在 `TripleCustomerProtocolWrapper`。包装器携带 `serializeType`、参数类型名、响应类型和嵌套数据字节。嵌套字节由 `MultipleSerialization` 生产，将 `hessian4` 回映射到 `hessian2` 然后委托给正常 `Serialization` SPI

这意味"Triple 用 protobuf"只对 protobuf 形服务成立。对 POJO 或泛型服务通过 Triple，反序列化风险通过包装器的 `serializeType` 和嵌套 `MultipleSerialization` 调用重新进入。

Triple 用显式检查缓解部分风险。提交 `03647452d5`（"triple serialize check"，2023-04-06）和 `bd57066e71`（"tri serial check"，2023-04-08）通过 `CodecSupport.checkSerialization(serializeType, allSerialize)` 添加包装器序列化验证，使包装器不能自由选择 URL 允许序列化集外的任意序列化器。

性能方面，当前 Triple 路径已向流调优：提交 `678d2a7831`（"Refactor tri pack & unpack use stream"，2026-02-05）改变 pack/unpack 路径在流上操作并添加基于流的包装器解析，对大消息减少不必要中间字节数组。

## 安全边界

序列化安全边界是条件的，非绝对的。

![security-boundary.png](https://developer.qcloudimg.com/http-save/yehe-7136204/c2086768986b5f7218006a3ccdf9c8ff.png)

重要属性：

- 网络对等方可发送变为应用对象的字节。无认证/TLS 和严格类检查，那是大信任边界
- Hessian2 和 Fastjson2 集成 Dubbo 的 `SerializeSecurityManager`。最强模式是带维护应用白名单的 `STRICT`
- `WARN` 模式是可观测模式，非硬安全边界。它记录未知类但仍可反序列化
- `serialize.check.serializable=true` 减少意外不安全对象，但不等价于 gadget-chain 防止。许多危险类实现 `Serializable`
- 原生 Java 序列化如通过扩展存在，风险更高，不应声明除非有严格兼容要求
- Triple protobuf 模式对消息体避免泛型 Java 对象反序列化。Triple 包装器模式不；包装器验证后委托给正常 Dubbo 序列化器

`docs/threat-model.md` 中现有威胁模型与此一致：Dubbo 默认假设内部/可信部署，而严格反序列化控制是 opt-in。

## 兼容边界

兼容有三个独立维度：

![compatibility-dimensions.png](https://developer.qcloudimg.com/http-save/yehe-7136204/c1aeffb4bfb62a25b77c6596783ba077.png)

1. **线 ID 兼容**：经典 Dubbo 要求头中序列化器 ID 双方映射到相同实现。ID 冲突是协议 bug，如 `89f6d6d262` 和 `2dabc7a841` 显示
2. **对象 schema 兼容**：Hessian2/Fastjson2/Kryo/FST 携带 Java 对象假设。类名、包名、字段类型、构造器、Record 和类加载器都重要
3. **协商兼容**：`UrlUtils` 按 `prefer.serialization`、`serialization`、默认排序。`CodecSupport.checkSerialization` 确保请求序列化器属于声明集。声明太多序列化器同时扩宽兼容表面和攻击表面

对 Triple，protobuf 服务加第四维度：**protobuf schema 演进**。字段号和消息定义变为持久契约，通常对跨语言和长寿 API 更好。

## 历史提交时间线

| 提交 | 日期 | 信号 |
| --- | --- | --- |
| `89f6d6d262` | 2019-05-05 | 修复多序列化器内容类型 ID 冲突，含 Kryo/FST |
| `2dabc7a841` | 2020-01-08 | 移除 ID 重用，为优化路径分配独立 ID |
| `8bdecea7ef` | 2020-08-17 | 从主仓库移除多 SPI 序列化器模块，含 Kryo 和 FST |
| `bcacaf72c6` | 2021-05-22 | 修复 Kryo 附件反序列化，显示框架元数据边界情况 |
| `f1af604e7e` | 2022-07-15 | 添加 Fastjson2 支持，ID `23` |
| `84c1c35aae` | 2023-01-11 | 添加通用序列化类检查基础设施，集成 Hessian2/Fastjson2 |
| `03647452d5` | 2023-04-06 | 添加 Triple 包装器序列化验证 |
| `bd57066e71` | 2023-04-08 | 精化 Triple 序列化检查 |
| `0d879666b4` | 2023-12-04 | 使 Fastjson2/Hessian2 依赖可排除，添加类路径检查 |
| `225ca9d232` | 2024-05-22 | 更新 hessian-lite 到 4.0.0，设置 Hessian 序列化回退 |
| `7618e10199` | 2024-10-28 | 修复 Hessian2 Java Record 反序列化 |
| `678d2a7831` | 2026-02-05 | 重构 Triple pack/unpack 为基于流路径 |

## 实践分析清单

审查或变更序列化行为时：

- 先检查线协议：经典 Dubbo 头 ID vs Triple HTTP2/gRPC 封装
- 确认调用路径是 protobuf 模式还是 Triple 包装器模式
- 验证提供者声明序列化集；不声明不需要的格式
- 经典 Java 到 Java Dubbo RPC 偏好带严格白名单的 Hessian2
- 跨语言或外暴露 HTTP2 服务偏好 protobuf 形 Triple API
- 将 Fastjson2 视为带类元数据的 JSONB，非普通 JSON
- 将 Kryo/FST 视为历史/高性能扩展选择，需更高兼容和安全审查要求
- 安全敏感部署将序列化检查设为 `STRICT`，维护 `security/serialize.allowlist`，用生产 DTO 测试启动/解码路径
- 兼容变更测试滚动升级双向：旧消费者到新提供者，新消费者到旧提供者

本文将 Dubbo 序列化作为调用路径决策进行分析，而非仅作为可插拔编解码器列表。核心区别在于：经典 Dubbo 二进制协议的线头携带 5 位序列化 ID，而 Triple/HTTP2 的 HTTP/2/gRPC 封装固定，但内部载荷可以是原生 protobuf 或 Dubbo 包装器，后者再委托回序列化 SPI。

Dubbo 序列化机制深度解析

软件研发

编程语言

后端

架构设计

深度解析Dubbo序列化机制，对比经典Dubbo二进制协议与Triple/HTTP2协议差异，详解Hessian2、Fastjson2等序列化器实现原理及安全控制，提供序列化器选择建议与兼容性分析。

JSON

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Dubbo 序列化机制深度解析-腾讯云开发者社区-腾讯云

Dubbo 序列化机制深度解析

Dubbo 序列化机制深度解析

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐