os.WriteFile 不适合 KV 持久化，因其无原子写入、无结构布局，导致并发覆盖、崩溃截断、全量读写开销大；应改用追加写+内存索引+固定 record 格式。
为什么 os.WriteFile 不适合做 KV 持久化
直接用 os.WriteFile 覆盖整个文件来存 KV，看似简单，但一写就卡、一并发就丢数据、一重启就丢键值——根本不是“持久化”，只是“碰巧没丢”。
核心问题在于：它没有原子写入保障，也没有结构化布局。每次更新都要读全量、改内存、再全量写回，O(n) 时间 + O(n) 内存 + 零容错。
- 并发写时，两个 goroutine 同时
os.WriteFile，后写入的直接覆盖前一个，键值对静默丢失 - 进程崩溃在写入中途，文件变成截断或乱码，整个 KV 库不可恢复
- 哪怕只改一个
user:123的状态，也要把几万条记录全读进内存再写出去
用 mmap + 固定长度 slot 实现追加写安全
真正的轻量级文件 KV 引擎，得靠“追加写 + 索引映射”：新数据永远 append 到文件末尾，旧数据不动；索引（比如哈希表）只存在内存里，启动时扫描文件重建。
mmap 不是必须，但能避免频繁 read/write 系统调用，尤其适合小 key 小 value 场景（如配置、会话 ID 映射）。关键是要定义好 record 格式：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
type record struct {
hash uint64 // key 的 xxhash
klen uint16 // key 长度
vlen uint16 // value 长度
key [256]byte // 固定长 key 区（实际按 klen 截取）
value [1024]byte // 固定长 value 区
}
- 每个
record总长固定（比如 1300 字节），方便用 offset 快速跳转 - 写入前先
f.Seek(0, io.SeekEnd)定位，再f.Write()一条 record，不覆盖旧数据 - 删除不是真删，而是写一条
vlen == 0的 tombstone record，合并时跳过
sync.Map 和文件持久化的分工边界在哪
sync.Map 是纯内存并发 map，快但掉电即失；文件是磁盘载体，慢但落地即存。两者不该混用，而应分层协作。
典型做法是：启动时从文件加载全部有效 record 到 sync.Map；运行时所有读写走内存；定时或触发条件（如 5 秒无写入）才把增量刷到文件末尾。
- 不要每写一次就
fsync一次——性能暴跌，且多数场景不需要强实时落盘 - 不要在
sync.Map.LoadOrStore里嵌套文件 I/O——阻塞其他 goroutine，违背并发 map 设计初衷 - 注意
sync.Map的迭代非强一致：遍历时可能漏掉刚写入的项，所以 dump 全量必须用Range+ 锁住写入通道
Windows 下 os.O_APPEND 和 mmap 的兼容性坑
Linux/macOS 上 mmap 配合 os.O_APPEND 基本可用，但 Windows 的 CreateFileMapping 对追加写支持极弱：一旦文件增长，原有 mapping 可能失效，读到脏数据或 panic。
跨平台方案不是“统一用 mmap”，而是按系统切换策略：
- Windows 下老实用
os.OpenFile(..., os.O_RDWR|os.O_CREATE)+Seek+Write - Linux/macOS 可选 mmap，但必须配合
syscall.MS_SYNC或定期msync，不能依赖内核自动刷盘 - 所有路径操作必须用
filepath.Join，硬写"./data/kv.bin"在 Windows 会因反斜杠解析失败
最易被忽略的一点：文件权限。Linux 默认创建是 0644，但某些容器环境 umask 为 0022，导致文件不可写；显式传 0600 更稳妥。
