Table of Contents

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 运行体往返自检