Day 22:XML、JSON 与 MessagePack 的分工

昨天结尾说换一个层面。从这里开始,题目不再是定义里声明了什么,而是这些定义与数据离开内存之后怎么走。
序列化是两件事。一件是持久化:对象要存下来,下次还得原样读得回来,定义是这样存的,SessionUser 这类系统数据也是。另一件是传输:对象要送到另一端,而那一端不只一种:桌面、浏览器、iOS、Android,运行环境各不相同。
本篇说明:
- 持久化走哪一条、传输为什么分两条,分界线照什么判准画
PayloadFormat怎么决定一次调用的value送出去长什么样- 定义类的东西为什么传出去是一段 XML 字符串,不是一棵 JSON 树
- 传输类型为什么一个都不能漏注册
- 反序列化那一端,类型由谁决定,以及为什么只有一条路需要白名单
一、持久化一条路,传输两条
持久化要的是人看得懂、能进版本控制、能手动改,这一件从头到尾走 XML。
传输分两条,分界在调用端是不是 .NET:
- 前后端都是 .NET:
value走 MessagePack - 前端不是 .NET:纯 JavaScript 前端或第三方集成,
value走 JSON
外面那一层两条路都一样:一次调用送出去的是一份 JSON-RPC payload,协议规定它是 JSON,换不掉。有选择的是里面那一格 value。不另外编码的时候,它就是那份 JSON 的一部分;编码过才轮到上面那两条路。
持久化一条加传输两条,三个格式各自用擅长的那一个:
| 格式 | 在框架里负责什么 | 需要外部包 | 谁在用 |
|---|---|---|---|
| XML | 定义与系统数据的持久化,以及定义类 API 的返回内容 | 否,BCL 内置 | 定义层 |
| JSON | 外面那份 JSON-RPC payload,以及编码过的 value 的其中一种写法 |
否,BCL 内置 | API 层 |
| MessagePack | 编码过的 value 的另一种写法,也是没有另外声明时的那一个 |
是 | API 层 |
第三列不是附注,它是第四列的理由:一个格式需要外部包,它就不能放在定义层。定义层在依赖图的底部,数据库、Repository、业务逻辑、每一个前端与定义文件工具都在它下游,加在这里的任何包会沿着依赖链传染给所有消费者,而其中没有一个用得到它。
换到的东西是:日后要改传输格式,定义层零改动。代价是传输绑定必须在 API 层另外写一份,而那一份跟定义类型之间没有编译器绑着。
二、PayloadFormat 决定 value 送出去长什么样
Day 16 谈 params 那一格时提过 format 与 type,当时只写了它们在 API payload 上而不在 value 里面。这两格的内容就是这一节。
format 有三个值,决定的是同一件事:这次调用的 value 送出去要以什么形式出现。
| 值 | value 送出去长什么样 |
经过哪一个 serializer | 谁在用 |
|---|---|---|---|
Plain |
一棵 JSON 对象树,人看得懂 | 就是 JSON-RPC payload 那一份 System.Text.Json | 登录之前的几个调用 |
Encoded |
一段 Base64 | 调用端声明的那一个,序列化后压缩 | 登录本身,以及降级的落点 |
Encrypted |
一段 Base64 | 调用端声明的那一个,压缩后再加密 | 其余全部,调用端的默认值 |
压缩与加密那一段管道本身是明天的题目。
同一个方法在三个值底下都走得通,这正是把格式放在 API payload 上、而不是放在方法名或路径上的用意。对案例的登录送一个 Plain 的 API payload,value 就是一份可读的 JSON:
{"jsonrpc":"2.0","method":"System.Login",
"params":{"format":0,"value":{"userId":"demo","password":"demo"},"type":""},"id":"1"}
回来的也是可读的:
{"jsonrpc":"2.0","method":"System.Login",
"result":{"format":0,"value":{"accessToken":"033bedcf-...","userName":"Demo User",
"timeZone":"Asia/Taipei"},"type":""},"id":"1"}
同一个方法把 format 改成 1,其余一字不动,换来的是一则错误:
{"jsonrpc":"2.0","method":"System.Login",
"error":{"code":-32099,"message":"TypeName is missing for deserialization."},"id":"1"}
type 这一格只有后两个值用得到,而原因正好说明三个值的差别在哪里。Plain 的 value 从头到尾没有离开 JSON,服务端拿到的是一段还没有类型的 JsonElement,等到反射查出那个方法声明的参数类型之后,才把它反序列化成那个类型。类型是从方法签名来的,不是从 API payload 来的。后两个值不一样:它们在调用端就把对象打成一串 bytes,而 bytes 自己不带类型信息,于是类型名得写在 API payload 上跟着送。这一格因此是调用端说了算的字段,服务端在 Type.GetType 之前必须先拿它比对一份类型白名单。
Plain 不是调试用的旁路,它是启动路径。连通性探测、取得共用设置、创建连接这几个,都发生在传输密钥存在之前,那时候没有东西可以拿来加密。
三个组件,两种决定方式
value 上那三个组件各自是一个接口加一个以名字取实现的工厂,差别在名字从哪里来:
| 组件 | 名字写在哪里 | 目前有的实现 |
|---|---|---|
| serializer | 每一次调用的 API payload 上 | MessagePack、JSON |
| compressor | 部署的那份 SystemSettings |
Gzip、不压缩 |
| encryptor | 部署的那份 SystemSettings |
AES-CBC-HMAC、不加密 |
取不到对应的实现就抛异常,不会安静退回默认。
分成两种,是因为它们回答的不是同一种问题。压缩与加密回答的是这个部署要不要保护 value、用什么保护,那是部署方的决定;serializer 回答的是这个调用端写得出哪一种 value,那是调用端的能力。把后者也收进部署设置,等于要求同一台服务器上的每一个调用端都说同一种话,而第一节那两条路本来就不说同一种。
没有声明的调用一律当成 MessagePack,因为还没认识这一格的调用端送的就是它。
这三个组件整个关在两个地方:调用端在 Connector 里,服务端在 API 层里。取一页清单的方法,签名上只有查询字段、条件、排序与分页,没有一个参数跟格式有关;BO 那一端拿到的也是还原好的对象。所以日后换一个更适合的传输格式,动的是 serializer 那一格,前后端的应用代码都不必改。
三、定义类的东西为什么是一段 XML 字符串
前一节说 value 可以是 JSON 树。那么取一份 FormSchema 回来,收到的应该也是一棵。实际上不是。同一个 Plain 的 API payload,向案例要一份订单的 FormSchema,value 里只有一个字段:
{"result":{"format":0,"value":{"xml":"
一段 XML 字符串,装在 API payload 那棵 JSON 树里。定义类的东西全部走这条路。API 层只负责把字符串送到,还原成对象是调用端的 Connector 在做,所以 XmlSerializer 在每一个前端上也要跑一次。
理由是持久化那一份现成可用:定义本来就以 XML 落盘,传出去沿用同一套序列化,零额外成本。
要让定义类型也走 JSON 或 MessagePack,代价是持续的。每多一种序列化就多一组要顾的事:来回一趟数据会不会丢、反序列化时挡不挡得住不该被建出来的类型。而定义是嵌套结构、又会随版本演进,每加一个属性都要在每一种格式上再确认一次;日后换一个更适合的传输格式,整组定义类型还要再验一轮。
而它们现在的形状也确实不适合:集合属性是只读的,各自握着自己的所有者引用。三个 serializer 对这种属性的处理方式刚好分成两边:
读回来的时候怎么做
遇到只读的集合属性
XmlSerializer
取出既有的实例,把值一项一项填进去
正常还原
System.Text.Json
建一个新集合,指派回去
指派不了,整段跳过
MessagePack
建一个新集合,指派回去
指派不了,整段跳过
两边的差别不在能力,在方向。而在建新集合那一边,「能不能指派」就是「这个成员存不存在」。
四、传输类型一个都不能漏注册
MessagePack 那一侧的规则是另一套。既然它连只读属性都不看,最省事的作法就是让它自己用反射把成员找出来,什么都不必声明。桌面上这样确实跑得动。
问题是这条路靠的是运行时现场产生代码,而这个能力不是每一种运行环境都给得起。给不起的地方,一个没有注册的类型不是变慢,是直接抛异常。所以每一个传输类型都得显式注册一份 formatter,把成员逐一列出来,下面这段出自表单那一族的 WireContracts.Form.cs:
WireContract.For()
.Member(nameof(GetListRequest.SelectFields), static x => x.SelectFields, static (x, v) => x.SelectFields = v)
.Member(nameof(GetListRequest.Filter), static x => x.Filter, static (x, v) => x.Filter = v)
// 其余成员逐一列出
.Build();
nameof 那一格不只是可读性。formatter 写出去的是以属性名为键的 map,读回来不认得的键就跳过,没收到的键让属性留在声明上的默认值。Day 16 那条「一个方法一个参数对象」因此多换到一件事:替 Args 加一个属性,不会让还没升级的调用端打不通。这是现在这个形状给得出的性质,不是一条被守着的承诺,没有任何一个测试在验它。
冗长是必然的:改用一个通用的 formatter 去读属性类型,就又回到现场产生代码那条路。所以这份清单只能手写,也没有生成器可以重跑。
集合在这条路上还有几个各自不同的雷,其中有些在开发机上完全正常,所以「桌面测起来没事」不能当成证据。
这份清单跟类型之间没有编译器绑着,不漂掉靠的是一组测试。它从同一组消息类型出发,把所有到得了的走一遍,两头都比对:走得到的都要有注册,注册了却没有人到得了的也要被指出来。而且这组测试可以在开发机上模拟那种环境跑,不必等到部署出去才发现。
这一整包收在同一处:包的引用、所有 formatter、这份清单,全都在 Bee.Api.Core 底下的一个文件夹里,其余程序集都不必认识 MessagePack。第一节那张表的第三列问的就是这件事。
五、反序列化这一端,类型由谁决定
反序列化是把外面送来的字节变成进程里的对象。而「变成哪一个类型」握在谁手上,决定了这件事有多危险,这里有三个不同的答案。
XML 那一条最封闭。服务端要把一份定义存回去时,类型不是从 XML 内容读出来的,是拿请求上那个 DefineType 去查一张固定的对照表;表上没有的值直接抛异常。
Plain 那一条由方法签名决定,也就是第二节那段 JsonElement:调用端连一个可以填类型的字段都没有。
编码过的那一条是唯一由调用端说了算的,第二节那个 type 字段就是它,走哪一个 serializer 都一样。bytes 不带类型,类型名只能写在 API payload 上跟着送,所以 Type.GetType 之前一定要有一道白名单。它筛的是整串名字,泛型参数与数组元素一个都不放过;解析不了就拒绝,而且整道检查发生在对象被建出来之前,不是建好之后才看。
不挡的话,调用端就等于指定了服务端要建出哪一个类型。危险不在送来的数据,在于有些类型一被建出来就会做事,而反序列化做的正是建对象。
白名单本身分两层:一组固定的基本类型,加上应用启动时声明的命名空间,框架自己那几个是默认值。第二层放得越宽,这道检查挡得越少,那是应用自己的选择。
类型对了,不代表内容不能作怪。XML 这一侧另外禁掉了 DTD:XmlSerializer 直接吃一段字符串时已经挡掉「去外面载一份资源进来」那一种,但文档自己声明的缩写还是会被展开,而那足以让一份几 KB 的文件在展开之后吃光内存。框架让所有 XML 都走同一个收紧过的 reader 进来,于是每个调用端不必各自记得这件事。
回到 Northwind
案例的服务端,跟序列化有关的代码是零行。唯一一处 JsonSerializer 在建表种子那个程序里,读的是自己的种子数据,跟传输无关。
前端也一样。四个前端共用同一个 UI 项目,那个项目里没有一行在处理格式,连定义那条 XML 的还原都是 Connector 做掉的。三种序列化全部关在那一层里,走哪一个、怎么压、怎么加密,上面的代码都不必知道。
零代码不等于零成本。这四个里,除了桌面那一个,其余都在构建文件上留了一笔放行:浏览器那一个跑在 wasm 上,要明确打开反射序列化,否则第一个调用就送不出去,因为框架的消息类型没有走源代码生成,而每一次调用都要经过那层 JSON-RPC payload。挂的不是 value,是外面那一层。应用要付的那一份落在构建设置上,不在源代码里。
小结
持久化那一件从头到尾走 XML:定义本来就要落盘,传出去沿用同一份,零额外成本。
传输那一件分两层。外面那份 JSON-RPC payload 是协议的固定格式,有选择的是里面那一格 value:前后端都是 .NET 走 MessagePack,没有声明时也是它,纯 JavaScript 前端与第三方集成走 JSON。
而 value 上那三个组件全关在两个地方:调用端的 Connector 与服务端的 API 层。日后要换掉其中任何一个,应用代码一行都不必改。
明天接着看 value 上的另一半:序列化之后的压缩与加密,以及那个顺序为什么不能调换。
本文为 2026 iThome 铁人赛参赛文章,原文为繁体中文。
系列完整目录:ERP 架构师笔记:定义驱动的框架设计
"原文地址: https://www.cveoy.top/t/topic/qHYI 著作权归作者所有。请勿转载和采集!