Go filepath.WalkDir 怎样复用已有缓冲空间

我在一个需要反复扫描目录的 Go 小工具里，最初把“复用已有缓冲空间”理解成给 filepath.WalkDir 传一个可复用的内部 buffer。这个方向其实走不通：WalkDir 的函数签名只有根路径和回调，目录读取及其内部临时空间由标准库管理，回调没有接管入口。

真正可控的做法是复用调用方自己的结果切片：每轮扫描前把 results 的长度切回 0，保留已有容量，再把匹配到的路径 append 回去。如果结果只用于当场处理，连结果切片都可以不要，直接在回调中消费。

先厘清 WalkDir 能复用什么

filepath.WalkDir 会遍历根目录本身，并通过 fs.WalkDirFunc 把路径、fs.DirEntry 和错误交给回调。它按字典序读取目录，且不会跟随符号链接；这些行为是 API 语义，不等于调用方可以控制标准库内部的目录读取缓存。

可以复用的是回调之外的业务缓冲，例如保存筛选结果的 []string。路径字符串一旦被 append 到结果切片，就由结果切片持有，不要把“复用切片容量”说成“复用 WalkDir 的内部 path 字符串”。

用切片容量承接重复扫描结果

重复调用时，最小改动是把结果切片作为参数传入，并在函数开头执行 results = results[:0]。这只改变长度，不清掉 backing array；后续 append 在容量足够时可以继续写入原来的数组。

package main

import (
    "io/fs"
    "path/filepath"
    "strings"
)

// collectGoFiles 复用调用方的结果切片，只收集当前目录树中的 Go 文件。
func collectGoFiles(root string, results []string) ([]string, error) {
    // 清空长度但保留容量，给下一轮扫描继续使用 backing array。
    results = results[:0]

    err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
        // 目录读取或访问失败时交回错误，避免继续使用不完整的 entry。
        if walkErr != nil {
            return walkErr
        }
        // 目录只负责遍历，不把目录本身放进结果集合。
        if entry.IsDir() {
            return nil
        }
        // 用文件名做轻量筛选，命中的完整路径才进入复用的结果切片。
        if strings.HasSuffix(entry.Name(), ".go") {
            results = append(results, path)
        }
        return nil
    })
    return results, err
}

调用方可以这样保留容量：

// 预留一小段容量，后续多轮扫描尽量复用同一 backing array。
files := make([]string, 0, 128)
files, err := collectGoFiles("./cmd", files)
if err != nil {
    // 扫描失败时不要把不完整的结果当成完整清单。
    panic(err)
}

这里复用的是 files 的存储空间，不保证每一轮都没有分配：如果本轮匹配项超过容量，append 仍会扩容。并且，下一轮复用前不能再依赖上一轮返回切片中已经被覆盖的元素。

把筛选和资源生命周期放进回调

如果只需要统计数量、写入摘要或把文件交给下游处理，就不必把全部路径保存到切片。回调里的 path 和 entry 已经足够完成判断，处理完后让它们自然离开当前回调即可。

// countGoFiles 只统计数量，不创建长期保存的路径结果集合。
func countGoFiles(root string) (int, error) {
    count := 0
    err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
        // 访问失败必须返回，让 WalkDir 将错误交给调用方。
        if walkErr != nil {
            return walkErr
        }
        // 目录不参与文件计数，避免把根节点和子目录算进去。
        if entry.IsDir() {
            return nil
        }
        // 只保留当前回调需要的判断，不把 path 逃逸到长期集合。
        if strings.HasSuffix(entry.Name(), ".go") {
            count++
        }
        return nil
    })
    return count, err
}

需要跳过某个目录时，可以在确认 entry.IsDir() 后返回 filepath.SkipDir；不要把它当作通用的内存复用开关。遇到回调收到的错误时，优先返回错误，除非业务已经明确设计了可接受的跳过策略。

判断复用是否值得

复用切片最适合“扫描结果规模大致稳定、同一个调用方串行重复使用”的场景。若结果要交给异步任务或多个 goroutine，就应当把所有权分开：每个并发任务使用自己的切片，或者在交接前复制一份，不能让下一轮扫描覆盖仍在读取的底层数组。

我的经验是先把“内部缓冲不可控”和“业务结果可复用”分开，再根据结果是否要跨回调、跨 goroutine 存活来选方案。只要切片所有权清楚，WalkDir 本身不需要也不应该被改造成带用户 buffer 参数的接口。

常见问题

把 results[:0] 当成清空所有数据安全吗？

它只把长度设为 0，底层数组中的旧元素可能仍然存在，但从切片视图看已不可遍历。下一轮 append 会覆盖需要的位置；如果元素是指针或大对象引用，想尽早释放引用时应按业务需要清零，而不是只依赖切片截断。

能不能把 WalkDir 的内部 buffer 传进去？

不能。标准库没有这样的参数或接口。你能控制的是回调里如何筛选、是否收集，以及自己维护的结果切片容量。