Table of Contents

Wire——消息族线编码

KernLab.Loom.Wire:消息族(一个抽象根 + 若干带 tag 的派生类)标注一次,编译期生成整套二进制线编码—— tag 判别、字段序、字节序、编解码全部是生成物,运行期零反射、AOT 就绪。两个生成器:[WireMessage](消息族)+ [WireArray](独立数组)。

可运行 sample:samples/Wire/HelloWorld(基础)、samples/Wire/Evolvable(演进)、samples/Wire/Failures(防御)。

从零跑通

[WireMessage]
public abstract record OrderMsg { public required long Version { get; init; } }   // 根:公共前缀字段

[WireMessageTag(0x01)]
public sealed record OrderPlaced : OrderMsg
{
    [WireField(Id = 1)] public required Guid OrderId { get; init; }               // Guid = 标准值类型(16B)
    [WireField(Id = 2)]
    [WireMember(MaxCount = 64)] public required byte[] Payload { get; init; }     // 变长成员必须 MaxCount
}

// 生成 OrderMsgCodec:
var bytes = OrderMsgCodec.Encode(new OrderPlaced { OrderId = id, Payload = data });
OrderMsgCodec.TryDecode(bytes, out var msg);          // tag 判别还原具体子类
OrderMsgCodec.TryGetFrameLength(bytes, out var len);  // 管道切帧边界

声明即协议——编解码、字段序、字节序全编译期生成,两端(生产者/消费者)用同一份声明。

声明消息族

[WireMessage]                                        // 族根:抽象类/record,公共字段全体子类共享
public abstract partial class FamilyMsg { }

[WireMessageTag(0x01)]                               // 族内唯一(重复 = KLSG050)
public sealed class Full : FamilyMsg
{
    [WireField(Id = 1)] public ulong Seq { get; init; }            // 字段 ID 显式分配(跨版本稳定)
    [WireField(Id = 3)]
    [WireMember(MaxCount = 64)] public byte[] Payload { get; init; } // 变长成员必须 MaxCount(KLSG052)
}

[WireMessageTag(0x02)]
public sealed class Minimal : FamilyMsg
{
    [WireField(Id = 1)] public uint Id { get; init; }
}

规则:

  • [WireMessage] 标在抽象基类(族根);[WireMessageTag(n)] 标在直接派生类(tag = 线首字节,byte)。
  • [WireField(Id = N)] 分配字段 ID(缺省 = 声明序自增,首字段 1);显式 ID 冲突/越界 = KLSG260/261。
  • [WireMember(MaxCount = N)] 是变长防御上限(string 按 UTF8 字节数、集合按元素数、字典按条目数);锯齿还要 InnerMaxCount。缺上限 = KLSG052。
  • 线格式 = [tag 1B][totalLen 4B][字段 tag 流][EOS 0x00]——字段级版本演进;完整字节面契约见线格式规格。

成员类型(每类可跑)

类别 声明 线面
标量 bool/sbyte…long/float/double/同底层 enum 定长,端序跟随族声明
标准值 Guid/DateTime/DateTimeOffset/TimeSpan/decimal 定长 16/8/10/8/13B(#130)
字符串 string [fieldId][len varint][UTF8]
二进制 byte[]/ReadOnlyMemory<byte> [fieldId][len varint][载荷](ROM 成员可零拷贝读)
集合 T[]/List<T>/IReadOnlyList<T>…/ImmutableArray<T> [fieldId][len][count 4B][元素×N]
字典 Dictionary<K,V>/IReadOnlyDictionary<K,V> [fieldId][len][count 4B][逐项 键+值]——键重复解码 Reject(#131)
嵌套结构 标 [BinaryLayout] 的 struct 定长直嵌(大小经其 StructSize)
嵌套消息 [WireMessage] 族根类型 [fieldId][len][内层完整帧],深度上限 8(#132)
消息集合 List<InnerMsg> 等(#188) [fieldId][len][count 4B][逐项内层帧]——多态 tag 还原子类
锯齿 int[][]/List<List<int>>(#133) 外层 count + 每行 [rowLen 4B][行载荷]
可空标量 int?/Guid?/MyEnum?(#133) 有值 = 常规字段;null = 省略该 fieldId
[WireMessage]
public abstract record BatchMsg { public required long Version { get; init; } }

[WireMessageTag(0x21)]
public sealed record Batch : BatchMsg
{
    [WireField(Id = 2)]
    [WireMember(MaxCount = 100)] public required List<int> Ids { get; init; }        // 集合
    [WireField(Id = 3)]
    [WireMember(MaxCount = 50)] public required Dictionary<string, byte[]> Blobs { get; init; }  // 字典
    [WireField(Id = 4)] public required InnerMsg? Inner { get; init; }               // 嵌套消息(可空 = 省略)
    [WireField(Id = 5)]
    [WireMember(MaxCount = 10)] public required IReadOnlyList<InnerMsg>? Party { get; init; }    // 消息集合
    [WireField(Id = 6)] public required int? Retry { get; init; }                    // Nullable 标量
}

生成物(<族名>Codec 静态类)

API 用途 场景
Encode(msg) 新数组 一次性发送
Encode(IBufferWriter<byte>, msg) 零拷贝直写 PipeWriter 汇流
EncodePooled(msg, out rented) ArrayPool 租借(返回写入长度,异常自动归还) 高频热路径
ComputeLength(msg) 精确线长(含 tag/totalLen/EOS) 预算缓冲
EncodeInto(span, msg) 就地编码 复用缓冲
TryGetFrameLength(buf, out len) 分帧探测(5 + totalLen;MaxFrameLength = 64MB 防不可信输入) 管道/PipeReader 切帧
TryDecode(span, out msg) 解码(畸形零异常全 false) 接收端
TryDecodeFromMemory(memory, out msg) ROM 源零拷贝(blob 成员 Slice、嵌套透传) 大 blob 高效读
MaxDepth/MaxFrameLength/Tag<子类> 常量 深度上限 8 / 帧长上限 64MB / 子类 tag 协议常数

接收端典型形态(管道切帧):

if (!MsgCodec.TryGetFrameLength(buffer, out var frame)) break;      // 帧未齐,等更多数据
var msg = MsgCodec.TryDecode(buffer.Slice(0, frame), out var m) ? m : default;
buffer = buffer.Slice(frame);                                       // 切走已消费帧

数组([WireArray])

独立数组 codec——定长前缀字段 + [count 4B][元素×N],元素 = 基元或 [BinaryLayout] struct:

[WireArray(MaxCount = 32)]
public readonly struct IdBatch(uint batch, int[] ids)
{
    public readonly uint Batch = batch;
    public readonly int[] Ids = ids;
}

// 生成 IdBatchCodec:Encode / Encode(Span) / EncodePooled / ComputeLength / TryDecode
var bytes = IdBatchCodec.Encode(new IdBatch(0x0D, [1, 2, 3]));

注意:[WireArray] 定长前缀不承载变长 string/集合(那用 [WireMessage] 字段);嵌套元素须同时引用 Layout 生成器。

端序与跨平台

[WireMessage(Endianness = LayoutEndianness.BigEndian)] 单一声明全族继承(缺省小端)——产物与宿主字节序解耦,三平台 golden 逐字节一致。

版本演进

操作 规则
加字段 新 ID(>当前最大)——旧客户端按 len 跳过、新客户端读旧报文 = 缺省值 ✅
删字段 ID 保留不再发;解码器留忽略槽位 ✅
改字段类型 ❌ 禁止(破坏线格式)——换新 ID 新字段
重排字段 ✅ 线格式不变(前提:显式 [WireField(Id)];声明序自增的 ID 重排即变)

诊断

KLSG045-048([WireArray])+ KLSG050-053(tag 重复/类型不支持/缺 MaxCount/孤立 tag)+ KLSG260-261(字段 ID 冲突/越界)——全默认 Error,随包 AnalyzerReleases 分发。

性能

编码/解码/池化量化基线:Wire 线编码基线。