WuKongIM 协议对象拆分重构:从 wkproto 单一包到 wkpacket / codec / jsonrpc 三层协议架构

原创2026-10-14 20:30:481,331 阅读
文章标签:即时通讯后端

WuKongIM 协议对象拆分重构:从 wkproto 单一包到 wkpacket / codec / jsonrpc 三层协议架构

导读

本文围绕 WuKongIM 协议层的一次结构性重构展开:把原本混合在 pkg/wkproto 中的"共享协议对象"与"二进制编解码逻辑"拆分开,抽取为独立的 pkg/wkpacket 共享对象包,使 pkg/wkproto 收敛为纯二进制编解码器、pkg/jsonrpc 收敛为 JSON-RPC 编解码与对象映射层。读完本文你将掌握:协议对象与编解码分离的包边界设计、测试驱动(TDD)的拆包实施步骤、Frame/Framer/Setting/各 Packet 对象的职责划分,以及如何在不改变线上协议语义的前提下完成一次纯结构性的包重构。

一、重构背景:wkproto 的"双重职责"问题

在重构之前,WuKongIM 的协议层由 pkg/wkproto 一个包承担了两种截然不同的职责:

  1. 共享协议对象定义:Frame 接口、Framer 结构、FrameType/ReasonCode/DeviceFlag/DeviceLevel 等枚举、Setting 位标志,以及 ConnectPacket、SendPacket、RecvPacket 等全部报文结构体;
  2. WuKong 二进制协议编解码:固定报头的编解码、剩余长度的变长编码、每个 Packet 的 decodeXxx/encodeXxx/encodeXxxSize 函数。

与此同时,pkg/jsonrpc 为了复用这些协议对象,直接依赖 pkg/wkproto。这就使 pkg/wkproto 变成了一个"偶然的共享模型包":任何协议适配层(无论是 JSON-RPC 还是将来的其他协议)想复用报文类型,都不得不连带依赖整个二进制编解码包。这种耦合让包边界失真,也让无关协议被迫背上二进制 codec 的依赖。

从当前仓库的实际布局可以印证这一点:重构完成后,协议层被组织在 pkg/protocol 下的三个子包中——pkg/protocol/frame(共享对象,即设计中的 wkpacket)、pkg/protocol/codec(二进制编解码,即设计中的 wkproto)、pkg/protocol/jsonrpc(JSON-RPC 编解码与映射)。计划文档与设计文档(设计文档)所描述的正是这一拆分的完整推演过程。

二、目标架构:三个包,一条单向依赖链

重构的核心目标是引入一个零依赖的 pkg/wkpacket 包,让它独占共享的帧接口、枚举、常量与报文结构体;再把 pkg/wkproto 重接为针对 wkpacket 类型做 WuKong 二进制编解码的纯 codec 包,把 pkg/jsonrpc 重接为在 wkpacket 类型与 JSON-RPC 消息之间做映射的包,且不再依赖 pkg/wkproto。

2.1 各包的职责边界

pkg/wkpacket —— 只拥有协议对象定义

允许的行为:

  • 字段定义
  • 枚举/String 辅助函数
  • 轻量对象方法:GetFrameType()、String()、Reset()、UniqueKey()、VerityString()

禁止的行为:

  • 二进制编解码
  • 依赖 codec 侧辅助函数的二进制帧大小计算
  • JSON 编解码
  • 对 pkg/wkproto 或 pkg/jsonrpc 的任何依赖

pkg/wkproto —— 只拥有 WuKong 二进制编解码行为

包含 Protocol 接口、WKProto 实现、DecodeFrame/EncodeFrame/WriteFrame、encoder/decoder 辅助函数,以及每个报文类型的 decodeConnect/encodeConnect/encodeConnectSize 等专用编解码函数。它单向依赖 pkg/wkpacket 获取帧接口、枚举与报文结构体。

pkg/jsonrpc —— 只拥有 JSON-RPC 编解码与对象映射

保留 JSON-RPC 请求/响应/通知结构体、JSON 编解码辅助函数、ToFrame/FromFrame 与 ToProto/FromProto 系列转换。变化点是:所有共享协议对象引用从 pkg/wkproto 切换到 pkg/wkpacket,默认版本常量改用 wkpacket.LatestVersion。

2.2 依赖方向(硬约束)

pkg/wkpacket  -> 无依赖(不依赖 wkproto、jsonrpc)
pkg/wkproto   -> pkg/wkpacket
pkg/jsonrpc   -> pkg/wkpacket

禁止 pkg/wkpacket 反向依赖任何一方。这一单向依赖链是判断重构是否成功的第一条硬性标准。

2.3 一个关键对象:Frame 接口与 Framer

pkg/wkpacket/common.go 是对象包的骨架,其中 Frame 接口定义了所有报文统一暴露的能力,Framer 是嵌入到每个报文结构体中的公共头:

package wkpacket

import "fmt"

const LatestVersion = 5

type Frame interface {
	GetFrameType() FrameType
	GetRemainingLength() uint32
	GetNoPersist() bool
	GetRedDot() bool
	GetsyncOnce() bool
	GetDUP() bool
	GetFrameSize() int64
	GetHasServerVersion() bool
	GetEnd() bool
}

type Framer struct {
	FrameType        FrameType
	RemainingLength  uint32
	NoPersist        bool
	RedDot           bool
	SyncOnce         bool
	DUP              bool
	HasServerVersion bool
	End              bool
	FrameSize        int64
}

func (f Framer) GetFrameType() FrameType        { return f.FrameType }
func (f Framer) GetRemainingLength() uint32     { return f.RemainingLength }
func (f Framer) GetNoPersist() bool             { return f.NoPersist }
func (f Framer) GetRedDot() bool                { return f.RedDot }
func (f Framer) GetsyncOnce() bool              { return f.SyncOnce }
func (f Framer) GetDUP() bool                   { return f.DUP }
func (f Framer) GetFrameSize() int64            { return f.FrameSize }
func (f Framer) GetHasServerVersion() bool      { return f.HasServerVersion }
func (f Framer) GetEnd() bool                   { return f.End }
func (f Framer) String() string                 { return fmt.Sprintf("packetType: %s remainingLength:%d NoPersist:%v redDot:%v syncOnce:%v DUP:%v", f.GetFrameType().String(), f.RemainingLength, f.NoPersist, f.RedDot, f.SyncOnce, f.DUP) }

对照当前仓库落地形态,pkg/protocol/frame/common.go 中的 Framer、Frame 接口与上述结构完全一致,并进一步给出了各字段的中文语义注释:

  • RemainingLength:控制报文总长度等于固定报头长度加上剩余长度;
  • NoPersist:是否不持久化;
  • RedDot:是否显示红点;
  • SyncOnce:此消息只被同步或被消费一次;
  • DUP:是否是重发消息;
  • HasServerVersion:是否有服务端版本(connack 包用到);
  • End:消息块是否是最后一包。

FrameType 枚举(见 pkg/protocol/frame/common.go)覆盖了 WuKong 协议的 12 种报文类型:UNKNOWN(保留位)、CONNECT(客户端请求连接 c2s)、CONNACK(服务端连接确认 s2c)、SEND(发送消息 c2s)、SENDACK(发送确认 s2c)、RECV(收取消息 s2c)、RECVACK(收取确认 c2s)、PING、PONG、DISCONNECT、SUB、SUBACK、EVENT。

2.4 版本常量与 Setting 位标志

版本常量 LatestVersion 随共享对象一起移入 wkpacket。当前仓库中(pkg/protocol/frame/common.go)版本演进为:LegacyMessageSeqVersion = 5、MessageSeqU64Version = 6,LatestVersion = MessageSeqU64Version。计划文档中的示例以 LatestVersion = 5 为占位,实际值以仓库为准,且 pkg/jsonrpc 必须使用 wkpacket.LatestVersion 而非旧的 wkproto.LatestVersion。

Setting 是 8 位位标志(pkg/protocol/frame/setting.go),定义如下:

常量 位值 语义
SettingUnknown 0 无标志
SettingReceiptEnabled 1 << 7 是否开启回执
SettingSignal 1 << 5 是否开启 signal 加密
SettingNoEncrypt 1 << 4 是否不加密
SettingTopic 1 << 3 是否有 topic
SettingStream 1 << 1 是否开启流

配套方法:IsSet(v) 判断标志是否置位、Clear(v) 清除标志、Set(v) 置位并返回新值、Uint8() 转为 uint8。测试 TestSettingFlags 验证了 Set/IsSet/Clear 的完整行为链。

三、文件映射:新增、修改与保留

计划文档给出了逐文件的责任分配表,这是拆包工作量的精确清单。

3.1 新增文件(pkg/wkpacket 与测试)

文件 职责
pkg/wkpacket/common.go Frame、Framer、FrameType、ReasonCode、DeviceFlag、DeviceLevel、Channel、LatestVersion、尺寸/频道常量
pkg/wkpacket/setting.go Setting 位标志
pkg/wkpacket/connect.go ConnectPacket 对象定义
pkg/wkpacket/connack.go ConnackPacket 对象定义
pkg/wkpacket/send.go SendPacket 对象定义与对象辅助方法
pkg/wkpacket/sendack.go SendackPacket 对象定义
pkg/wkpacket/recv.go StreamFlag、RecvPacket、Reset、校验辅助方法
pkg/wkpacket/recvack.go RecvackPacket 对象定义
pkg/wkpacket/disconnect.go DisconnectPacket 对象定义
pkg/wkpacket/sub.go SubPacket 对象定义
pkg/wkpacket/suback.go Action、SubackPacket 对象定义
pkg/wkpacket/event.go EventPacket 对象定义
pkg/wkpacket/ping.go PingPacket 对象定义
pkg/wkpacket/pong.go PongPacket 对象定义
pkg/wkpacket/common_test.go 共享对象冒烟测试:flags、latest version、frame type 辅助函数
pkg/wkpacket/packet_test.go SendPacket.UniqueKey、RecvPacket.Reset、ReasonCode.String 回归检查
pkg/jsonrpc/frame_bridge_test.go JSON-RPC 到 wkpacket 转换测试

3.2 修改文件(pkg/wkproto 侧)

文件 变更内容
pkg/wkproto/common.go 删除共享对象定义,仅保留 ToFixHeaderUint8、FramerFromUint8 等固定报头辅助函数,并改为基于 wkpacket 类型
pkg/wkproto/protocol.go 引入 wkpacket,接口与报文断言切换到 wkpacket.Frame 与 wkpacket.*Packet
pkg/wkproto/connect.go 仅保留 connect 包的二进制编解码函数,改用 wkpacket.ConnectPacket
pkg/wkproto/connack.go 仅保留 connack 包的二进制编解码函数
pkg/wkproto/send.go 仅保留 send 包的二进制编解码函数
pkg/wkproto/sendack.go 仅保留 sendack 包的二进制编解码函数
pkg/wkproto/recv.go 仅保留 recv 包的二进制编解码函数,删除对象侧 Size 方法
pkg/wkproto/recvack.go 仅保留 recvack 包的二进制编解码函数
pkg/wkproto/disconnect.go 仅保留 disconnect 包的二进制编解码函数
pkg/wkproto/sub.go 仅保留 sub 包的二进制编解码函数
pkg/wkproto/suback.go 仅保留 suback 包的二进制编解码函数
pkg/wkproto/event.go 仅保留 event 包的二进制编解码函数,删除对象侧 Size 方法
pkg/wkproto/ping.go / pong.go 删除报文对象定义,仅在仍需要 codec 辅助函数时保留文件
pkg/wkproto/*_test.go 测试改为实例化/导入 wkpacket 报文类型与 wkpacket.LatestVersion

3.3 修改文件(pkg/jsonrpc 侧)

文件 变更内容
pkg/jsonrpc/types.go 将 wkproto 共享类型导入/使用替换为 wkpacket;默认版本切换为 wkpacket.LatestVersion
pkg/jsonrpc/codec.go ToFrame/FromFrame 签名与类型断言从 wkproto 切换到 wkpacket
pkg/jsonrpc/codec_test.go 签名变化后更新导入与断言
pkg/jsonrpc/wukongim_rpc_schema.json 描述文本从 wkproto.ReasonCode 更新为 wkpacket.ReasonCode

3.4 已有脏文件(先检查再编辑)

文件 风险
pkg/jsonrpc/codec.go 工作区中已有本地修改,编辑前需检查当前 diff
pkg/jsonrpc/types.go 工作区中已有本地修改,编辑前需检查当前 diff

四、Task 1:创建 pkg/wkpacket 共享对象包

4.1 第一步:先写失败的冒烟测试

整个重构遵循测试驱动:先写针对 wkpacket 的行为测试,让它在包不存在的状态下失败,再实现代码让测试通过。核心冒烟测试覆盖三块行为:

package wkpacket

import "testing"

func TestLatestVersionAndFrameTypes(t *testing.T) {
	if LatestVersion != 5 {
		t.Fatalf("expected LatestVersion=5, got %d", LatestVersion)
	}
	if (&PingPacket{}).GetFrameType() != PING {
		t.Fatalf("ping frame type mismatch")
	}
	if (&PongPacket{}).GetFrameType() != PONG {
		t.Fatalf("pong frame type mismatch")
	}
}

func TestSettingFlags(t *testing.T) {
	var s Setting
	s.Set(SettingReceiptEnabled)
	s.Set(SettingTopic)
	if !s.IsSet(SettingReceiptEnabled) || !s.IsSet(SettingTopic) {
		t.Fatalf("expected flags to be set")
	}
	s.Clear(SettingTopic)
	if s.IsSet(SettingTopic) {
		t.Fatalf("expected topic flag to be cleared")
	}
}

func TestSendPacketUniqueKeyAndRecvReset(t *testing.T) {
	send := &SendPacket{
		ChannelID:   "ch",
		ChannelType: 2,
		ClientMsgNo: "msg-1",
		ClientSeq:   9,
	}
	if send.UniqueKey() != "ch-2-msg-1-9" {
		t.Fatalf("unexpected unique key: %s", send.UniqueKey())
	}

	recv := &RecvPacket{
		Framer: Framer{RedDot: true, RemainingLength: 10},
		Setting: SettingReceiptEnabled,
		ChannelID: "ch",
		Payload: []byte("body"),
	}
	recv.Reset()
	if recv.ChannelID != "" || recv.Setting != 0 || recv.RemainingLength != 0 || recv.RedDot {
		t.Fatalf("recv reset did not clear fields")
	}
}

运行命令(在仓库根目录执行):

go test ./pkg/wkpacket -run 'Test(LatestVersionAndFrameTypes|SettingFlags|SendPacketUniqueKeyAndRecvReset)' -v

预期结果:FAIL,因为 pkg/wkpacket 尚不存在。

4.2 第二步:实现对象定义

SendPacket 与 RecvPacket 是两个最有代表性的对象。SendPacket 集中了发送消息的全部字段,并携带 UniqueKey() 对象方法:

package wkpacket

import "fmt"

type SendPacket struct {
	Framer
	Setting     Setting
	MsgKey      string
	Expire      uint32
	ClientSeq   uint64
	ClientMsgNo string
	StreamNo    string
	ChannelID   string
	ChannelType uint8
	Topic       string
	Payload     []byte
}

func (s *SendPacket) GetFrameType() FrameType { return SEND }
func (s *SendPacket) UniqueKey() string {
	return fmt.Sprintf("%s-%d-%s-%d", s.ChannelID, s.ChannelType, s.ClientMsgNo, s.ClientSeq)
}

字段语义(与 pkg/protocol/frame/send.go 对照):

  • MsgKey:用于验证此消息是否合法(防中间人篡改);
  • Expire:消息过期时间,0 表示永不过期;
  • ClientSeq:客户端提供的序列号,在客户端内唯一;
  • ClientMsgNo:客户端消息唯一编号,一般是 UUID,用于去重;
  • ChannelID:频道 ID(个人频道时为个人 UID);
  • ChannelType:频道类型(1. 个人 2. 群组);
  • Topic:消息 topic;
  • Payload:消息内容。

UniqueKey() 将 ChannelID-ChannelType-ClientMsgNo-ClientSeq 拼接为唯一键,是服务端消息去重与幂等判定的关键依据;VerityString() 则把 ClientSeq、ClientMsgNo、ChannelID、ChannelType、Payload 拼成校验串。

RecvPacket 是服务端向客户端推送消息的报文,字段更多,并提供 Reset() 方法用于连接对象复用前的字段清空(当前仓库的完整实现见 pkg/protocol/frame/recv.go):

type RecvPacket struct {
	Framer
	Setting     Setting
	MsgKey      string
	Expire      uint32
	MessageID   int64
	MessageSeq  uint32
	ClientMsgNo string
	StreamNo    string
	StreamId    uint64
	StreamFlag  StreamFlag
	Timestamp   int32
	ChannelID   string
	ChannelType uint8
	Topic       string
	FromUID     string
	Payload     []byte
	ClientSeq   uint64
}

func (r *RecvPacket) GetFrameType() FrameType { return RECV }
func (r *RecvPacket) Reset() {
	*r = RecvPacket{}
}

StreamFlag 定义了三态流标志:StreamFlagStart = 0(开始)、StreamFlagIng = 1(进行中)、StreamFlagEnd = 2(结束)。注意当前仓库中 RecvPacket.Reset() 是逐字段清零的完整实现(见 pkg/protocol/frame/packet_test.go 中对应的回归测试),计划的简化版 *r = RecvPacket{} 与之一致。

统一规则:其余所有报文文件(connack、sendack、recvack、disconnect、sub、suback、event、ping、pong)遵循同一原则——只迁移对象结构、枚举定义、String()、GetFrameType() 与对象本地辅助方法;不迁移二进制编解码函数,也不迁移需要 codec 侧尺寸辅助函数的对象方法。

4.3 第三步:验证通过并提交

go test ./pkg/wkpacket -run 'Test(LatestVersionAndFrameTypes|SettingFlags|SendPacketUniqueKeyAndRecvReset)' -v
git add pkg/wkpacket
git commit -m "refactor(wkpacket): extract shared protocol objects"

五、Task 2:重接 pkg/wkproto 为纯编解码器

5.1 协议接口切换到 wkpacket 类型

protocol.go 中的 Protocol 接口全面切换到 wkpacket 类型——解码返回 wkpacket.Frame,编码与写入也以 wkpacket.Frame 为输入:

package wkproto

import "github.com/WuKongIM/WuKongIM/pkg/proto/wkpacket"

type Protocol interface {
	DecodeFrame(data []byte, version uint8) (wkpacket.Frame, int, error)
	EncodeFrame(packet wkpacket.Frame, version uint8) ([]byte, error)
	WriteFrame(w Writer, packet wkpacket.Frame, version uint8) error
}

type PacketDecodeFunc func(frame wkpacket.Frame, remainingBytes []byte, version uint8) (wkpacket.Frame, error)
type PacketEncodeFunc func(frame wkpacket.Frame, version uint8) ([]byte, error)

5.2 固定报头辅助函数留在 codec 侧

ToFixHeaderUint8 与 FramerFromUint8 属于固定报头编解码行为,必须留在 pkg/wkproto,不要移入 pkg/wkpacket。它们把 Framer 的 8 个布尔标志位与帧类型压缩进第一个字节:

func ToFixHeaderUint8(f wkpacket.Frame) uint8 {
	typeAndFlags := encodeBool(f.GetDUP())<<3 |
		encodeBool(f.GetsyncOnce())<<2 |
		encodeBool(f.GetRedDot())<<1 |
		encodeBool(f.GetNoPersist())
	if f.GetFrameType() == wkpacket.CONNACK {
		typeAndFlags = encodeBool(f.GetHasServerVersion())
	}
	return byte(int(f.GetFrameType()<<4) | typeAndFlags)
}

func FramerFromUint8(v uint8) wkpacket.Framer {
	p := wkpacket.Framer{}
	// populate flags exactly as before
	return p
}

当前仓库中这两个函数的完整实现(pkg/protocol/codec/common.go)展示了位布局细节:低 4 位依次承载 NoPersist(bit0)、RedDot(bit1)、SyncOnce(bit2)、DUP(bit3),高 4 位承载 FrameType;当帧类型为 CONNACK 时,bit0 改承载 HasServerVersion。同时 MaxRemaingLength(1024*1024,即最大剩余长度)与 PayloadMaxSize(1<<15 - 1,即最大负载)这两个协议常量也保留在 codec 包中。

5.3 每个报文的 codec 拆分模式

以 connect 为例,对象 ConnectPacket 移入 wkpacket,而 decodeConnect/encodeConnect 留在 wkproto:

func decodeConnect(frame wkpacket.Frame, data []byte, version uint8) (wkpacket.Frame, error) {
	dec := NewDecoder(data)
	packet := &wkpacket.ConnectPacket{}
	packet.Framer = frame.(wkpacket.Framer)
	// decode fields exactly in the old order
	return packet, nil
}

func encodeConnect(packet *wkpacket.ConnectPacket, enc *Encoder, _ uint8) error {
	// write fields exactly in the old order
	return nil
}

关键约束:字段解码/编码顺序必须与重构前完全一致。当前仓库 pkg/protocol/codec/connect.go 展示了真实编码顺序:Version(1 字节)→ DeviceFlag(1 字节)→ DeviceID(变长字符串)→ UID(变长字符串)→ Token(变长字符串)→ ClientTimestamp(8 字节)→ ClientKey(变长字符串)。send 包的编码顺序(见 pkg/protocol/codec/send.go)则更为复杂,带有版本门控逻辑:

  • Setting(1 字节);
  • ClientSeq(4 字节);
  • ClientMsgNo(变长字符串);
  • 版本门控:version < 5 且 version >= 2 且开启 SettingStream 时,写入 StreamNo(5 版本后 send 不再携带 streamNo);
  • ChannelID(变长字符串);
  • ChannelType(1 字节);
  • 版本门控:version >= 3 时写入 Expire(4 字节);
  • MsgKey(变长字符串);
  • 开启 SettingTopic 时写入 Topic(变长字符串);
  • Payload(剩余全部字节)。

对应的 encodeSendSize 按相同字段与版本分支累加字节数,其中 frame.SettingByteSize = 1、frame.ClientSeqByteSize = 4、frame.StringFixLenByteSize = 2、frame.ChannelTypeByteSize = 1、frame.ExpireByteSize = 4 等尺寸常量定义于共享对象包(见 pkg/protocol/frame/common.go),它们随对象一起归 wkpacket 所有。

需要特别处理的方法:RecvPacket.Size()、RecvPacket.SizeWithProtoVersion()、EventPacket.Size() 这三个方法依赖 codec 侧尺寸辅助函数。决策是:从 wkpacket 对象上删除,把二进制尺寸计算保留为 wkproto codec 内部逻辑;如果将来调用方仍需要尺寸计算,应在 wkproto 中提供独立的 codec 面向 API 辅助函数,而不是让 wkpacket 反向依赖 codec。

5.4 编解码流程验证

重构后 WKProto 的完整编解码调度(对照 pkg/protocol/codec/protocol.go)为:

  • DecodeFrame(data, version):先解固定报头(FramerFromUint8)→ 解变长剩余长度(decodeLength)→ 校验 RemainingLength > MaxRemaingLength 时拒绝 → 按 packetDecodeMap[FrameType] 分发到各 decodeXxx;
  • EncodeFrame(f, version):按帧类型分发到各 encodeXxx,并用 encodeXxxSize 预计算剩余长度写入变长头;
  • PING/PONG 是特例:整个报文只有 1 个固定报头字节,无剩余长度与 body。

六、Task 3:重接 pkg/jsonrpc 映射层

6.1 先检查脏文件

pkg/jsonrpc/codec.go 与 pkg/jsonrpc/types.go 在工作区已有本地修改,动手前必须先审查当前 diff,保留与本次重构无关的用户改动:

git diff -- pkg/jsonrpc/codec.go pkg/jsonrpc/types.go

6.2 写失败的桥接测试

新增 frame_bridge_test.go,从 JSON-RPC 请求侧和响应侧同时锁定 wkpacket 行为:

func TestConnectParamsToProtoDefaultsToWKPacketLatestVersion(t *testing.T) {
	pkt := ConnectParams{
		UID: "u1",
		Token: "t1",
	}.ToProto()

	require.Equal(t, wkpacket.LatestVersion, pkt.Version)
}

func TestToFrameReturnsWKPacketFrame(t *testing.T) {
	frame, reqID, err := ToFrame(ConnectRequest{
		BaseRequest: BaseRequest{Method: MethodConnect, ID: "req-1"},
		Params: ConnectParams{UID: "u1", Token: "t1"},
	})
	require.NoError(t, err)
	require.Equal(t, "req-1", reqID)
	require.IsType(t, &wkpacket.ConnectPacket{}, frame)
}

func TestFromFrameAcceptsWKPacketConnack(t *testing.T) {
	msg, err := FromFrame("req-1", &wkpacket.ConnackPacket{
		ReasonCode: wkpacket.ReasonSuccess,
	})
	require.NoError(t, err)
	require.IsType(t, ConnectResponse{}, msg)
}

6.3 更新映射代码

对象映射的核心是 ToProto/FromProto 系列与 ToFrame/FromFrame。Header、SettingFlags、ConnectParams 三者的转换逻辑如下:

func (h Header) toProtoInternal() *wkpacket.Framer {
	return &wkpacket.Framer{
		NoPersist: h.NoPersist,
		RedDot: h.RedDot,
		SyncOnce: h.SyncOnce,
		DUP: h.Dup,
		End: h.End,
	}
}

func (sf SettingFlags) ToProto() wkpacket.Setting {
	var setting wkpacket.Setting
	if sf.Receipt {
		setting |= wkpacket.SettingReceiptEnabled
	}
	if sf.Signal {
		setting |= wkpacket.SettingSignal
	}
	if sf.Stream {
		setting |= wkpacket.SettingStream
	}
	if sf.Topic {
		setting |= wkpacket.SettingTopic
	}
	return setting
}

func (p ConnectParams) ToProto() *wkpacket.ConnectPacket {
	version := uint8(p.Version)
	if p.Version == 0 {
		version = wkpacket.LatestVersion
	}
	return &wkpacket.ConnectPacket{Version: version, UID: p.UID, Token: p.Token}
}

ToFrame 在 wkpacket.Frame 上做类型断言分发:

func ToFrame(packet interface{}) (wkpacket.Frame, string, error) {
	switch p := packet.(type) {
	case ConnectRequest:
		return p.Params.ToProto(), p.ID, nil
	case SendRequest:
		return p.Params.ToProto(), p.ID, nil
	case PingRequest:
		return &wkpacket.PingPacket{}, p.ID, nil
	case DisconnectRequest:
		return p.Params.ToProto(), p.ID, nil
	case RecvAckNotification:
		return p.Params.ToProto(), "", nil
	}
	return nil, "", fmt.Errorf("unknown packet type: %T", packet)
}

当前仓库 pkg/protocol/jsonrpc/codec.go 中的 ToFrame 还额外支持 SubscribeRequest/UnsubscribeRequest 的分发,FromFrame 则按 CONNACK/SENDACK/SUBACK/RECV/EVENT/DISCONNECT/PONG 反向映射为 JSON-RPC 响应或通知,其中非 ReasonSuccess 的结果统一转为带 ErrorObject 的响应。pkg/jsonrpc/types.go(pkg/protocol/jsonrpc/types.go)中的 Header.UnmarshalJSON 兼容 EasySDK 的 snake_case 与 camelCase 双命名约定(Android 用 snake_case、iOS/Flutter/JavaScript 用 camelCase),payload 也支持 JSON 字符串、Base64 与原始 JSON 对象三种形态(decodeEasySDKPayload)——这些 JSON-RPC 线上线形状在重构中必须原样保留。

最后更新 wukongim_rpc_schema.json 的描述文本,将 wkproto.ReasonCode 改为 wkpacket.ReasonCode(当前仓库 schema 中已可见该引用)。

6.4 验证与提交

go test ./pkg/jsonrpc -run 'Test(ConnectParamsToProtoDefaultsToWKPacketLatestVersion|ToFrameReturnsWKPacketFrame|FromFrameAcceptsWKPacketConnack)' -v
git add pkg/jsonrpc
git commit -m "refactor(jsonrpc): map frames through wkpacket"

七、Task 4:清理剩余导入并完成全量验证

7.1 扫描残留引用

用正则全仓扫描仍引用 wkproto 共享对象类型的代码:

rg -n 'wkproto\.(ConnectPacket|ConnackPacket|SendPacket|SendackPacket|RecvPacket|RecvackPacket|DisconnectPacket|SubPacket|SubackPacket|EventPacket|PingPacket|PongPacket|Frame|Framer|ReasonCode|Setting|DeviceFlag|FrameType|LatestVersion)' .

预期结果:只剩有意的 codec 引用,或无匹配。任何残留都应改成最终期望方向——对象类型从 wkpacket 导入,codec 行为从 wkproto 导入:

import (
	"github.com/WuKongIM/WuKongIM/pkg/proto/wkpacket"
	"github.com/WuKongIM/WuKongIM/pkg/proto/wkproto"
)

var frame wkpacket.Frame
codec := wkproto.New()

7.2 兼容性策略:不保留对象别名

设计文档明确:不要在 wkproto 中重新导出 wkpacket 的对象别名。理由很直接——本次重构的目的就是让包边界显式化,重新导出共享对象只会保留现有的语义模糊,全仓导入可以在一次变更中直接更新。若未来确需外部兼容,应作为独立任务并附带显式的兼容性要求来处理。

7.3 格式化与逐级验证

gofmt -w pkg/wkpacket/*.go pkg/wkproto/*.go pkg/jsonrpc/*.go
go test ./pkg/wkpacket ./pkg/wkproto ./pkg/jsonrpc -v   # 定向验证
go test ./...                                           # 全仓验证

若全仓验证出现与本次重构无关的既有失败,需在执行前显式记录。最终提交:

git add pkg/wkpacket pkg/wkproto pkg/jsonrpc
git commit -m "refactor: split protocol objects into wkpacket"

八、不可破坏的约束与实现红线

这是一次纯结构性重构,以下约束构成不可逾越的红线(详见 设计文档):

  1. 协议字段名、字段类型与语义含义不变;
  2. 二进制编码顺序不变(包括各版本门控分支);
  3. 版本门控行为不变(如 version < 5 时 send 的 streamNo 逻辑、version >= 3 时 send 的 expire 逻辑);
  4. JSON-RPC schema 与线形状不变;
  5. pkg/jsonrpc 必须使用 wkpacket.LatestVersion;
  6. 依赖方向严格单向:wkpacket 不依赖任何一方。

九、风险清单与对策

风险 表现 对策
对象/codec 混合文件 多数报文文件同时包含对象定义与编解码逻辑 逐个文件拆分:对象方法迁移到 wkpacket,codec 函数留在 wkproto
隐藏的导入扇出 除 pkg/jsonrpc 外还有其他包直接引用 wkproto 对象类型 用 rg 全仓扫描并一次性更新导入图
脏工作区 pkg/jsonrpc 已有本地修改 编辑前 git diff 审查,保留无关改动

十、成功标准与验证路径

重构完成的判定标准:

  • pkg/wkpacket 包含全部共享协议对象;
  • pkg/wkproto 除 codec-only 辅助函数外不含共享对象定义;
  • pkg/jsonrpc 对共享帧/报文类型的依赖来自 pkg/wkpacket 而非 pkg/wkproto;
  • 现有协议行为不变;
  • 定向测试通过(wkproto 测试、jsonrpc 测试、受导入重写影响的包构建)。

推荐的端到端冒烟路径,也是理解三层架构协作关系的最佳入口:

JSON-RPC 请求
   │  jsonrpc.ToFrame
   ▼
wkpacket.Frame
   │  wkproto.EncodeFrame / DecodeFrame
   ▼
wkpacket.Frame
   │  jsonrpc.FromFrame
   ▼
JSON-RPC 响应/通知

这条链路对应当前仓库中 pkg/protocol/jsonrpc/codec_test.go、pkg/protocol/jsonrpc/frame_bridge_test.go、pkg/protocol/codec/*_test.go 等测试文件覆盖的行为,也是重构后协议层的标准数据流。通过本文的四个任务,一个职责清晰、依赖单向、行为不变的 WuKongIM 协议层即可完整落地。

登录后查看全文
WuKongIM