WuKongIM 协议对象拆分设计:将共享报文对象与二进制编解码解耦
WuKongIM 协议对象拆分设计:将共享报文对象与二进制编解码解耦
导读
本文介绍 WuKongIM 中一次关键的协议层重构:将共享协议对象(Frame、Framer、枚举、各 Packet 结构体)从二进制编解码包中拆分出来,形成独立、零依赖的纯对象包。读者将理解原 pkg/wkproto 包"对象 + 编解码"双重职责造成的耦合问题、pkg/wkpacket / pkg/wkproto / pkg/jsonrpc 三个包的目标边界与依赖方向,以及该拆分的文件迁移清单、兼容性策略、风险应对与验证方式。本文以 设计文档 为核心骨架,并结合当前仓库中该设计落地后的源码结构进行印证。
一、背景:pkg/wkproto 的双重职责问题
在设计拆分之前,pkg/wkproto 同时承担了两类完全不同的职责:
- 共享协议对象定义:如
Frame、Framer、枚举(FrameType、ReasonCode、DeviceFlag等)、标志位(Setting、StreamFlag)、Channel以及全部报文结构体(ConnectPacket、SendPacket、RecvPacket等); - WuKong 二进制协议编解码:
DecodeFrame、EncodeFrame、WriteFrame以及各 Packet 专属的encodeXxx/decodeXxx/encodeXxxSize函数。
由于 pkg/jsonrpc 需要直接复用这些共享对象,它被迫依赖 pkg/wkproto。这带来的后果是:
pkg/wkproto从"纯编解码包"变成了"意外共享模型包"(accidental shared model package),包边界具有误导性;- 任何只想复用报文类型的无关协议,都必须连带依赖二进制编解码包;
- 后续新增协议适配器(如 JSON-RPC)时,依赖关系被错误地集中到编解码实现上。
从当前仓库源码可以看到,该问题已通过包拆分解决:共享对象位于 pkg/protocol/frame/,二进制编解码位于 pkg/protocol/codec/,JSON-RPC 位于 pkg/protocol/jsonrpc/(设计文档中的 pkg/wkpacket / pkg/wkproto 在落地时落位于 pkg/protocol/ 下的 frame / codec 子包,职责划分与设计完全一致)。
二、目标包边界:三个包各司其职
设计的核心是把协议层横向切分为三个职责单一、依赖单向的包。
1. pkg/wkpacket(落地为 pkg/protocol/frame):只拥有协议对象定义
该包只允许出现以下内容:
Frame、Framer、FrameType;LatestVersion、ReasonCode、Setting、DeviceFlag、DeviceLevel、Action、StreamFlag、Channel;- 与对象类型一起定义的报文大小/频道相关常量;
- 全部协议报文结构体:
ConnectPacket、ConnackPacket、SendPacket、SendackPacket、RecvPacket、RecvackPacket、DisconnectPacket、SubPacket、SubackPacket、EventPacket、PingPacket、PongPacket。
该包允许的行为仅限:字段定义、枚举/字符串辅助方法(如 String()、Byte()、ToUint8())、轻量对象方法(GetFrameType()、Reset()、UniqueKey()、VerityString() 等)。
严禁出现的行为:二进制编解码、依赖编解码侧辅助函数的二进制报文大小计算、JSON 编解码、对 pkg/wkproto 或 pkg/jsonrpc 的任何依赖。
以落地后的 pkg/protocol/frame/common.go 为例,Framer 是全部报文的公共基座,包含固定报头语义字段:
type Framer struct {
FrameType FrameType
RemainingLength uint32 // 控制报文总长度等于固定报头的长度加上剩余长度
NoPersist bool // 是否不持久化
RedDot bool // 是否显示红点
SyncOnce bool // 此消息只被同步或被消费一次
DUP bool // 是否是重发消息
HasServerVersion bool // 是否有服务端版本 connack包用到
End bool // 消息块:是否是最后一包
FrameSize int64
}
Frame 是全部报文必须实现的接口,仅包含读取性质的轻量方法,不涉及任何字节读写:
type Frame interface {
GetFrameType() FrameType
GetRemainingLength() uint32
GetNoPersist() bool
GetRedDot() bool
GetsyncOnce() bool
GetDUP() bool
GetFrameSize() int64 // 总个frame的大小(不参与编码解码)
GetHasServerVersion() bool // 是否有服务端版本 connack包用到
GetEnd() bool
}
FrameType 枚举完整覆盖协议中的 12 类报文,即 UNKNOWN(保留位)、CONNECT、CONNACK、SEND、SENDACK、RECV、RECVACK、PING、PONG、DISCONNECT、SUB、SUBACK、EVENT。ReasonCode 枚举则承载连接、发送、订阅等场景的语义化原因码(ReasonSuccess、ReasonAuthFail、ReasonSubscriberNotExist、ReasonRateLimit、ReasonSendBan 等)。
对象包同样承载协议常量。设计文档明确"协议相关常量中跨协议适配器共享、但不属于编解码行为的(如 LatestVersion)应移入 pkg/wkpacket"。落地源码中的 常量定义 包括:
- 字段字节宽度常量:
SettingByteSize = 1、StringFixLenByteSize = 2、ClientSeqByteSize = 4、ChannelTypeByteSize = 1、MessageIDByteSize = 8、MessageSeqByteSize = 8等; - 频道类型常量:
ChannelTypePerson = 1、ChannelTypeGroup = 2、ChannelTypeCustomerService = 3、ChannelTypeCommunity = 4、ChannelTypeLive = 9、ChannelTypeVisitors = 10、ChannelTypeAgent = 11、ChannelTypeAgentGroup = 12等; - 协议版本常量:
LegacyMessageSeqVersion = 5、MessageSeqU64Version = 6、LatestVersion = MessageSeqU64Version,明确LatestVersion是当前协议最新版本号。
Setting 同样被建模为纯对象层的位标志,并提供位操作辅助方法(见 pkg/protocol/frame/setting.go):
type Setting uint8
const (
SettingUnknown Setting = 0
SettingReceiptEnabled Setting = 1 << 7 // 是否开启回执
SettingSignal Setting = 1 << 5 // 是否开启signal加密
SettingNoEncrypt Setting = 1 << 4 // 是否不加密
SettingTopic Setting = 1 << 3 // 是否有topic
SettingStream Setting = 1 << 1 // 是否开启流
)
func (s Setting) IsSet(v Setting) bool { return s&v != 0 }
func (s *Setting) Clear(v Setting) { *s &= ^v }
func (s *Setting) Set(v Setting) Setting { *s |= v; return *s }
func (s Setting) Uint8() uint8 { return uint8(s) }
各报文结构体同样保持"纯对象"形态。例如 SendPacket 只包含业务字段与 UniqueKey()、VerityString() 等无副作用方法;RecvPacket 提供 Reset() 用于对象复用池场景下的字段清空,其 VerityString() / VerityBytes() 用于生成防篡改验证串(消息去重与合法性校验使用)。
2. pkg/wkproto(落地为 pkg/protocol/codec):只拥有二进制编解码行为
该包保留的内容为:
Protocol、WKProto;DecodeFrame、EncodeFrame、WriteFrame;- 编解码辅助结构(
Encoder、Decoder、Writer); - 各报文专属二进制编解码函数:
decodeConnect、encodeConnect、encodeConnectSize及全部报文对应的函数。
pkg/wkproto 将依赖 pkg/wkpacket 获取帧接口、枚举与报文结构体。落地后的 pkg/protocol/codec/protocol.go 印证了这一点——它显式 import "github.com/WuKongIM/WuKongIM/pkg/protocol/frame",Protocol 接口的三个方法签名全部围绕 frame.Frame 展开:
type Protocol interface {
DecodeFrame(data []byte, version uint8) (frame.Frame, int, error)
EncodeFrame(packet frame.Frame, version uint8) ([]byte, error)
WriteFrame(w Writer, packet frame.Frame, version uint8) error
}
WKProto 通过 packetDecodeMap(以 frame.FrameType 为键、以解码函数为值)实现"按报文类型路由解码",并在 EncodeFrame / encodeFrameWithWriter 中按 frameType 分发到各 encodeXxx 与 encodeXxxSize 函数。固定报头中的剩余长度采用类 MQTT 的变长编码(每字节 7 位有效位、最高位为延续标志),由 encodeVariable / decodeLength 实现,并设置了 multiplier < 27 的防死循环上限。
3. pkg/jsonrpc:只拥有 JSON-RPC 消息与对象映射
该包内容保持不变,但共享对象引用全部从 pkg/wkproto 切换到 pkg/wkpacket:
- JSON-RPC 请求/响应/通知结构体;
- JSON 编解码辅助函数(
Encode、Decode、determineMessageType等); ToFrame/FromFrame双向桥接;ToProto/FromProto风格的转换辅助函数。
落地后的 pkg/protocol/jsonrpc/codec.go 展示了完整的桥接逻辑:ToFrame(packet interface{}) 将 JSON-RPC 请求/通知(ConnectRequest、SendRequest、SubscribeRequest、RecvAckNotification 等)转换为 frame.Frame;FromFrame(reqId, f) 则把 frame.ConnackPacket、frame.SendackPacket、frame.SubackPacket、frame.RecvPacket、frame.EventPacket、frame.DisconnectPacket、frame.PongPacket 反向映射为 JSON-RPC 响应或通知,非 ReasonSuccess 原因码会转换为 ErrorObject 错误响应。字段级转换(如 FromProtoConnectAck、FromProtoSendAck、FromProtoRecvPacket、fromProtoHeader)位于 types.go。
三、依赖方向:单向依赖是本次重构的灵魂
最终依赖方向必须严格满足:
pkg/wkpacket -> 不依赖 pkg/wkproto 或 pkg/jsonrpc
pkg/wkproto -> pkg/wkpacket
pkg/jsonrpc -> pkg/wkpacket
禁止出现从 pkg/wkpacket 出发的任何反向依赖。这一单向依赖结构保证了:对象层永远不知道编解码的存在,任何新协议适配器(MQTT、JSON-RPC 之外的未来协议)都可以直接复用 wkpacket 的对象类型而不会被迫引入二进制编解码实现。从当前仓库实际 import 关系看,frame 包仅依赖 fmt 与 bytebufferpool 等通用库,没有任何对 codec / jsonrpc 的引用,单向依赖已完整落地。
四、文件级迁移清单
设计文档给出了明确的迁移清单,可直接作为重构的搬运依据:
移入 pkg/wkpacket 的文件(对象定义部分):
| 源文件 | 内容 |
|---|---|
pkg/wkproto/common.go |
对象定义(Framer、枚举、常量、Channel) |
pkg/wkproto/setting.go |
Setting 类型 |
pkg/wkproto/connect.go |
ConnectPacket |
pkg/wkproto/connack.go |
ConnackPacket |
pkg/wkproto/send.go |
SendPacket |
pkg/wkproto/sendack.go |
SendackPacket |
pkg/wkproto/recv.go |
RecvPacket |
pkg/wkproto/recvack.go |
RecvackPacket |
pkg/wkproto/disconnect.go |
DisconnectPacket |
pkg/wkproto/sub.go |
SubPacket |
pkg/wkproto/suback.go |
SubackPacket |
pkg/wkproto/event.go |
EventPacket |
pkg/wkproto/ping.go |
PingPacket |
pkg/wkproto/pong.go |
PongPacket |
保留在 pkg/wkproto 的文件:protocol.go、encoder.go、decoder.go,以及全部 WuKong 二进制协议的 encode/decode/size 函数。
落地后的目录结构与迁移清单一一对应:pkg/protocol/frame/ 下有 common.go、setting.go 及 12 个与报文一一对应的源文件;pkg/protocol/codec/ 下有 protocol.go、encoder.go、decoder.go 与各报文的 codec 源文件(如 connect.go、send.go、recv.go)。
五、迁移期的强制拆分规则:对象与编解码必须分居两包
设计文档强调:迁移不是简单的"整文件搬家"。每个含混对象与编解码逻辑的文件都必须拆成两份:
- 对象定义(结构体 +
GetFrameType()等轻量方法)留在pkg/wkpacket; - 二进制编解码函数(
decodeXxx/encodeXxx/encodeXxxSize)留在pkg/wkproto。
以 ConnectPacket 为例的拆分结果,在当前仓库中可以直接对照验证:
对象侧 pkg/protocol/frame/connect.go:
type ConnectPacket struct {
Framer
Version uint8 // 协议版本
ClientKey string // 客户端公钥
DeviceID string // 设备ID
DeviceFlag DeviceFlag // 设备标示(同标示同账号互踢)
ClientTimestamp int64 // 客户端当前时间戳(13位时间戳,到毫秒)
UID string // 用户ID
Token string // token
}
func (c ConnectPacket) GetFrameType() FrameType {
return CONNECT
}
编解码侧 pkg/protocol/codec/connect.go:
func decodeConnect(f frame.Frame, data []byte, version uint8) (frame.Frame, error) {
dec := NewDecoder(data)
connectPacket := &frame.ConnectPacket{}
connectPacket.Framer = f.(frame.Framer)
// 依次解码 Version、DeviceFlag、DeviceID、UID、Token、ClientTimestamp、ClientKey
// ...
}
func encodeConnect(connectPacket *frame.ConnectPacket, enc *Encoder, _ uint8) error {
enc.WriteUint8(connectPacket.Version)
enc.WriteUint8(connectPacket.DeviceFlag.ToUint8())
enc.WriteString(connectPacket.DeviceID)
enc.WriteString(connectPacket.UID)
enc.WriteString(connectPacket.Token)
enc.WriteInt64(connectPacket.ClientTimestamp)
enc.WriteString(connectPacket.ClientKey)
return nil
}
func encodeConnectSize(connectPacket *frame.ConnectPacket, _ uint8) int {
var size = 0
size += frame.VersionByteSize
size += frame.DeviceFlagByteSize
size += len(connectPacket.DeviceID) + frame.StringFixLenByteSize
size += len(connectPacket.UID) + frame.StringFixLenByteSize
size += len(connectPacket.Token) + frame.StringFixLenByteSize
size += frame.ClientTimestampByteSize
size += len(connectPacket.ClientKey) + frame.StringFixLenByteSize
return size
}
注意 encodeConnectSize 直接引用 frame.VersionByteSize、frame.StringFixLenByteSize 等对象包导出的字节宽度常量,这正是"常量随对象走、计算逻辑留在 codec"这一设计意图的体现——对象包提供事实数据,编解码包提供计算方法。
特殊决策:Size() 方法的去留
迁移前 RecvPacket.Size()、RecvPacket.SizeWithProtoVersion()、EventPacket.Size() 依赖编解码侧的 size 辅助函数。设计文档的决策是:
- 从
pkg/wkpacket中删除这些方法; - 二进制报文大小计算保留为
pkg/wkproto的 codec 内部逻辑(即上文encodeXxxSize这类函数); - 若后续调用方仍需计算大小,在
pkg/wkproto中显式提供 codec 对外辅助函数,绝不为了让对象包调用 size 而制造wkpacket -> wkproto的反向依赖。
从当前 pkg/protocol/frame 的源码看,RecvPacket 与 EventPacket 上已不存在 Size() 类方法,大小计算统一收敛在 pkg/protocol/codec 的 encodedFrameSize / encodeXxxSize 路径中,该决策已落地。
六、兼容性策略与实现约束
不保留别名再导出
设计文档明确:不要在 pkg/wkproto 中保留对象的别名再导出(re-export)。理由是:再导出会让"共享对象来自 wkproto"的旧印象继续存在,包边界的明确性目标就无法达成;仓库范围内的 import 可以在一次变更中直接全部改写。如果未来确有必要的外部兼容,应作为独立任务、携带显式兼容需求单独处理。
纯结构性重构的六条红线
- 协议字段名、字段类型与语义含义不得改变;
- 二进制编码顺序不得改变;
- 版本门控行为(version-gated behavior)不得改变;
- JSON-RPC 的 schema 与 wire 形态不得改变;
pkg/jsonrpc必须改用wkpacket.LatestVersion而非wkproto.LatestVersion;- 本次重构仅是结构性的(structural only),不夹带任何行为变更。
七、风险与应对
设计文档预先识别了三类主要风险:
| 风险 | 说明 | 应对 |
|---|---|---|
| 混合对象/编解码文件 | 多数报文文件同时包含对象定义与编解码逻辑 | 迁移时严格按"对象入 wkpacket、codec 函数留 wkproto"逐文件拆分 |
| 隐藏的 import 扇出 | pkg/jsonrpc 是已知依赖,但可能还有其他包直接 import wkproto 的对象类型 |
仓库 import 图必须一次性地、一致地全部更新 |
| 工作区存在未提交改动 | 重构时 pkg/jsonrpc 等文件可能已包含本地修改 |
编辑前先检查相关文件,保留与本任务无关的改动 |
其中"隐藏 import 扇出"在当前仓库中体现为协议对象被大量业务代码引用——搜索 wkproto 可以在 cmd/、internal/、pkg/、scripts/ 等多处代码与配置中发现引用痕迹,因此 import 改写必须覆盖全仓库并依赖编译与测试来兜底。
八、测试策略:行为不变是完成的唯一标准
设计文档将"行为不变、既有测试全绿"作为重构完成判定,并给出四级验证要求:
pkg/wkproto测试全部通过;pkg/jsonrpc测试全部通过;- 受 import 改写影响的包,仓库整体构建成功;
- 必要时新增/更新聚焦测试,覆盖
jsonrpc.ToFrame/jsonrpc.FromFrame使用wkpacket对象的情况。
推荐的冒烟路径(smoke path)是一条贯穿三个包的最小闭环:
JSON-RPC 请求
-> 转换为 wkpacket.Frame
-> 经 wkproto 编码 / 解码
-> 从 wkpacket.Frame 反向转换回 JSON-RPC 消息
落地仓库中,这条冒烟路径已有对应测试资产:pkg/protocol/jsonrpc/frame_bridge_test.go(frame 桥接契约)、pkg/protocol/jsonrpc/codec_contract_test.go(编解码契约)、pkg/protocol/frame/packet_test.go 与 pkg/protocol/codec/connect_test.go 等逐报文测试,共同构成"对象包 + 编解码包 + 桥接层"三层验证。
九、实施步骤清单
设计文档给出了可直接执行的七步实施顺序:
- 创建
pkg/wkpacket; - 将共享枚举、接口、常量与报文结构体移入
pkg/wkpacket; - 更新
pkg/wkproto,改为 import 并使用pkg/wkpacket; - 将原本与对象定义同文件的报文专属编解码函数迁入
pkg/wkproto源文件; - 更新
pkg/jsonrpc的转换逻辑,改为 importpkg/wkpacket; - 改写仓库中其余对
wkproto共享对象类型的 import; - 执行格式化与定向测试。
十、成功标准
当且仅当以下五条全部满足,重构才算成功:
pkg/wkpacket包含全部共享协议对象;pkg/wkproto除 codec 专属辅助外,不再包含任何共享对象定义;pkg/jsonrpc对共享 frame/packet 类型依赖的是pkg/wkpacket而非pkg/wkproto;- 既有协议行为完全不变;
- 定向测试全部通过。
对照当前仓库:pkg/protocol/frame 汇集全部对象与常量,pkg/protocol/codec 只保留 Protocol、WKProto、Encoder/Decoder 与 encodeXxx/decodeXxx/encodeXxxSize 函数,pkg/protocol/jsonrpc 通过 ToFrame/FromFrame 桥接对象包——三项职责边界与单向依赖均已按设计落地,这为 WuKongIM 后续接入更多协议适配器(包括 pkg/protocol/mqtt、pkg/protocol/wkprotoenc 等)提供了清晰、可复用的对象底座。
延伸阅读
- 设计文档原文:docs/superpowers/specs/2026-03-30-wkpacket-protocol-object-split-design.md
- 对象包核心实现:pkg/protocol/frame/common.go、pkg/protocol/frame/setting.go
- 编解码包核心实现:pkg/protocol/codec/protocol.go、pkg/protocol/codec/encoder.go、pkg/protocol/codec/decoder.go
- JSON-RPC 桥接层:pkg/protocol/jsonrpc/codec.go、pkg/protocol/jsonrpc/types.go、pkg/protocol/jsonrpc/protocol.md
- 相关契约测试:pkg/protocol/jsonrpc/frame_bridge_test.go、pkg/protocol/codec/connect_test.go