WuKongIM 插件钩子迁移微基准线：基准数据、源码级实现细节与回归判定规则

• 即时通讯
• 后端

本文整理 WuKongIM 仓库内部维护的插件（plugin）迁移微基准基线文档 PLUGIN_BENCHMARK_BASELINE.md。读完后你将掌握三件事：如何在改动插件分发、host RPC 映射、PersistAfter/Send/Receive 钩子、NoPersist 实时投递或插件指标之前，用仓库给定的go test -bench命令复现同一套基准；如何在 Apple M4、go1.25.0 环境下记录的一组完整基准数据作为回归参照；以及如何按仓库明确的规则区分“真实的内存/分配退化”与“单次计时噪声”，避免误报性能回归。

一、基线文档的适用范围

基线文档开头明确了它的使用时机：在改动触及以下任何路径之前和之后，都应运行并对照这组基准：

• 插件分发（plugin dispatch）；
• host RPC 映射（插件宿主侧的 RPC 转发）；
• PersistAfter 钩子（消息落库提交后触发）；
• Send 钩子与 Receive 钩子；
• NoPersist 实时投递（不落盘的一次性实时消息）；
• 离线接收者（offline recipient）探测；
• 插件指标（plugin metrics）。

从源码结构看，这七个范围恰好对应仓库中四组独立的基准测试文件，文档把它们统一纳入同一套回归参照体系：

二、基线环境：Commit、机器与 Go 版本

文档记录基准来自以下环境（这是判断数据可比性的前提）：

• 基线 Commit：c6e42412a9ce test: add plugin benchmark baselines
• Receive hook 扩展数据：记录自 2026-06-22 工作区（working tree），时间点位于 Receive hook 提交之前，属于同一天的补充采样；
• 记录日期：2026-06-22；
• 硬件平台：Apple M4，darwin/arm64；
• Go 版本：go1.25.0。

当前仓库 go.mod 声明go 1.25.0（toolchaingo1.25.11），与基线记录一致。需要特别注意：这组 ns/op 数字只在同一台 M4 机器上具有直接可比性。跨机器、跨架构（例如 x86_64 服务器）对比时，只能把基线当作量级参照，回归结论必须在改动前后的同一台机器上重新测量。这一点与文档“Interpreting Regressions”一节的规则互为呼应。

三、基准命令：如何完整复现

文档给出三组命令，覆盖了全部六个基准文件。所有命令都使用-run '^$'（不跑普通测试）、-benchmem（报告分配数据）和-benchtime=3s（每个基准运行 3 秒）以保证统计稳定性。

3.1 插件包主组

go test ./internal/usecase/plugin ./internal/runtime/pluginhook ./internal/contracts/pluginevents ./internal/app -run '^$' -bench 'Benchmark(PersistAfter|Receive|SendMessageFromPluginReq|ChannelMessagesFromPluginReq|ClusterConfigFromSnapshot|ClusterChannelsBelongNode|ConversationChannels|HTTPForward|ListPlugins|SendPluginCandidates|BeforeSend|PluginHook|PluginMetricsObserver)' -benchmem -benchtime=3s

注意-bench参数使用的是交替正则：PersistAfter会同时匹配BenchmarkPersistAfterMessageBatchMapping、BenchmarkPersistAfterCandidates、BenchmarkPersistAfterCommittedClone；Receive会匹配BenchmarkReceiveOffline、BenchmarkReceivePluginCandidates、BenchmarkReceiveOfflineClone、BenchmarkPluginHookReceiveEnqueue等。这正是文档把多个包合并进一条命令执行的原因——插件链路上的每个环节都有对应前缀。

3.2 channelappend 插件相关子集

go test ./internal/runtime/channelappend -run '^$' -bench 'Benchmark(SubmitLocalNoPersistRealtimeScoped|ChannelAppendPostCommitPlugin)$' -benchmem -benchtime=3s

注意这里用了$锚定精确匹配，说明 channelappend 包内其他更大的压测（如多频道并行提交）不属于本基线范围，刻意排除以保持回归信号聚焦。

3.3 大接收者 Online Delivery 规范负载

go test ./internal/runtime/delivery -run '^$' -bench '^BenchmarkRuntimeBounded100KRecipientWorkload$' -benchmem -benchtime=3s

这是文档指定的 canonical（规范）大接收者工作负载。后文会解释为什么大群回归覆盖必须集中在这一个基准上，而不能另起炉灶。

四、基线数据（2026-06-22，Apple M4，darwin/arm64，go1.25.0）

以下数据完整继承自 基线文档，是改动前后对照的参照值。

4.1 规范 Online Delivery 离线分类

这个单次“op”处理 10 万个离线接收者：39 个投递 plan（每 plan 256 人），全部经 presence 解析后被判定为离线并走OfflineRecipientsObserver路径。Extra列的100000 offline_recipients/workload由b.ReportMetric输出，直接验证了离线分类结果的数量正确性（见 runtime_benchmark_test.go#L113-L168）。

4.2 Plugin usecase

几个值得注意的读数规律：

• 映射类基准的分配几乎与 payload 大小无关：PersistAfterMessageBatchMapping在 128 B 到 16 KB 三档 payload 下都是 4 次分配，说明映射路径对 payload 只做切片搬运而不做深拷贝（拷贝成本单独由合同层 Clone 基准度量，见 4.4 节）；
• 候选集基准呈近似线性增长：plugins_1→plugins_1024，ns/op 从约 114 增长到约 135 000，allocs/op 从 4 增长到 1029，约对应每个插件 1 次分配——这是评估“插件注册表/选择逻辑”改动的核心信号；
• HTTP 转发的 local 与 remote 差距：local 路径（经 Invoker 真正走 HTTP 路由）固定约 58 次分配，而 remote 路径（转发到远端节点）恒定 6 次分配，两者成本结构完全不同，回归时要分开看。

4.3 Plugin hook runtime

4.4 Plugin event contracts

4.5 App 插件指标观察者

4.6 Channelappend 插件与 NoPersist 边界

goroutine-delta是b.ReportMetric输出的 goroutine 数量差，3.000 说明该基准路径没有 goroutine 泄漏；disabled与enabled_enqueue的 ns/op 几乎持平（101.6 vs 105.1），说明提交后插件入队的固定开销非常小。

五、源码级解读：这些数字从哪来

5.1 usecase 层：映射、发送与钩子候选集

benchmark_test.go 中的基准通过NewApp(Options{...})注入recordingRuntime、recordingInvoker等 fake 端口，把测量焦点收敛到 usecase 层自身的逻辑。以BenchmarkSendMessageFromPluginReq（第 46-81 行）为例，它构造带NoPersist/SyncOnce/RedDot头的SendReq，每轮调用app.SendMessage并校验返回的MessageId非零——因此测的是“插件发起一条消息”的完整 usecase 路径，而不含真实 RPC 与存储。

BenchmarkBeforeSend定义了no_candidates、one_plugin、chain_4三档钩子链长度，正好覆盖“没有插件参与”“单插件”“四插件链式执行”的相对成本；BenchmarkHTTPForwardFanoutDeferred则专门验证ToNodeId: -1的广播转发被延迟处理并返回ErrHTTPForwardFanoutDeferred且响应为 nil（第 248-271 行），是 fanout 延迟语义的基准化契约。

5.2 合同层：事件 Clone 的深拷贝语义

异步插件 worker 消费的是入队时深拷贝的事件副本，PersistAfterCommitted.Clone()与ReceiveOffline.Clone()的实现（types.go#L34-L38、L69-L73）只复制两个可变部分：

e.Payload = append([]byte(nil), e.Payload...) e.MessageScopedUIDs = append([]string(nil), e.MessageScopedUIDs...)

合同基准用payload大小（128/1024/16384）×MessageScopedUIDs数量（0/10/1000）九宫格展开，正是为了分别暴露“payload 拷贝”和“scoped UID 切片拷贝”两个成本维度：scoped_0时恒定 1 次分配（仅 payload），scoped_10/scoped_1000时恒定 2 次分配。这也解释了为什么 usecase 层映射基准的 allocs/op 与 payload 大小无关——深拷贝被有意推到了入队边界。

5.3 pluginhook 运行时：有界准入、fail-open 与“队列打满”基准

worker.go 实现了有界插件钩子 worker，关键常量（第 14-26 行）：

defaultQueueSize = 1024 defaultWorkers = 1 defaultInvokeTimeout = time.Second enqueueAdmissionTimeout = 2 * time.Millisecond

EnqueuePersistAfter/EnqueueReceive/EnqueueReceiveBatch三个入口在入队前统一调用event.Clone()（第 237-250 行），入队采用两段式：先尝试无锁快路径tryEnqueueFast，队列满时进入带 2ms 超时器的select，超时即记为full并放弃该事件，绝不阻塞或拖垮调用方（第 252-287 行）。这就是 4.3 节两组 QueueFull 基准的由来：benchmark_test.go#L96-L124 用QueueSize: 1, Workers: 1加一个阻塞至 context 结束的 usecase 制造“队列永久打满”场景，ns/op ≈ 2.26ms恰好对应enqueueAdmissionTimeout的 2ms 上限加少量开销。换句话说，这组基线锁定的是一项可用性契约：插件侧再慢，消息提交路径的入队成本也不会超过约 2ms，代价是事件按 fail-open 语义丢弃。任何改动若让 QueueFull 的 ns/op 显著偏离 2ms 量级，或让 Enqueue 的 allocs/op 上升（当前 PersistAfter/Receive 各 5 次），都应按回归处理。

此外，worker 的Observer接口（第 57-63 行）记录每次入队与调用的结果和耗时，其真实实现pluginHookMetricsObserver的成本由 4.5 节三组观察者基准锁定——指标上报路径本身约 120~170ns、恒定 4 次分配，不会反向成为热点。

5.4 delivery 规范负载：10 万离线接收者分类

BenchmarkRuntimeBounded100KRecipientWorkload 构造 39 个 plan（每 plan 256 个接收者，共 100 000 个 UID），presence 解析器统一返回空结果（即全部离线），再由benchmarkOfflineRecipientsObserver累计接收者与回调次数，并在结尾断言b.N * 100000的精确数量。基准还通过b.ReportMetric输出recipients/workload、offline_recipients/workload、recipient_bytes/workload三项自定义指标。文档特别规定：大接收者的 Online Delivery 回归覆盖归属于这一个基准，不要在 channelappend 里另建 recipient-processor 基准——从源码看，channelappend 侧已有BenchmarkVeryLargeGroupRecipientDispatch覆盖“分页→权威分组→投递计划准入”的上游段，两者分段协作而不重叠，各自负责自己边界上的 CPU 与分配成本。

5.5 channelappend：NoPersist 实时投递与提交后插件

BenchmarkSubmitLocalNoPersistRealtimeScoped（benchmark_test.go#L147-L177）构造NoPersist=true、SyncOnce=true且带MessageScopedUIDs: ["u1"]的实时消息，经OnlineDeliveryEnqueuer计数型 fake 完成“提交→实时投递计划入队”的闭环，并在计时结束后校验 goroutine 差。文档明确要求该基准必须保留在 channelappend 子集中，因为命令式 NoPersist 实时投递的职责归属在 channelappend，而不是 plugin usecase。BenchmarkChannelAppendPostCommitPlugin的 disabled/enabled 两档则量化了“提交效果中挂载插件入队端口”的边际成本（约 3.5ns），为“提交路径接入插件钩子”这一迁移决策提供了成本证据。

六、回归判定规则（文档原文的完整继承）

基线文档给出的判定规则是这份数据的“使用说明”，应逐条遵循：

1. 以 B/op 与 allocs/op 的持续增长作为强于单次 ns/op 变慢的信号。计时样本受机器状态影响大，分配模式退化则是结构性的；
2. 宣布计时回归之前，必须在同一台机器上重跑同一条命令，排除偶发干扰；
3. 候选集与列表类基准刻意包含plugins_1024：修改插件注册表或选择逻辑时，不要删除该用例——它是最容易暴露每插件固定开销（分配、字符串拼接）的规模档；
4. Receive 候选基准刻意包含bindings_1024：修改 UID 绑定选择逻辑时保留该用例；
5. 大接收者回归覆盖只归属于BenchmarkRuntimeBounded100KRecipientWorkload，不要在 channelappend 重建 recipient-processor 基准；
6. BenchmarkSubmitLocalNoPersistRealtimeScoped必须留在 channelappend 子集，因为命令式 NoPersist 实时投递由 channelappend 负责；
7. 如果一次有意的迁移导致分配增长，必须在同一提交中更新本文档，并写明实测权衡。

第 7 条意味着这份基线文档是“活”的：任何经评审接受的性能形态变化都要把新数字与理由写回文档，保持“文档数字 = 当前主干实测”的对应关系。

七、实操建议小结

• 改动前：在当前机器上用第三节三条命令各跑一轮，记录完整输出（含-benchmem的 B/op、allocs/op 与 Extra 指标列）作为本地基线；
• 改动后：原样重跑，优先对照 allocs/op 与 B/op，再看 ns/op；
• 对照 基线表格 时：跨机器只做量级比较，同机器才下结论；
• 保留文档标记的用例：plugins_1024、bindings_1024、100K 工作负载、NoPersist scoped 基准都是回归检测的“探针”，删除它们等价于放弃对最坏规模档的监控；
• 有意变更：更新基线文档与改动同提交合入，写明新数字与权衡依据。

这套“命令 + 数据 + 判定规则 + 用例保护条款”的组合，把一个容易流于形式的性能回归流程，固化成了可复制、可审计的工程契约。

• 即时通讯
• 后端