如何在 Go 中实现一个高效的本地文件缓存

很多同学会想当然地用 os.Stat 看一眼修改时间，再决定要不要读文件。这招看着简单，但藏着三个坑：ModTime() 精度可能只有秒级（比如 NFS 或容器挂载场景），1 秒内多次更新直接忽略；硬链接和符号链接会让 os.Stat 跟 os.Lstat 行为不一致，缓存判断出错；更关键的是，检查和读取之间没有原子性——刚检查完文件还在，下一秒就被删了，跑出 no such file 错误。所以，关键是把检查和读取合并成一次原子操作，或者换一个更稳定的标识来代替时间戳。

为什么 os.Stat 和文件读取不能直接拼凑出可靠缓存

先说结论：直接用 os.Stat 检查修改时间再决定是否读文件，这个思路听着简单，但实际跑起来会踩三个坑。第一个坑，ModTime() 精度不够——在 NFS 或某些容器挂载场景下，返回的时间戳可能只有秒级，如果 1 秒内文件被多次更新，缓存根本察觉不到。第二个坑，硬链接和符号链接会让 os.Stat 和 os.Lstat 的行为不一致，缓存可能误判源文件有无变化。第三个坑最致命：检查完文件状态、准备读取的间隙，文件可能已被删除或重命名，直接抛 no such file 错误。所以，必须把“检查 + 读取”合并成一次系统调用级别的原子操作，或者用更可靠的东西代替时间戳。

• 优先用文件的 inode + dev 组合（Linux/macOS）或 FileID（Windows）做唯一标识，比 ModTime() 靠谱得多
• 如果不想碰 syscall、要跨平台，退而求其次：对文件内容算个轻量哈希（比如 xxhash.Sum64），只在首次读或缓存失效时算一次
• 别每次 Get 都调 os.Stat —— 把元数据也缓存起来，和内容放一起，读缓存时直接比对就完事

用 sync.Map 还是带驱逐策略的结构体

sync.Map 适合高并发读、低频写的场景，但本地文件缓存往往需要控制总大小或按 LRU 踢掉旧项。硬塞 sync.Map 的结果就是缓存无限增长，最后吃光内存。更务实的做法：自己封装一个结构体，内部用 map[string]*cacheEntry + sync.RWMutex，再加一个简单的 LRU 链表（用 list.List）管理访问顺序。不需要引入完整 Go cache 库（比如 gocache），因为文件缓存的 key 是路径字符串，value 是字节切片或结构体，没必要泛型化。

• key 用绝对路径（filepath.Abs 处理一次，避免软链造成重复缓存）
• value 里至少包含：data []byte、inode uint64（Linux/macOS）、size int64、accessedAt time.Time
• 每次 Get 时更新 accessedAt 并移到 LRU 表头；Set 时检查总 size，超限就从尾部逐个删除

如何安全地检测文件是否变更

最稳妥的做法不是监听，而是每次读缓存前做一次“轻量验证”：打开文件（os.OpenFile(path, os.O_RDONLY, 0)），然后 f.Stat()，再对比 inode/dev 和之前缓存的值。这个过程比读全部内容快得多，而且能规避权限变化、删除后重建等边界情况。注意，别拿了 f 就忘了 Close，Linux 上文件描述符消耗很快。建议用 defer f.Close() 包裹验证逻辑，或者直接用 os.Stat（但它不打开文件，拿不到 inode——所以还得走 Open + Stat 组合）。

• Windows 下用 syscall.GetFileInformationByHandle 取 FileIndexLow/High 替代 inode
• 如果业务允许“最多 N 秒延迟感知变更”，可以加一个 staleDuration time.Duration 字段，在 Get 时跳过验证（省一次 syscall 开销）
• 永远别信 os.SameFile 的结果来判断缓存有效性——它只比 path，不比实际内容或 inode

要不要支持内存映射（mmap）读大文件

超过 10MB 的文件，用 os.ReadFile 会一次性分配等长内存，GC 压力不小。而 mmap（Go 里通过 golang.org/x/sys/unix.Mmap 调用）能按需页加载，降低峰值内存。但代价也很明显：Windows 支持弱（syscall.CreateFileMapping 封装复杂）、无法跨平台统一 API、而且 mmap 区域 GC 不感知，容易被误认为内存泄漏。除非明确知道缓存的大文件会被随机访问（比如日志检索、二进制解析），否则不值得引入 mmap。更通用的解法是：缓存里只存 *os.File 句柄 + offset/length，配合 io.ReadAt 按需读块——这样既省内存，又能保持跨平台。

• 缓存 value 类型可以定义为 interface{ ReadAt([]byte, int64) (int, error) }，底层是 *os.File 或 bytes.Reader
• 小文件走内存缓存（[]byte），大文件走句柄缓存（*os.File），由大小阈值自动切换
• 务必在 Set 时记录文件是否已打开，并在缓存淘汰时 Close()，否则 fd 泄漏比内存泄漏更快出问题

缓存的难点不在读写逻辑，而在元数据一致性与资源生命周期管理。inode 比时间戳靠谱，但得适配 Windows；LRU 比 sync.Map 好控，但得自己维护链表；mmap 看似高效，但跨平台成本常被低估。这些细节不写进代码注释里，过三个月自己都看不懂为啥这么写。