Go 用 io/fs 做配置目录快照：过滤、排序与差异报告小工具

部署前把 config-prod/ 复制到候选机器，最怕的不是文件夹不存在，而是两边服务都能正常启动，里面却悄悄少了一个 feature-flags.json，又或者证书文件只改了一个字节没人发现。这类小问题根本不用找第三方 diff 工具，直接用 Go 标准库写个只读文件夹快照小工具，就能把全量文件集合和内容差异输出成可回溯复查的 JSON 文件。

这次的小工具只做三件事：遍历文件夹、为每个文件生成相对路径和 SHA-256 摘要、对比两份快照后报告新增、缺失和内容变化；它不会自动覆盖任何文件。

先把文件夹核对边界定下来

假设有两份文件夹：config-prod/ 是基准版本，config-candidate/ 是待发布版本。我们只关心普通文件，不跟随符号链接，不读取隐藏配置，把每个文件压缩成下面三个字段：

这三个字段足够支撑一次完整核对。工具不判断哪一边“正确”，也不把摘要当作安全签名；生产环境仍要做好配置文件本身和输出报告的访问权限管控。

用 WalkDir 收集稳定的文件清单

文件夹遍历的第一版最容易写成“拿到路径就直接比较”。我更建议先收集成 map[string]FileRecord，再统一排序和对比。这样就算不同文件系统返回目录项的顺序不一样，最终报告也不会出现换行乱跳、排序随机的问题。

type FileRecord struct {
    Path   string `json:"path"`
    Size   int64  `json:"size"`
    Digest string `json:"digest"`
}

func collect(root string) (map[string]FileRecord, error) {
    files := make(map[string]FileRecord)
    err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            return walkErr
        }
        if path != root && strings.HasPrefix(entry.Name(), ".") {
            if entry.IsDir() {
                return fs.SkipDir
            }
            return nil
        }
        if entry.IsDir() || !entry.Type().IsRegular() {
            return nil
        }

        rel, err := filepath.Rel(root, path)
        if err != nil {
            return err
        }
        rel = filepath.ToSlash(rel)
        record, err := digestFile(path, rel)
        if err != nil {
            return err
        }
        files[rel] = record
        return nil
    })
    return files, err
}

entry.Type().IsRegular() 的意义在这里很明确：文件夹只负责继续向下遍历，符号链接、设备文件等非普通文件不进入快照。隐藏目录返回 fs.SkipDir，不会继续向下访问；隐藏普通文件则直接跳过。

边读边计算摘要，不把大文件塞进内存

拿到路径后再打开文件，使用 io.Copy 把内容流进 SHA-256 哈希器，同时记录文件大小。这样哪怕是 500 MB 的压缩包也只需要占用很小的工作内存。

func digestFile(path, rel string) (FileRecord, error) {
    file, err := os.Open(path)
    if err != nil {
        return FileRecord{}, err
    }
    defer file.Close()

    info, err := file.Stat()
    if err != nil {
        return FileRecord{}, err
    }
    hash := sha256.New()
    if _, err := io.Copy(hash, file); err != nil {
        return FileRecord{}, err
    }
    return FileRecord{
        Path: rel, Size: info.Size(), Digest: hex.EncodeToString(hash.Sum(nil)),
    }, nil
}

这里的摘要用于判断“内容是否变化”，不是用来替代权限校验或机密文件加密。遇到读取失败时直接返回错误，比生成一个不完整的快照结果更可靠。

把两份快照变成三类差异

对比时先取两份记录的路径并集，再按路径排序。基准侧没有而候选侧有，就是 added；反过来是 missing；两侧都有但摘要不同，则是 changed。

type Diff struct {
    Kind string     `json:"kind"`
    Path string     `json:"path"`
    Base *FileRecord `json:"base,omitempty"`
    Next *FileRecord `json:"next,omitempty"`
}

func compare(base, next map[string]FileRecord) []Diff {
    all := make(map[string]struct{}, len(base)+len(next))
    for path := range base { all[path] = struct{}{} }
    for path := range next { all[path] = struct{}{} }
    paths := make([]string, 0, len(all))
    for path := range all { paths = append(paths, path) }
    sort.Strings(paths)

    diffs := make([]Diff, 0)
    for _, path := range paths {
        left, hasLeft := base[path]
        right, hasRight := next[path]
        switch {
        case !hasLeft:
            diffs = append(diffs, Diff{Kind: "added", Path: path, Next: &right})
        case !hasRight:
            diffs = append(diffs, Diff{Kind: "missing", Path: path, Base: &left})
        case left.Digest != right.Digest:
            diffs = append(diffs, Diff{Kind: "changed", Path: path, Base: &left, Next: &right})
        }
    }
    return diffs
}

注意不要只比较文件总数。两边各有 12 个文件，并不代表它们的路径和内容完全一致；稳定排序也不是为了视觉好看，而是为了让同一次核对生成的 JSON 在代码审查和流水线日志里可以直接对比。

做一个能复查结果的命令行入口

把入口限定成两个文件夹参数：go run . config-prod config-candidate。输出对象包含扫描数量、差异数组和错误信息；只要存在差异，就返回状态 2，参数或读取失败返回状态 1，完全一致才返回状态 0。

type Report struct {
    BaseFiles int    `json:"base_files"`
    NextFiles int    `json:"next_files"`
    Diffs     []Diff `json:"diffs"`
}

func main() {
    if len(os.Args) != 3 {
        fmt.Fprintln(os.Stderr, "用法: go run .  ")
        os.Exit(1)
    }
    base, err := collect(os.Args[1])
    if err != nil { fmt.Fprintln(os.Stderr, "基准目录读取失败:", err); os.Exit(1) }
    next, err := collect(os.Args[2])
    if err != nil { fmt.Fprintln(os.Stderr, "候选目录读取失败:", err); os.Exit(1) }
    report := Report{BaseFiles: len(base), NextFiles: len(next), Diffs: compare(base, next)}
    enc := json.NewEncoder(os.Stdout)
    enc.SetIndent("", "  ")
    if err := enc.Encode(report); err != nil { os.Exit(1) }
    if len(report.Diffs) > 0 { os.Exit(2) }
}

可以先覆盖四个边界场景测试：完全一致、候选新增文件、基准缺失文件、同名文件内容变化。命令行里用 echo $? 读取退出状态，不要用“输出里是否出现 changed”这类脆弱的字符串判断。

mkdir -p config-prod config-candidate
printf 'port=8080\n' > config-prod/app.properties
cp config-prod/app.properties config-candidate/app.properties
printf '{"checkout":true}\n' > config-prod/feature-flags.json
printf '{"checkout":false}\n' > config-candidate/feature-flags.json
printf 'debug=true\n' > config-candidate/debug.properties

go run . config-prod config-candidate
echo $?

预期的报告里会有 feature-flags.json 的 changed 和 debug.properties 的 added，最后状态为 2。把候选文件夹改回完全一致后再次运行，应只看到空的 diffs，状态为 0。再传入不存在的路径，确认返回状态为 1。

常见问题：这个快照工具应该放在哪里

为什么不用 os.ReadDir 一次性读取目录？

顶层目录很简单时可以用它，但递归遍历、跳过隐藏文件夹和统一处理错误时，filepath.WalkDir 更直接。两者都不会自动替你判断业务层面的“配置是否一致”。

SHA-256 摘要能证明文件绝对安全吗？

不能。它只是在本次核对里提供稳定的内容指纹，报告文件和原始配置仍然要按敏感信息管理，跨不可信环境传输时还需要额外补充签名或走安全通道。

为什么不在发现差异后直接复制修复？

因为快照工具的核心职责是给出核对证据。自动覆盖可能误伤证书、密钥或机器专属配置，应该把同步动作交给有明确备份和审批边界的发布步骤处理。

把只读核对接到发布前检查

这个小项目的价值不在于替代专业 diff 工具，而是给发布前增加一个稳定、可审查的门槛：先确认相对路径集合，再比较摘要，最后用退出状态把“继续、暂停、人工处理”的判断交给外层脚本。后续即使扩展忽略规则或者支持把 JSON 快照落盘，也建议保留三类差异的输出逻辑和只读原则，避免核对工具演变成不可控的同步脚本。