• 即时通讯
• 后端

本文以 WuKongIM 仓库内的docs/superpowers/plans/2026-04-10-pkg-restructure-implementation.md实施计划为主体，结合docs/raw/pkg-restructure-proposal.md方案文档与当前仓库pkg/的实际落地状态，完整还原一次大规模 Go 包结构重构的动机、迁移映射、批次执行顺序与 import 改写策略。读者学完后，将掌握"如何把一套隐含三层分布式架构的代码库，重构成目录结构一眼可读的分层布局"，并能在自己的项目中复刻这种"分批可编译、分批可测试"的迁移方法论。

一、重构背景：为什么pkg/需要一次大手术

WuKongIM 是一个自研的分布式即时通讯（IM）系统，其核心运行时天然分为三个逻辑层级：**控制层（Controller）**负责集群状态与槽位调度决策，Group/Slot 层负责按 hash slot 分片的权威元数据复制，Channel 层负责消息日志的共识与存储。重构之前，pkg/目录的物理结构与这套逻辑分层完全脱节，docs/raw/pkg-restructure-proposal.md将其概括为四个核心问题：

此外还有一处命名混淆：cluster/groupcontroller/名字暗示它属于 Group 层，实际上它承载的是 Controller 的控制面决策引擎（Planner + StateMachine），"名字指向错误的分层"比单纯的位置不对更容易误导后来者。

二、目标结构：让目录一眼映射出三层架构

重构方案确立的目标布局，核心思想是让目录树成为架构文档本身：

pkg/ ├── controller/ # ═══ L1 · 控制层 ═══ │ ├── raft/ # Controller Raft 引擎（原 controllerraft/） │ ├── plane/ # 控制面决策：Planner + StateMachine（原 groupcontroller/） │ └── meta/ # 控制面持久化 Pebble 存储（原 storage/controllermeta/） │ ├── group/ # ═══ L2 · 元数据层 ═══ │ ├── multiraft/ # MultiRaft 引擎（原 replication/multiraft/） │ ├── meta/ # 元数据 Pebble 存储（原 storage/metadb/） │ ├── fsm/ # 元数据状态机（原 storage/metafsm/） │ └── proxy/ # 元数据存取代理（原 storage/metastore/） │ ├── channel/ # ═══ L3 · 消息层 ═══ │ ├── isr/ # ISR 共识核心（原 replication/isr/） │ ├── node/ # ISR Node 编排（原 replication/isrnode/） │ ├── transport/ # ISR Node 传输（原 replication/isrnodetransport/） │ └── log/ # 频道日志存储（原 storage/channellog/） │ ├── cluster/ # ═══ 跨层集成（胶水）═══ ├── transport/ # ═══ 横向 · 集群网络 ═══ ├── raftlog/ # ═══ 横向 · Raft 日志存储（Controller + Group 共用）═══ └── protocol/ # ═══ 外部协议 ═══ ├── codec/ # 原 wkcodec/（去 wk 前缀） ├── frame/ # 原 wkframe/ └── jsonrpc/ # 原 wkjsonrpc/

这套结构的价值在于：controller/、group/、channel/三个顶层目录分别对应 L1/L2/L3 三层；cluster/、transport/、raftlog/、protocol/则是跨层或横向的基础设施，不会与任何一层绑定。任何新成员加入代码库时，都能根据"我要实现的是哪一层的能力"直接判断代码归属。

2.1 逐层迁移映射总表

计划将全部迁移动作整理为一张可直接执行的映射表：

L1 · Controller 控制层

L2 · Group 元数据层

L3 · Channel 消息层

横向基础设施

2.2 五个待决策点：动手前的架构辩论

方案文档特别列出了 5 个需要在动手前拍板的设计选择，这体现了重构中"先定命名哲学、再动手搬文件"的原则：

1. multiraft 是否放group/下？推荐 A：group/multiraft/，因为 multiraft 目前仅被 Group 层使用，架构上是 Group 层的"引擎"；备选 B：保持pkg/multiraft/顶层，若未来其他层也可能复用 MultiRaft。
2. controller/plane/vscontroller/planner/？推荐 A：controller/plane/，更短且"控制面（control plane）"是标准术语，能同时覆盖 Planner 与 StateMachine；B 只覆盖了 Planner 没覆盖 StateMachine。
3. channel/transport/命名？推荐 B：channel/transport/，Go 的 import 路径是全限定的，不会与顶层transport/实际冲突，且语义清晰；A 的channel/xport/是为了规避"读起来混淆"的折衷；C 是并入channel/node/。
4. raftlog/放顶层还是storage/下？推荐 A：pkg/raftlog/，因为 Controller Raft 和 Group MultiRaft 都用它，不属于任何一层；B 保留storage/聚合目录。
5. protocol/的 wk 前缀是否安全移除？推荐 A：移除，项目内部无歧义，codec/frame/jsonrpc语义足够清晰；B 保留前缀的前提是存在外部项目依赖wkcodec等包名。

三、变更规模评估与 8 批次执行顺序

重构不是一次性的git mv狂欢，而是被拆成8 个独立可编译、可测试的批次，每个批次都可以单独合入主干：

风险判断的依据很直观：被引用点越少、越"单纯提升"的批次风险越低；而"多包合一 + 包名重命名"的批次（如group/、channel/）风险中等，因为它们既改了目录又改了 package 声明，import 改写面也更大。

3.1 每批次标准流程（可复制的操作模板）

计划为每个批次给出了统一的 8 步流水线，这是全文最具迁移复用价值的部分：

1. git checkout -b refactor/batch-N 2. mkdir -p 新路径 3. git mv 旧路径/* 新路径/ 4. 修改 package 声明 5. sed 全局替换 import 路径 6. go build ./... （确认编译通过） 7. go test ./... （确认测试通过） 8. git commit

关键点在于：git mv保留文件历史、go build ./...是红绿信号（编译不过就是红色，编译通过才允许提交）、包声明重命名与 import 改写分离执行以降低出错面。

3.2 实施计划中的 7 个 Task（落地阶段划分）

实施计划docs/superpowers/plans/2026-04-10-pkg-restructure-implementation.md将 8 个批次进一步组织为 7 个可勾选追踪的任务，每个任务都规定了"先跑测试验证边界、再移动、再回归"的三段式：

• Task 1 — 盘点剩余迁移与 import 影响面：审阅方案文档与pkg/cluster/*、pkg/replication/*、pkg/storage/*、internal/app/*、internal/usecase/*、internal/access/*，确认pkg/transport与pkg/protocol/*已部分迁移应保留，列出 controller/group/channel/cluster/raftlog 剩余的全部 import 改写清单。
• Task 2 — 迁移storage/raftstorage→raftlog：先跑一个聚焦的go test证明新旧路径不匹配（或移动后包边界将被充分触达），再移动文件并保留包名raftstorage，更新 import 到pkg/raftlog，最后重跑聚焦测试。
• Task 3 — Controller 层包迁入pkg/controller：controllerraft→controller/raft、groupcontroller→controller/plane、controllermeta→controller/meta，同步修改pkg/cluster/*、internal/app/*及相关测试的 import 与符号别名。
• Task 4 — Group 层包迁入pkg/group：multiraft、metadb→meta、metafsm→fsm、metastore→proxy，注意包名重命名后可能出现的本地别名冲突。
• Task 5 — Channel 层包迁入pkg/channel：isr、isrnode→node、isrnodetransport→transport、channellog→log，重点处理与 stdliblog、顶层transport的同名包名冲突场景。
• Task 6 — 将pkg/cluster/raftcluster拍平进pkg/cluster：15 个文件提升一层，包声明从raftcluster改为cluster，测试覆盖pkg/cluster、internal/app、internal/access/node。
• Task 7 — 最终验证与文档收尾：跑被移动包的go test，聚焦套件全绿后再跑go test ./...，最后更新仍指向旧路径的文档，对刻意延后的清理项做总结。

值得注意的是计划中反复强调的一个执行原则："使用 package-scopedgo test作为每个移动的红绿信号"——即每个批次都以该包的测试通过为合入门槛，而不是等全部搬完再一次性排错，这大幅降低了 200+ 处 import 改写的风险。

四、重构落地验证：当前仓库的实际结构

实施计划属于"执行中"文档（所有条目均为- [ ]待勾选状态），但通过检查当前仓库pkg/目录可以确认：重构已经在代码层面全部落地，且目标结构与计划存在一处重要演化。

4.1 已落地的分层结构

当前pkg/顶层目录（pkg/）为：backup、bench、channel、client、cluster、controller、dataformat、db、flowdoc、gateway、goroutine、hashslot、metrics、observability、plugin、protocol、quorumlog、raftlog、slot、transport、wklog、workqueue。

计划中的关键目标全部可对号入座：

• pkg/controller/：根包是公开门面（facade），doc.go 声明调用方应依赖根包的 Controller runtime 启动、强类型集群状态快照、状态变更事件、Raft 消息 stepping、提案探测与全文件状态同步契约；内部组件包括raft/（Controller Raft service、WAL、快照、调度 apply）、fsm/（批量 apply 提交命令并保存最终状态）、planner/（纯规划，默认规划器生成初始 slot 分配与任务）、state/（持久化cluster-state.json模型、校验、checksum 与 hash-slot 辅助）、statefile/（原子读写本地状态文件）、command/（带版本的 Controller Raft 命令负载）、sync/（Controller voter 到非控制节点的全文件状态同步）、server/（薄门面）。包间职责边界在 pkg/controller/docs/USAGE.md 中有完整表格说明，且明确约束"本包不得 importpkg/cluster"。
• pkg/channel/：doc.go 描述其为"multiple-reactor channel log runtime"，负责 append 校验、follower apply、ACK、HW 提交、PullHint 唤醒与空闲运行时驱逐；channel/replication/（原 ISR 相关能力的演化，含 leader/follower/learner 与 exchange 传输）、channel/transport/（本地传输）、channel/store/（日志存储适配层）等子包齐全。
• pkg/raftlog/：落地为顶层横向包。scope.go 中的ScopeKind直接印证了"跨层共用"设计意图——ScopeSlot与ScopeController两种作用域共用一个存储引擎；codec.go则展示了其二进制日志格式（manifest/hardstate/appliedIndex/snapshot/entry 等记录类型）。当前包内包含 Pebble 存储、快照管理与内存实现等完整能力（pkg/raftlog/）。
• pkg/transport/：已拍平为顶层包（server.go、client.go、config.go、types.go、errors.go 等直接在 pkg/transport/ 下），不再有nodetransport/中间层。
• pkg/cluster/：已拍平，pkg/cluster/ 顶层直接排列 api.go、node.go、config.go、default_slots.go、node_channel_migration.go 等文件，原raftcluster/子层已消失。
• pkg/protocol/：已去 wk 前缀，codec/、frame/、jsonrpc/三个子包就位（如 pkg/protocol/codec/common.go 的package codec声明）。
• 旧路径已彻底清除：全仓库*.go源码中已检索不到pkg/storage/...、pkg/replication/...、pkg/protocol/wkcodec、pkg/cluster/controllerraft、pkg/cluster/groupcontroller、pkg/transport/nodetransport等旧 import 路径（旧路径引用仅残留在docs/历史计划文档中），说明 200+ 处 import 改写与删除旧目录均已完成。

4.2 重要演化：group/最终统一为slot/

计划方案中的 L2 层目标路径是pkg/group/，但当前仓库不存在pkg/group，取而代之的是pkg/slot/（含fsm/、multiraft/、proxy/三个子包）。这一演化有明确的独立设计文档支撑：docs/superpowers/specs/2026-04-10-slot-naming-unification-design.md（日期恰为重构计划的同一天，状态 Proposed）。

该设计文档的核心主张是：仓库中group与slot长期指代同一个领域概念（按 hash slot 分片的权威复制单元），造成"读代码的人无法判断二者是不同概念还是历史同义词"，因此做了一次有意的、非兼容的硬切重命名——领域概念统一命名为slot，而机制性包名（multiraft、meta、fsm、proxy）保持不变，且不保留任何兼容别名。

这一决策在落地后的 pkg/slot/BOUNDARY.md 中体现得淋漓尽致：pkg/slot被明确定义为"Slot 维度的分布式元数据存储层"，multiraft/管理本节点多个 Slot Raft group 的 open/bootstrap/close/step/propose/config change/leader transfer/compaction 能力，fsm/解码并确定性 apply 元数据命令，proxy/给上层提供按 key 路由到 Slot leader 的分布式元数据 Store facade；同时该文件还以"只做/不做"清单划清了与controller/cluster（调度决策）、channel/message/delivery（消息数据面）、internal/usecase（业务编排）、internal/access（入口适配）的边界。这正是计划中"让目录一眼映射出三层架构"哲学的延续——术语统一让分层更加无歧义。

4.3 落点佐证：从使用方看重构效果

重构是否真正收敛，从"谁在 import 谁"可以验证：

• internal/usecase/management/下多个文件（nodes.go、opsmcp.go、node_lifecycle.go、slot_onboarding.go 等）importWuKongIM/pkg/controller，证明 Controller 引擎已独立为可被业务层复用的组件。
• pkg/cluster/control/（pkg/cluster/control/）承担"把 Controller 引擎适配进生产集群"的职责，包含 controller.go、controller_adapter.go、runtime.go 等，印证了 pkg/controller/FLOW.md 中"生产启动应留在调用方（如pkg/cluster/control）"的边界设计。
• pkg/hashslot/、pkg/cluster/大量文件 importWuKongIM/pkg/slot，internal/infra/migrationv3/、pkg/cluster/node.go、pkg/slot/fsm等 importWuKongIM/pkg/raftlog，说明横向存储包确实被跨层共享。

五、方法论总结：从本次重构提炼的可复用经验

1. 目录结构就是架构文档：当代码库隐含分层模型（如 Controller/Group/Channel）时，物理目录应直接暴露该模型；命名应避免"名字指向错误分层"（如groupcontroller实为 Controller 决策引擎）。
2. 先立方案、列映射表、再动手：pkg-restructure-proposal.md先给出问题清单、目标树、逐层映射表、决策点与规模评估，实施计划再据此拆分任务，两个文档一"设计"一"执行"，职责清晰。
3. 批次切割以"可编译可测试"为准：每个批次独立可编译、独立可测试，用 package-scopedgo test作为红绿信号，避免大规模 import 改写的一次性排错地狱。
4. git mv+ 全局 sed + 构建回归是包重命名的基础三件套；包名与 stdlib（log）、顶层包（transport）冲突时，依赖 Go 的 import 路径全限定特性消除歧义。
5. 术语统一要敢于硬切：group/slot的命名统一以"一个概念只保留一个名字"为原则，明确机制性包名与领域概念名的分工，不保留兼容别名，才能让后续所有 call site 免于记忆翻译层。

六、延伸阅读（仓库内路径）

• 重构实施计划原文：docs/superpowers/plans/2026-04-10-pkg-restructure-implementation.md
• 重构方案（source of truth）：docs/raw/pkg-restructure-proposal.md
• Slot 命名统一设计：docs/superpowers/specs/2026-04-10-slot-naming-unification-design.md
• 落地后的分层目录：pkg/controller/、pkg/slot/、pkg/channel/、pkg/raftlog/、pkg/transport/、pkg/cluster/
• 边界与用法文档：pkg/slot/BOUNDARY.md、pkg/controller/docs/USAGE.md、pkg/controller/FLOW.md

说明：本文中的迁移映射、批次划分、决策点与规模数字均直接取自上述两份文档；落地状态描述基于当前仓库目录与源码检索结果。若你正在阅读本仓库的其他计划文档，请注意其中旧路径（如pkg/replication/、pkg/storage/）均指重构前的历史位置，应以当前pkg/实际结构为准。

• 即时通讯
• 后端