Endpoints 序列化规格
[EndpointCommand]/[EndpointQuery]契约集与 SSE 流元素的 JSON 序列化面规格—— 编译期自写 converter 发射(EF10 spike §4 立案收口)。主张三律适用:可证伪才写、 有边界才写、一致才写——跨平台一致性由运行时黄金快照(真编译契约 → 产物逐字节)与 真 Kestrel roundtrip 断言背书。
§1 形态:自写 converter + TypeInfoResolver
生成器为每根类型(契约 + SSE 流元素)发射一个 file sealed JsonConverter<T>,闭包内嵌套
DTO 以同类私有静态读写方法并入(规避静态单例相互初始化的循环陷阱);另发射
IJsonTypeInfoResolver(JsonMetadataServices.CreateValueInfo)接入分派表
Options。要点:
- 无 SDK STS 生成器依赖——Roslyn 生成器管线按注册序喂编译状态,SDK 内置 STS 生成器
先于用户生成器运行,
JsonSerializerContext经生成器发射永远看不到后发射的 context; 自写 converter + resolver 不依赖该时序。 - AOT/裁剪安全:反射式序列化不可达——
LoomEndpointSerialization.g.cs零 trim 上报 (CI publish 实证)。分派方法体走GetTypeInfo(Type)+JsonTypeInfo<T?>强转 (net8 无泛型GetTypeInfo<T>()——双腿兼容形态)。 - 发射确定性:一切顺序取自闭包扫描序(禁 Dictionary 枚举序 /
GetHashCode进程随机化) ——golden 逐字稳定。
§2 声明面:契约即序列化计划(零标注)
属性面 = public 可读可写(set/init)实例属性(record 位置属性天然满足);[JsonIgnore]
属性跳过。类型支持集(超集报 KLSG240——宁编译期拒绝不留运行时炸点):
| 形态 | 支持 |
|---|---|
| 基元 | string/bool/int/long/uint/ulong/short/ushort/sbyte/byte/float/double/decimal |
| 知名值类型 | Guid/DateTime/DateTimeOffset/TimeSpan |
| 枚举 | 任意底层整型(数字形态——STS 缺省) |
| 可空 | 值类型 T?、引用 T?(含 oblivious 上下文) |
| 集合 | T[]、List<T>、IReadOnlyList<T>、IList<T>、IEnumerable<T>、IReadOnlyCollection<T>、ICollection<T>(嵌套/锯齿任意组合——变量名带嵌套深度编号) |
| 字典 | Dictionary<string,T>、IReadOnlyDictionary<string,T>、IDictionary<string,T>(键必须 string,读侧 Dictionary 落地;值任意支持集形态递归) |
| 任意值 | object(读侧 JsonElement 往返;写侧 JsonElement/JsonDocument 直写——运行时类型反射序列化与 AOT 不兼容,诚实拒绝) |
| 嵌套 | 其它 record/class/struct DTO(闭包内递归;循环引用合法——运行时自管) |
不支持:多维修数组 T[,](JSON 形态歧义——锯齿数组 T[][] 为替代)、非 string 键字典、
接口集合元素形态等——KLSG240 fail-fast。
§3 语义(对齐 STS 缺省行为)
| 面 | 语义 |
|---|---|
| 属性名 | 写侧原文(PascalCase);读侧 OrdinalIgnoreCase(PropertyNameCaseInsensitive = true 对齐) |
| null | 照写 null、null 还原为 null(DefaultIgnoreCondition = Never 同律,属性与集合元素一致) |
| 缺属性 | 读侧 default(对齐 STS);未知属性 reader.Skip() |
| 枚举 | 数字形态(STS 缺省) |
| 嵌套 DTO | 委托闭包私有方法——端序/转换语义与顶层一致 |
| 非空值类型遇 null token | JsonException(对齐 STS) |
| 容量守卫 | 宿主桥接由生成桩的 400 ProblemDetails 承担(畸形 JSON / 空体) |
§4 分派 API(通道实现方接口,签名稳定)
LoomEndpointSerialization.Options // converter 全量注册 + resolver
await LoomEndpointSerialization.ReadXxxAsync(stream, ct) // JSON 流 → 契约(空体 = null)
string json = LoomEndpointSerialization.WriteXxx(value); // 契约 → JSON 文本
Options同时被生成桩(POST 绑定/SSE 流项序列化)消费——服务侧全部 JSON 面单一来源。- 客户端通道(
LoomHttpOptions.JsonSerializerOptions)保持消费方注入边界——消费方可 注入自建JsonSerializerContext,或直接复用LoomEndpointSerialization.Options(契约集在同一编译单元时即 AOT 安全)。 - SSE 流元素为基元类型时经 resolver 基元兜底(BCL 内建 converter,同样 AOT 安全)。
§5 证明面
| 层 | 手段 |
|---|---|
| 发射文本 | golden 快照(Golden/Endpoints/*/LoomEndpointSerialization.g.cs 逐字) |
| 产物可编译 | GeneratedCompilesClean 真编译绊线(双腿) |
| roundtrip 正确性 | 真 Kestrel HTTP 深度契约往返(嵌套/集合/枚举/可空/Guid/DateTime 族/decimal/大小写不敏感) |
| AOT | CI publish 实证:serializer 文件零 trim 上报;/probe 运行体往返自检 |