WuKongIM 协议对象拆分设计:将共享报文对象与二进制编解码解耦

原创2026-10-16 17:39:511,860 阅读
文章标签:即时通讯后端

WuKongIM 协议对象拆分设计:将共享报文对象与二进制编解码解耦

导读

本文介绍 WuKongIM 中一次关键的协议层重构:将共享协议对象(Frame、Framer、枚举、各 Packet 结构体)从二进制编解码包中拆分出来,形成独立、零依赖的纯对象包。读者将理解原 pkg/wkproto 包"对象 + 编解码"双重职责造成的耦合问题、pkg/wkpacket / pkg/wkproto / pkg/jsonrpc 三个包的目标边界与依赖方向,以及该拆分的文件迁移清单、兼容性策略、风险应对与验证方式。本文以 设计文档 为核心骨架,并结合当前仓库中该设计落地后的源码结构进行印证。

一、背景:pkg/wkproto 的双重职责问题

在设计拆分之前,pkg/wkproto 同时承担了两类完全不同的职责:

  1. 共享协议对象定义:如 Frame、Framer、枚举(FrameType、ReasonCode、DeviceFlag 等)、标志位(Setting、StreamFlag)、Channel 以及全部报文结构体(ConnectPacket、SendPacket、RecvPacket 等);
  2. 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)。

五、迁移期的强制拆分规则:对象与编解码必须分居两包

设计文档强调:迁移不是简单的"整文件搬家"。每个含混对象与编解码逻辑的文件都必须拆成两份:

  1. 对象定义(结构体 + GetFrameType() 等轻量方法)留在 pkg/wkpacket;
  2. 二进制编解码函数(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 可以在一次变更中直接全部改写。如果未来确有必要的外部兼容,应作为独立任务、携带显式兼容需求单独处理。

纯结构性重构的六条红线

  1. 协议字段名、字段类型与语义含义不得改变;
  2. 二进制编码顺序不得改变;
  3. 版本门控行为(version-gated behavior)不得改变;
  4. JSON-RPC 的 schema 与 wire 形态不得改变;
  5. pkg/jsonrpc 必须改用 wkpacket.LatestVersion 而非 wkproto.LatestVersion;
  6. 本次重构仅是结构性的(structural only),不夹带任何行为变更。

七、风险与应对

设计文档预先识别了三类主要风险:

风险 说明 应对
混合对象/编解码文件 多数报文文件同时包含对象定义与编解码逻辑 迁移时严格按"对象入 wkpacket、codec 函数留 wkproto"逐文件拆分
隐藏的 import 扇出 pkg/jsonrpc 是已知依赖,但可能还有其他包直接 import wkproto 的对象类型 仓库 import 图必须一次性地、一致地全部更新
工作区存在未提交改动 重构时 pkg/jsonrpc 等文件可能已包含本地修改 编辑前先检查相关文件,保留与本任务无关的改动

其中"隐藏 import 扇出"在当前仓库中体现为协议对象被大量业务代码引用——搜索 wkproto 可以在 cmd/、internal/、pkg/、scripts/ 等多处代码与配置中发现引用痕迹,因此 import 改写必须覆盖全仓库并依赖编译与测试来兜底。

八、测试策略:行为不变是完成的唯一标准

设计文档将"行为不变、既有测试全绿"作为重构完成判定,并给出四级验证要求:

  1. pkg/wkproto 测试全部通过;
  2. pkg/jsonrpc 测试全部通过;
  3. 受 import 改写影响的包,仓库整体构建成功;
  4. 必要时新增/更新聚焦测试,覆盖 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 等逐报文测试,共同构成"对象包 + 编解码包 + 桥接层"三层验证。

九、实施步骤清单

设计文档给出了可直接执行的七步实施顺序:

  1. 创建 pkg/wkpacket;
  2. 将共享枚举、接口、常量与报文结构体移入 pkg/wkpacket;
  3. 更新 pkg/wkproto,改为 import 并使用 pkg/wkpacket;
  4. 将原本与对象定义同文件的报文专属编解码函数迁入 pkg/wkproto 源文件;
  5. 更新 pkg/jsonrpc 的转换逻辑,改为 import pkg/wkpacket;
  6. 改写仓库中其余对 wkproto 共享对象类型的 import;
  7. 执行格式化与定向测试。

十、成功标准

当且仅当以下五条全部满足,重构才算成功:

  • 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 等)提供了清晰、可复用的对象底座。

延伸阅读

登录后查看全文
WuKongIM