refactor: 重划包边界（对外/内部由编译器强制），拆分两个过大文件

[NeverENG]

结构层面的整理。先用 go list 量了一遍依赖图——无环，方向干净：config 是叶子，client(SDK) 只依赖 proto+predicate，service 作为编排层依赖其余。问题不在依赖方向，在包的划分。

① 对外契约与内部实现混在同一层

pkg/ 下同时放着两类性质相反的包：

• proto、predicate 出现在 SDK 的公开签名里（client.Scan 的参数就是 predicate.Predicate）——是对外契约
• credit、admission、metrics 是纯内部实现

混在一起，「哪些算对外 API」只能靠口头约定。重划后由编译器强制：

pkg/proto     → proto              对外
pkg/predicate → predicate          对外
pkg/credit    → internal/credit    内部
pkg/admission → internal/admission 内部
pkg/metrics   → internal/metrics   内部

移走后 pkg/ 只剩一层无意义包装，一并删除。

已实测两个方向：在模块外建临时 module 导入 internal/metrics → use of internal package not allowed；导入 client/proto/predicate 并实际调用 Scan → 正常编译。

② pkg/utils：23 行、1 个函数、1 个使用方

只剩 ByteBuilder，只有 cmd/ban-bench 用（3 处）。为它维持一个包、一条导入路径和一层公开 API 不划算。下沉到唯一使用它的文件，并改名 concatBytes（原名更像类型而非函数）。

③ 拆分两个过大文件

文件	原	拆分后
storage/sstable.go	910 行、七个关注点	sstable.go 96 / _read.go 355 / _write.go 312 / _meta.go 176
raft/raft.go	845 行、全部子系统	raft.go 213 / _election.go 192 / _replication.go 235 / _snapshot.go 187 / _persist.go 49

纯文件重组，无逻辑改动，并做了完整性核对：sstable 拆分前后均 25 个函数（去空行注释 697→716 行，多出的 19 行是四份文件头）；raft 拆分前后均 30 个函数。

一处我查证后没有动的地方

service/delivery/governance → service/delivery 看着像「子包反向依赖父包」，但 deliverer.go:13 写明这是刻意设计：deliverer 收接口（sender）故不 import governance，由 governance 反向 import delivery，正是为了避免 import 环。设计过的，不动。

一处发现但未修的既有缺陷

全量 go test -race ./... 时 TestShardKV_RealSharding_ForwardedReads 偶发失败（单独跑本分支与 main 各 3/3 通过，故与本 PR 无关）。

根因是断言与被测设计相抵触：它要求每个副本都必须被用到，而 P2C 是延迟感知的——只有 2 个副本时它必然两个都看再选快的那个。整套并行跑造成 CPU 争抢、延迟不对称时，把流量集中到快副本正是 P2C 的设计行为，不是 bug。

修它需要重写断言（改成「制造延迟差、断言流量随之迁移」这类有向验证，而非统计分布），与本次结构重构无关，故未顺手削弱它。

验证

go build ./...（含 -tags pprof）、go vet ./...、gofmt 全绿；go test -race ./... 连跑 2 次通过；scripts/bench.sh 实跑通过。

🤖 Generated with Claude Code

[github-actions]

🐯 BanGD 数据库内核评审

整体风险：🟢 低

变更总结：这是一个纯结构重组 PR，不触碰任何运行逻辑/磁盘格式/数据不变量。它做了三件事：(1) 重划包边界——把 pkg/{credit,admission,metrics} 移入 internal/ 由编译器强制为内部实现，把 pkg/{proto,predicate} 提升为顶层对外包（SDK 公开签名使用了它们），pkg/utils 因仅 1 函数 1 使用方而被就地下沉到 cmd/ban-bench；(2) 把 storage/sstable.go（910 行）按读/写/元信息三个关注点拆为四文件，把 raft/raft.go（845 行）按选举/日志复制/快照/持久化四个子系统拆为五文件；(3) 更新 README 对外契约文档。diff 中大量代码被移动而非重写，作者做了函数计数核对（sstable 前后均 25 函数、raft 前后均 30 函数）以证明是纯移动，并实测了 internal 强制与外部导入。因此本 PR 的核心评审维度是「移动是否真的无逻辑改动、是否引入新的编译/依赖/测试问题」，而非并发与存储正确性。

本评审不阻塞合入；架构级建议以 Issue 形式跟踪，普通问题在下方内联列出。

架构问题（共 2 项）

• [兼容] 拆包后 scan.go 旧包注释与导入受损 proto/scan.go → 🐯 [兼容] 拆包后 scan.go 旧包注释与导入受损 · scan.go #286
• [性能] concatBytes 下沉与 ByteBuilder 行为等价 cmd/ban-bench/runner.go → 🐯 [性能] concatBytes 下沉与 ByteBuilder 行为等价 · runner.go #287

---

_{本次评审消耗 token：共 154734 tokens（输入 143802，输出 2228，缓存命中 8704，缓存写入 0）｜维度 [concurrency, memory, lock, storage, performance]｜对抗式复核 3 票/条，过滤疑似误报 0 条}