WuKongIM 发送微批处理(Send Frame Batching)实现解析:从 Gateway 到 Channel 的整链路批量合并

原创2026-10-15 13:35:381,345 阅读
文章标签:即时通讯后端WebSocket微服务高可用前端可观测性

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 四层架构链路

计划文档给出的架构是一条从客户端到存储的完整链路,对应实现同样分四层:

  1. Gateway 异步 SEND 分片:收集有界微批,调用 SEND 专属的批处理接口(SendBatchHandler)。
  2. Access Gateway:把逐帧校验结果映射为对齐的逐项结果,写入按输入顺序对齐的 Sendack。
  3. message usecase(internal/usecase/message):Append 网关批量接口,SendBatch 把持久化命令按有序 channel 段分组。
  4. 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,核心要点:

  1. 准备阶段:prepareSendBatch(items) 完成逐项解密、命令映射、权限预检(precheck),产出 validItems、precheckResults、traceFields 等。
  2. 会话内顺序提交(Sendack 顺序保证):用 gatewayBatchSessionKey{sessionID, isolated} 给每项建立会话内链表(heads/tails/nextInSession),只有队头结果 ready 时才允许按序写出 Sendack——保证同一会话的 Sendack 严格按输入顺序。
  3. 逐项完成回调:对有效项调用 h.messages.SendBatchEach(validItems, ...),每个结果通过 complete(index, ...) 写入对应 Sendack;回调结果计数不匹配时返回 ErrSendBatchResultCountMismatch 并记录日志。
  4. 隔离性与错误映射:每个有效项从原始 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)

计划文档明确要求共享逻辑中:

  1. metaForKey → epoch 兼容 → 状态检查 → 序列格式检查 → runtime leader 检查 → commit mode context;
  2. 逐项 stored idempotency 查找先于 write fence(与单条 Append 一致);
  3. 批内幂等合并:两条同幂等键 + 同 payload 返回首项结果;同键不同 payload 仅后项失败;确保没有重复幂等键到达 store.messageTable.append;
  4. write fence 检查在幂等重复解决之后;
  5. legacy U32 容量检查:将超过 maxLegacyMessageSeq 的尾部项在 durable append 前失败/拆分;
  6. 消息 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 中记录的项目知识与本文第八节给出的压测命令执行验证。

登录后查看全文
WuKongIM