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 线编码基线。