WuKongIM 发送微批处理(Send Frame Batching)实现解析:从 Gateway 到 Channel 的整链路批量合并
WuKongIM 发送微批处理(Send Frame Batching)实现解析:从 Gateway 到 Channel 的整链路批量合并
导读
本文基于 WuKongIM 仓库中的发送批处理实现计划文档(docs/superpowers/plans/2026-05-20-send-frame-batching.md),系统拆解其"内部 SEND 微批处理"设计:在不改动线协议(wire protocol)、不破坏既有单条发送行为的前提下,让一次 channel append 能够将多个 SEND 帧以持久化方式一次性提交,同时保持严格的每 channel 顺序与既有客户端协议语义。读完本文你将掌握:Gateway 异步分片如何收集有界微批、Access Gateway 如何将逐帧校验结果对齐为 Sendack、message.App.SendBatch 如何按有序 durable 段分组,以及 pkg/channel 的 AppendBatch 如何把同 channel 段合并为一次 replica.Append(ctx, []Record)——并能对照仓库源码定位每一层的实现与测试证据。
一、目标与架构总览
1.1 一句话目标
在内部增加 SEND 微批处理(micro-batching),使一次 channel append 可以持久化提交多个 SEND 帧,同时保持严格的 per-channel 顺序与既有客户端协议语义。
1.2 四层架构链路
计划文档给出的架构是一条从客户端到存储的完整链路,对应实现同样分四层:
- Gateway 异步 SEND 分片:收集有界微批,调用 SEND 专属的批处理接口(
SendBatchHandler)。 - Access Gateway:把逐帧校验结果映射为对齐的逐项结果,写入按输入顺序对齐的 Sendack。
- message usecase(
internal/usecase/message):Append网关批量接口,SendBatch把持久化命令按有序 channel 段分组。 - pkg/channel:
handler/AppendBatch(实现中位于pkg/channel/reactor/append.go与pkg/channel/service)把同 channel 段合并为一次replica.Append(ctx, []Record)。
客户端 SEND → Gateway 异步分片(微批) → Access Handler.OnSendBatch
→ message.App.SendBatch → 有序 durable 段切分
→ Channel Cluster AppendBatch → 一次 replica.Append(ctx, []Record)
1.3 关键约束(Implementation Notes)
计划文档明确列出以下实现红线,仓库实现全部遵守:
- 每个行为变更采用 TDD(先写失败测试)。
- 不改变线协议。
- 保留全部既有单条发送行为(单帧回退路径)。
- 批量 API 保持内部化,除非既有公开 channel 接口需要扩展。
- per-channel 顺序优先级高于吞吐优化。
- 在 write-fence 检查前先解决存储中的幂等(idempotency)判定,与现有
Append一致。 - 在一个批次内部、记录到达
store.messageTable.append之前,合并重复的幂等键。 - 保留逐项 request context:一个被取消的会话不得取消批次中无关项。
- 原始 gateway 分片只是批处理提示(hint);canonical channel 顺序在消息归一化与 channel append 串行化之后强制执行。
二、Task 1:Gateway 批处理选项与收集器
2.1 配置项与默认值
计划文档要求新增三个 Gateway SEND 批处理开关,仓库在 pkg/gateway/types/options.go 的 SessionOptions 中落地:
| 字段 | 说明 | 默认值 |
|---|---|---|
AsyncSendBatchMaxWait |
SEND 分片等待收集相邻帧的最长时间 | time.Millisecond(计划初稿为 500 * time.Microsecond,最终实现为 1ms) |
AsyncSendBatchMaxRecords |
单个 gateway 微批内的 SEND 帧数上限 | 128 |
AsyncSendBatchMaxBytes |
单个 gateway 微批的 payload 字节上限 | 512 * 1024(512 KB) |
对应常量定义见 pkg/gateway/types/options.go:
defaultAsyncSendBatchMaxWait = time.Millisecond
defaultAsyncSendBatchMaxRecords = 128
defaultAsyncSendBatchMaxBytes = 512 * 1024
2.2 归一化规则
NormalizeSessionOptions(pkg/gateway/types/options.go)的规则与计划文档完全一致:
AsyncSendBatchMaxWait == 0→ 使用默认值;< 0→ 视为无等待(置 0)。AsyncSendBatchMaxRecords <= 0→ 使用默认值。AsyncSendBatchMaxBytes <= 0→ 使用默认值。
计划文档中的两个测试在仓库 pkg/gateway/core/async_dispatch_test.go 中均有对应实现:TestAsyncSendBatchOptionsUseDefaults 验证三个默认值;TestAsyncSendBatchOptionsCanDisableWaitButNotBounds 验证负 wait 可禁用等待、但负 records/bytes 仍回退到默认上界。
func TestAsyncSendBatchOptionsUseDefaults(t *testing.T) {
opt := gatewaytypes.NormalizeSessionOptions(gatewaytypes.SessionOptions{})
require.Equal(t, 500*time.Microsecond, opt.AsyncSendBatchMaxWait)
require.Equal(t, 128, opt.AsyncSendBatchMaxRecords)
require.Equal(t, 512*1024, opt.AsyncSendBatchMaxBytes)
}
注:计划初稿断言
500*time.Microsecond,最终仓库默认值定为time.Millisecond;测试文件同步使用了最终值。配置实际生效值以当前仓库 pkg/gateway/types/options.go 为准。
2.3 收集器实现
计划文档要求一个 collectAsyncSendBatch(first, tasks, limits) 帮助函数,规则包括:始终包含 first;按 send.Payload 长度做字节记账;超出字节上限的任务保留为分片本地 pending 槽,不丢弃、不重复、不重排;MaxWait 之后允许热 channel 的邻近流量聚合。
仓库实际实现走的是 workqueue 的 ShardedMailbox 路径(见 pkg/gateway/core/async_send.go):newSendExecutor 以 BatchMaxItems: limits.maxRecords 和 BatchMaxWait: limits.maxWait 构造 workqueue.ShardedMailbox<a href="https://link.gitcode.com/i/f0b8acfff9447fab4fb0529f44508580" target="_blank">asyncDispatchTask],由 mailbox 内部分片收集微批;随后 dispatchMailboxBatch([pkg/gateway/core/async_send.go)按 maxBytes 与 maxRecords 把 mailbox 吐出的批次进一步切分成安全的小批次:
func (e *sendExecutor) dispatchMailboxBatch(items []asyncDispatchTask) {
limits := gatewaySendBatchLimits(e.server)
...
for i, task := range items {
taskBytes := asyncDispatchTaskByteCount(task)
if i > start && limits.maxBytes > 0 && byteCount+taskBytes > limits.maxBytes {
e.dispatchBatchSafely(items[start:i])
start = i
byteCount = 0
}
byteCount += taskBytes
if i-start+1 >= limits.maxRecords {
e.dispatchBatchSafely(items[start : i+1])
start = i + 1
byteCount = 0
}
}
...
}
分片数量由 asyncSendLogicalShardCount(pkg/gateway/core/async_send.go)基于 worker 数与队列容量推导:asyncSendOrderingShardsPerWorker = 4,即默认每个 worker 对应 4 个逻辑顺序分片,使无关会话不共享 worker 本地队头阻塞,而每个会话仍严格有序。
对应的收集器/切分测试在 pkg/gateway/core/async_dispatch_test.go:TestAsyncSendDispatchMailboxBatchHonorsMaxRecordsAndOrder、TestAsyncSendDispatchMailboxBatchSplitsBeforeMaxBytes 分别验证记录数上限与字节上限切分。
三、Task 2:Gateway 批处理派发接口
3.1 可选批处理接口
计划文档要求一个可选接口,仓库在 pkg/gateway/types/event.go 落地:
// SendBatchItem carries one asynchronous SEND frame through a gateway micro-batch.
type SendBatchItem struct {
Context Context
ReplyToken string
Frame *frame.SendPacket
Index int
EnqueuedAt time.Time
ByteCount int
}
// SendBatchHandler is optionally implemented by handlers that can process SEND frames in batches.
type SendBatchHandler interface {
OnSendBatch(items []SendBatchItem) error
}
同时仓库还提供了更进一步的 DeferredSendBatchHandler(pkg/gateway/types/event.go),用于延迟(deferred)发送路径:按会话顺序跨批次发布结果、保持 terminal seal 权威性,且发布回调不允许递归。
3.2 派发与单帧回退
dispatchBatch(pkg/gateway/core/async_send.go)先调用 s.server.dispatchSendBatch(batch);dispatchSendBatch(pkg/gateway/core/server.go)只有在 dispatcher.canSendBatch() 且构造出的 items 长度与 batch 相等时才走批处理;否则逐帧回退到 dispatchFrame(非 SEND 帧也走该路径):
if s.server.dispatchSendBatch(batch) {
return
}
for _, task := range batch {
...
if err := e.server.dispatchFrame(task.state, task.replyToken, task.frame); err != nil {
e.server.handleHandlerError(task.state, err)
}
}
每项都会调用 recordAsyncDispatchWait 记录排队等待时间;OnSendBatch 返回基础设施错误时,对受影响会话只调用一次 handleHandlerError,而逐项发送失败由 Access Gateway 转换为 Sendack。
sendBatchItems(pkg/gateway/core/server.go)为每个任务构造带 Index、EnqueuedAt、ByteCount 的 SendBatchItem,并保留原始 reply token。相关测试见 pkg/gateway/core/async_dispatch_test.go(观察器统计、批派发、batch item 按值存储 context 等)。
四、Task 3:Access Gateway 的 SEND 批适配器
4.1 消息 usecase 接口
计划文档建议在 internal/access/gateway/handler.go 中保持 MessageUsecase 不变并增加可选批量接口。仓库最终直接把 MessageUsecase 定义为批处理入口(internal/access/gateway/handler.go):
// MessageUsecase is the batch SEND entry used by the gateway adapter.
type MessageUsecase interface {
SendBatchEach([]message.SendBatchItem, func(int, message.SendBatchItemResult) error) error
}
4.2 Handler.OnSendBatch 的对齐写入
OnSendBatch 的完整实现在 internal/access/gateway/batch.go,核心要点:
- 准备阶段:
prepareSendBatch(items)完成逐项解密、命令映射、权限预检(precheck),产出validItems、precheckResults、traceFields等。 - 会话内顺序提交(Sendack 顺序保证):用
gatewayBatchSessionKey{sessionID, isolated}给每项建立会话内链表(heads/tails/nextInSession),只有队头结果 ready 时才允许按序写出 Sendack——保证同一会话的 Sendack 严格按输入顺序。 - 逐项完成回调:对有效项调用
h.messages.SendBatchEach(validItems, ...),每个结果通过complete(index, ...)写入对应 Sendack;回调结果计数不匹配时返回ErrSendBatchResultCountMismatch并记录日志。 - 隔离性与错误映射:每个有效项从原始 request context 派生独立 timeout context;一个项被取消不影响无关项;预检失败项映射为对应 reason 的 Sendack,其余有效项仍进入批次。
计划文档中的对齐测试(两个有效 SendPacket 调用一次 batch、两个 Sendack 按输入顺序写出、保留原始 reply token;无效项被拒绝但不阻塞有效项)在 internal/access/gateway/handler_test.go 中均有覆盖。
五、Task 4/6:Message 层 SendBatch 与 durable 段切分
5.1 从 Send 到 SendBatch 的包装
internal/usecase/message/send.go 中:
Send(ctx, cmd):单条路径,执行权限检查 →beforeSendHook→ person 目录 → 提交给submitter.Send。SendBatch(items):为每个输入返回对齐的SendBatchItemResult数组。SendBatchEach(items, emit):每项结果一旦终态就同步回调 emit,索引可能乱序到达,emit 永不并发调用,且方法返回前会 join 全部内部工作——这正是文档注释强调"对延迟敏感的适配器应使用SendBatchEach,避免已完成的 hot 结果被无关的 cold 准备阻塞"的原因(internal/usecase/message/send.go)。
SendBatchItem / SendBatchItemResult 定义于 command.go(计划文档指定位置):
type SendBatchItem struct {
// Context is the per-send request context for cancellation and timeout.
Context context.Context
// Command is the normalized or raw send command for this item.
Command SendCommand
}
type SendBatchItemResult struct {
Result SendResult
Err error
}
5.2 权限分组与逐项隔离
sendBatchEach(internal/usecase/message/send.go)会把可合并作用域(scope)的项按 sendBatchPermissionGroupKey(scope + context.Done + deadline)分组,批量解析权限;每项仍保留自己的 request context,组内任一 context 取消只影响该组,不波及其他组。计划文档的"一个无效项不阻塞有效项""被取消项不取消无关项"正是由这一层保证。
5.3 durable 段切分
计划文档要求 splitDurableSendSegments(preparedItems) 切分规则:
- 同 channel + 同 append 选项 → 合并。
- 同 channel + 不同 commit mode → 拆分。
- 同 channel 顺序保留。
- 不同 channel 各自成段、段内不乱序。
- person/agent 发送按 canonical 归一化后的 channel 切分,而非原始 packet channel。
实现约束强调"不在同 channel 屏障上做跨段优化":首轮简单按输入顺序迭代,只有 key 匹配才追加进最后一段,既保留顺序又把 gateway 分片来的相邻帧成批。对应测试在 internal/usecase/message/send_test.go(TestSendBatchUsesChannelAppendBatchForSameChannelSegment 等)。
5.4 提交与 dispatcher 语义保持
批量 append 成功后,计划文档要求:
- 每项调用
submitRequestScopedCMDConversationIntent; - 每项调用
dispatcher.SubmitCommitted保持既有行为; - 请求作用域发送若 dispatcher 失败,按单条发送语义失败该项。
对 follower 入口的发送,仓库通过节点 RPC 层把 AppendBatchRequest 转发给 leader;peer/路径不支持 batch 时显式 de-batch 并带 trace/日志可见性,而不是静默丢失批处理证据(见 internal/access/node/channel_append_rpc.go 的 ChannelAppendRPCServiceID 与 ChannelAppend 接口)。
六、Task 5:Channel AppendBatch API 与 Handler
6.1 公开类型
pkg/channel/types.go 定义了完整公开类型:
// AppendBatchRequest appends messages to one channel in request order.
type AppendBatchRequest struct {
ChannelID ChannelID
Messages []Message
PayloadsImmutable bool // 适配器可转移 payload 所有权时置 true,避免克隆
TraceID string
ChannelKey string
Attempt int
CommitMode CommitMode
ExpectedChannelEpoch uint64
ExpectedLeaderEpoch uint64
ExpectedRouteGeneration uint64 // 与 AppendRequest 相同的精确权威契约
OmitResultPayload bool
ServerAllocatedMessageIDs bool // 消息 ID 已由节点级全局唯一分配器产生,存储可跳过查重
}
// AppendBatchResult aligns per-message append results with the request order.
type AppendBatchResult struct {
Items []AppendBatchItemResult
}
// AppendBatchItemResult is one result inside an append batch.
type AppendBatchItemResult struct {
MessageID uint64
MessageSeq uint64
Message Message
Err error
}
Cluster 门面接口(pkg/channel/channel.go)同时暴露 Append 与 AppendBatch。
6.2 Reactor 内实现
在 reactor 实现中,AppendBatchRequest 被封装为 append 事件/队列项(pkg/channel/reactor/append_queue.go、pkg/channel/reactor/event.go),handleAppend(pkg/channel/reactor/append.go)完成:校验 context → validateAppendEvent → 构造 append 请求 → 入队 → 取消 leader 驱逐 → 跟踪时序 → 注册取消 context → 触发 flush。批量 append 与单条 append 共用同一套校验、幂等与写入栅栏逻辑。
6.3 幂等与边界检查(Task 5 步骤 4/6)
计划文档明确要求共享逻辑中:
metaForKey→ epoch 兼容 → 状态检查 → 序列格式检查 → runtime leader 检查 → commit mode context;- 逐项 stored idempotency 查找先于 write fence(与单条
Append一致); - 批内幂等合并:两条同幂等键 + 同 payload 返回首项结果;同键不同 payload 仅后项失败;确保没有重复幂等键到达
store.messageTable.append; - write fence 检查在幂等重复解决之后;
- legacy U32 容量检查:将超过
maxLegacyMessageSeq的尾部项在 durable append 前失败/拆分; - 消息 ID 分配 → 编码全部新消息 →
group.Append(ctx, records)→ 按 base offset 映射新项 → append 后状态复检。
计划文档中的幂等测试矩阵(stored duplicate 返回既有消息并绕过活跃 write fence;批内同键同 payload;批内同键不同 payload 仅失败后者;无重复幂等键到达 store;legacy U32 边界失败尾部项;append 后状态变化保持单条行为)在 pkg/channel 相关测试(pkg/channel/api_test.go 的 nopCluster 实现、pkg/channel/reactor 的 append 系列测试)中均有覆盖。
七、Task 7:应用配置与装配
7.1 环境变量键
计划文档给出三枚配置键,仓库在 internal/config/build.go 以 WK_GATEWAY_DEFAULT_SESSION_ASYNC_SEND_BATCH_* 前缀落地(比计划文档的 WK_GATEWAY_SEND_BATCH_* 更精确地定位到默认会话选项):
| 环境变量 | 类型 | 校验 |
|---|---|---|
WK_GATEWAY_DEFAULT_SESSION_ASYNC_SEND_BATCH_MAX_WAIT |
duration | parseDuration |
WK_GATEWAY_DEFAULT_SESSION_ASYNC_SEND_BATCH_MAX_RECORDS |
int | parseInt,显式负值报错 |
WK_GATEWAY_DEFAULT_SESSION_ASYNC_SEND_BATCH_MAX_BYTES |
int | parseInt,显式负值报错 |
internal/config/effective_values.go(internal/config/effective_values.go)将三者纳入生效配置输出;internal/app/deferred_send.go(internal/app/deferred_send.go)则把 AsyncSendBatchMaxBytes/MaxRecords 直接喂给 channelappend.NewOrderedSubmitter 的 BatchMaxRecords/BatchMaxBytes,使网关批与提交器批共享同一组上界。配置测试(默认值、env 覆盖、显式非法负值、示例配置对齐)在 internal/app/config_test.go 与 internal/config/example_test.go 中体现。
说明:计划文档原定修改
wukongim.conf.example;当前仓库中实际配置入口集中在internal/config/build.go与internal/config/effective_values.go,环境变量名也以仓库实际为准。
八、Task 8:Trace 与压测验证
8.1 Trace 断言
计划文档要求扩展压测 trace 汇总,记录四类批大小:
- gateway batch records
- channel append batch records
- store commit records
- follower apply records
若既有阶段已带 RecordCount 则优先复用。验证目标是:压测中 replica.leader.durable_append_store 与 store.commit.pebble_sync 阶段出现 RecordCount > 1,证明多帧确实在 durable append/store sync 处合并提交。
8.2 压测验收命令
计划文档给出的聚焦单测与集成压测命令:
# 聚焦单元测试
go test ./internal/gateway/core ./internal/access/gateway ./internal/usecase/message ./pkg/channel/handler ./internal/app -run 'Test.*(Batch|Append|SendStress)' -count=1
# 高并发热 channel 三节点压测
WK_SEND_STRESS=1 go test -tags=integration ./internal/app -run '^TestSendStressHighChannelThreeNode$' -count=1 -timeout=300s -v
# 原始三节点对比压测
WK_SEND_STRESS=1 go test -tags=integration ./internal/app -run '^TestSendStressThreeNode$' -count=1 -timeout=300s -v
验收判据:
- success 等于 total,failed 为零,
unique_target_count等于 senders; - trace 中 durable append/store sync 的
RecordCount > 1; - 原始
TestSendStressThreeNode仍通过;启用批配置后 QPS 应有改善,未启用则行为保持兼容。
压测预设调整通过 MaxInflightPerWorker、Senders 与批配置的 env/preset 完成(internal/app/comm_test.go、internal/app/send_stress_integration_test.go)。
8.3 最终验证清单
计划文档的收尾步骤包括:gofmt -w 格式化全部改动文件;跑聚焦单元套件;跑两组三节点压测对比;git diff --check 与 git status --short 检查 diff 卫生。所有 checkpooint 均注明"仅当人类明确要求提交时才提交"。
九、工程要点总结
| 关注点 | 结论 | 源码位置 |
|---|---|---|
| 批处理开关 | 等待 1ms / 128 条 / 512 KB,支持负 wait 禁用等待 | pkg/gateway/types/options.go |
| 网关微批收集 | workqueue ShardedMailbox + 字节/条数二次切分 | pkg/gateway/core/async_send.go |
| 批处理接口 | 可选 SendBatchHandler,未实现则逐帧回退 |
pkg/gateway/types/event.go |
| Sendack 对齐 | 会话内队头就绪才写 Sendack,保持输入顺序 | internal/access/gateway/batch.go |
| 幂等合并 | 先解 stored 幂等、批内合并、后写 fence | pkg/channel/types.go |
| 配置键 | WK_GATEWAY_DEFAULT_SESSION_ASYNC_SEND_BATCH_* |
internal/config/build.go |
本文所依据的实现计划文档位于 docs/superpowers/plans/2026-05-20-send-frame-batching.md;需要了解网关批处理设计脉络可继续阅读 pkg/gateway/FLOW.md,消息发送链路全貌见 internal/usecase/message/FLOW.md。如需在本地复现,可参照 docs/development/PROJECT_KNOWLEDGE.md 中记录的项目知识与本文第八节给出的压测命令执行验证。