dotnet-skills 序列化选型指南:Protobuf、MessagePack 与 System.Text.Json 源生成器三选一

原创2026-10-13 21:23:381,373 阅读

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):

  1. 宽容读取器(Tolerant Reader):老代码必须能安全忽略未知字段,而不是报错
  2. 先读后写(Introduce Read Before Write):先全量部署支持新格式的"读取端",再在下一个版本启用"写入端"
  3. 永远不要在 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 兼容性和版本演进上都会更从容 🎯

登录后查看全文
dotnet-skills