dotnet-skills 序列化选型指南:Protobuf、MessagePack 与 System.Text.Json 源生成器三选一
dotnet-skills 序列化选型指南:Protobuf、MessagePack 与 System.Text.Json 源生成器三选一
dotnet-skills 是面向 .NET 开发者的 AI 编码插件,内置 30 个 skills 和 5 个专家 agent,其中 serialization(序列化)skill 就是一份完整的 .NET 序列化选型指南:Protobuf、MessagePack、System.Text.Json 源生成器该怎么选,一文讲清 🧭
🤔 为什么 .NET 序列化选型容易踩坑?
序列化不只是"把对象变成字节"这么简单。真正的问题藏在两个维度里:
| 维度 | 问题 |
|---|---|
| 类型信息的来源 | Schema-based(外部模式)性能快、AOT 兼容;Reflection-based(运行时反射)慢、且无法用于 AOT 发布 |
| 线上格式的演进 | 类型名一旦写进 payload,重命名类就会直接破坏兼容性 |
dotnet-skills 给出的核心建议很直接:凡是跨进程边界的场景(API、消息队列、事件流),优先选 schema-based 格式(详见 skills/serialization/SKILL.md)。
📋 快速选型表:按场景对号入座
不必纠结技术细节,先按你的使用场景查表(来源:skills/serialization/SKILL.md):
| 使用场景 | 推荐格式 | 推荐理由 |
|---|---|---|
| REST API | System.Text.Json(源生成器) | 标准 JSON,且 AOT 兼容 |
| gRPC 服务 | Protocol Buffers | 原生格式,版本管理优秀 |
| Actor 消息通信 | MessagePack 或 Protobuf | 紧凑、快速、版本安全 |
| 事件溯源(Event Sourcing) | Protobuf 或 MessagePack | 旧事件必须永久可读 |
| 缓存 | MessagePack | 紧凑 + 快速 |
| 配置文件 / 日志 | JSON(System.Text.Json) | 人类可读、易解析 |
💡 记住一句话:热路径选 MessagePack 或 Protobuf,对外 JSON 接口选源生成器版的 System.Text.Json。
🥇 方案一:System.Text.Json 源生成器
如果你是做 ASP.NET Core / REST API,这是默认答案。
System.Text.Json 默认走运行时反射,但在启用**源生成器(Source Generators)**后,类型信息会在编译期生成,带来四个实打实的收益:
- ✅ 无运行时反射 —— 所有类型信息编译期生成
- ✅ AOT 兼容 —— 配合 Native AOT 发布无压力(AOT 的更多细节可参考 skills/aot-trimming/SKILL.md)
- ✅ 更快 —— 省去运行时类型分析
- ✅ 裁剪安全 —— 链接器清楚知道需要保留什么
使用方式很简单:定义一个继承 JsonSerializerContext 的 partial class,用 <a href="https://link.gitcode.com/i/25b5fdfaceded4c9505399dbf492968d" target="_blank">JsonSerializable] 属性登记所有需要序列化的类型,之后读写 JSON 时传入该上下文即可。完整的上下文定义与 ASP.NET Core 集成示例见 [skills/serialization/SKILL.md。
🥈 方案二:Protocol Buffers(Protobuf)
适合:gRPC、事件溯源、Actor 系统,以及任何"要活很久"的线上格式。
Protobuf 的杀手锏是显式字段编号带来的版本演进能力:
message Order {
string id = 1;
string customer_id = 2;
// 新增字段永远安全,老版本读取器会直接忽略
string notes = 5;
}
版本管理只需记住两条红线(详见 skills/serialization/SKILL.md):
| 操作 | 是否安全 |
|---|---|
| 新增字段(新编号) | ✅ 安全,老读者自动忽略 |
删除字段并 reserved 保留编号 |
✅ 安全 |
| 修改字段类型 | ❌ 会破坏兼容 |
| 复用已删除的字段编号 | ❌ 会破坏兼容 |
🥉 方案三:MessagePack
适合:高性能场景、紧凑 payload、Actor 消息。
MessagePack 是二进制格式,体积比 JSON 小、编解码更快,序列化后的字节流在热路径上的吞吐表现最好。
- 通过
[MessagePackObject]+[Key(n)]特性显式声明字段序号,版本演进逻辑与 Protobuf 类似 - 类标记为
partial后可启用源生成器模式,同样获得 AOT 兼容能力 - 在 Akka.NET 中配置
MessagePackSerializer绑定消息类型后,Actor 消息即可自动走该格式(配置示例见 skills/serialization/SKILL.md)
⚠️ 这些格式请直接排除
skill 中明确列出了"黑名单",新手尤其注意:
| 格式 | 问题 |
|---|---|
| BinaryFormatter | 存在安全漏洞,已弃用,永远不要用 |
| Newtonsoft.Json 默认模式 | 类型名嵌入 payload,重命名即破坏兼容 |
| DataContractSerializer | 复杂、版本管理差 |
| XML | 冗长、慢、复杂 |
⚡ 性能对比:谁的吞吐更高?
dotnet-skills 给出的近似吞吐量与体积对比(★ 越多越好):
| 格式 | 序列化 | 反序列化 | 体积 |
|---|---|---|---|
| MessagePack | ★★★★★ | ★★★★★ | ★★★★★ |
| Protobuf | ★★★★★ | ★★★★★ | ★★★★★ |
| System.Text.Json(源生成) | ★★★★☆ | ★★★★☆ | ★★★☆☆ |
| System.Text.Json(反射) | ★★★☆☆ | ★★★☆☆ | ★★★☆☆ |
| Newtonsoft.Json | ★★☆☆☆ | ★★☆☆☆ | ★★★☆☆ |
结论:消息热路径上,优先 MessagePack 或 Protobuf(完整对比见 skills/serialization/SKILL.md)。
🔒 保持线上格式兼容的三条军规
分布式系统里,"格式还能不能安全演进"往往比"现在多快"更重要。skill 总结了三个经典模式(详见 skills/serialization/SKILL.md):
- 宽容读取器(Tolerant Reader):老代码必须能安全忽略未知字段,而不是报错
- 先读后写(Introduce Read Before Write):先全量部署支持新格式的"读取端",再在下一个版本启用"写入端"
- 永远不要在 payload 里嵌入类型名:用显式的判别字段(discriminator)代替,重构才安全
🚀 如何在你的项目里用上这套选型指南
dotnet-skills 支持 Claude Code、Codex、GitHub Copilot、OpenCode 等多种 AI 编码助手,安装方式与技能清单见 README.md。
安装后,在 AI 助手中通过 /skills 或 $serialization 等命令即可调用该技能;它覆盖选型、AOT 适配、Newtonsoft.Json 迁移(含多态判别字段的写法)等完整流程。配套的 API 设计技能 skills/csharp-api-design/SKILL.md 也从接口设计角度给出了同一套 schema-based 优先的结论,两者互为补充。
✅ 一句话总结
- 对外 JSON 接口 → System.Text.Json 源生成器
- gRPC / 事件溯源 / 长生命周期线上格式 → Protobuf
- 缓存 / Actor 消息 / 极致吞吐 → MessagePack
- 黑名单 → BinaryFormatter 和反射式默认配置
选对序列化格式,你的 .NET 服务在性能、AOT 兼容性和版本演进上都会更从容 🎯