Day 22:XML、JSON 与 MessagePack 的分工

昨天结尾说换一个层面。从这里开始,题目不再是定义里声明了什么,而是这些定义与数据离开内存之后怎么走。

序列化是两件事。一件是持久化:对象要存下来,下次还得原样读得回来,定义是这样存的,SessionUser 这类系统数据也是。另一件是传输:对象要送到另一端,而那一端不只一种:桌面、浏览器、iOS、Android,运行环境各不相同。

本篇说明:

  1. 持久化走哪一条、传输为什么分两条,分界线照什么判准画
  2. PayloadFormat 怎么决定一次调用的 value 送出去长什么样
  3. 定义类的东西为什么传出去是一段 XML 字符串,不是一棵 JSON 树
  4. 传输类型为什么一个都不能漏注册
  5. 反序列化那一端,类型由谁决定,以及为什么只有一条路需要白名单

一、持久化一条路,传输两条

持久化要的是人看得懂、能进版本控制、能手动改,这一件从头到尾走 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:

json 复制代码
{"jsonrpc":"2.0","method":"System.Login",
 "params":{"format":0,"value":{"userId":"demo","password":"demo"},"type":""},"id":"1"}

回来的也是可读的:

json 复制代码
{"jsonrpc":"2.0","method":"System.Login",
 "result":{"format":0,"value":{"accessToken":"033bedcf-...","userName":"Demo User",
 "timeZone":"Asia/Taipei"},"type":""},"id":"1"}

同一个方法把 format 改成 1,其余一字不动,换来的是一则错误:

json 复制代码
{"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 里只有一个字段:

json 复制代码
{"result":{"format":0,"value":{"xml":"<?xml version=\"1.0\" encoding=\"utf-8\"?>
<FormSchema ProgId=\"Order\" CategoryId=\"company\" ...>
  <Tables><FormTable TableName=\"Order\" DbTableName=\"ft_order\" ..."},"type":""}}

一段 XML 字符串,装在 API payload 那棵 JSON 树里。定义类的东西全部走这条路。API 层只负责把字符串送到,还原成对象是调用端的 Connector 在做,所以 XmlSerializer 在每一个前端上也要跑一次。

理由是持久化那一份现成可用:定义本来就以 XML 落盘,传出去沿用同一套序列化,零额外成本。

要让定义类型也走 JSON 或 MessagePack,代价是持续的。每多一种序列化就多一组要顾的事:来回一趟数据会不会丢、反序列化时挡不挡得住不该被建出来的类型。而定义是嵌套结构、又会随版本演进,每加一个属性都要在每一种格式上再确认一次;日后换一个更适合的传输格式,整组定义类型还要再验一轮。

而它们现在的形状也确实不适合:集合属性是只读的,各自握着自己的所有者引用。三个 serializer 对这种属性的处理方式刚好分成两边:

读回来的时候怎么做 遇到只读的集合属性
XmlSerializer 取出既有的实例,把值一项一项填进去 正常还原
System.Text.Json 建一个新集合,指派回去 指派不了,整段跳过
MessagePack 建一个新集合,指派回去 指派不了,整段跳过

两边的差别不在能力,在方向。而在建新集合那一边,「能不能指派」就是「这个成员存不存在」。


四、传输类型一个都不能漏注册

MessagePack 那一侧的规则是另一套。既然它连只读属性都不看,最省事的作法就是让它自己用反射把成员找出来,什么都不必声明。桌面上这样确实跑得动。

问题是这条路靠的是运行时现场产生代码,而这个能力不是每一种运行环境都给得起。给不起的地方,一个没有注册的类型不是变慢,是直接抛异常。所以每一个传输类型都得显式注册一份 formatter,把成员逐一列出来,下面这段出自表单那一族的 WireContracts.Form.cs:

csharp 复制代码
WireContract.For<GetListRequest>()
    .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 铁人赛参赛文章,原文为繁体中文。

iThome 原文 | HackMD 版

系列完整目录:ERP 架构师笔记:定义驱动的框架设计

相关推荐
风云17 小时前
从 NLite 到 Vane.Container 1.0:压箱十六年的自研 DI 容器开源
.net·di·mini 容器·nlite
Jeff-Tsai1 天前
Day 21:业务逻辑定制与 Plugin 的四个时点
.net·架构设计·erp·definition-driven
IT规划师1 天前
Redis 核心机制 | 键生命周期与 TTL 管理
redis·.net
Jeff-Tsai2 天前
Day 20:多语言定制与资源结构
.net·架构设计·erp·definition-driven
泓度科技2 天前
多租户数据隔离怎么做 单库单表架构方案
架构设计·多租户·缓存策略·数据隔离·权限管控
Jeff-Tsai3 天前
Day 19:定制层的范围与叠加粒度
.net·架构设计·erp·definition-driven
known4 天前
你的账,是补出来的还是做出来的
blazor·erp·known
Jeff-Tsai4 天前
Day 18:错误契约与用户可见消息
.net·架构设计·erp·definition-driven