Go afero 怎么用 BasePathFs 把导出文件限定在工作目录

导出功能最容易留下的隐患，不是文件写不出来，而是调用方把路径拼成了工作目录之外的位置。我的处理方式是让导出函数只拿到一个 afero.Fs：底层使用 OsFs，外面再包一层 BasePathFs。这样导出代码只处理相对路径，../ 经过路径清理后越过根目录时会直接返回错误。

官方地址：https://github.com/spf13/afero

结论：用 afero.NewBasePathFs(afero.NewOsFs(), workDir) 建立虚拟根目录，写入时只传工作目录内的相对路径；先创建父目录，再检查返回的 error。

用 BasePathFs 给导出逻辑加一层工作目录边界

先把真实目录固定在应用配置里，再把这个目录包装成文件系统接口。导出函数不再接收任意绝对路径，而是接收类似 reports/summary.csv 的相对路径。对调用方而言，/ 就是工作目录；对底层 OsFs 而言，Afero 会把它映射回真实目录。

package export

import (
    "fmt"
    "path/filepath"

    "github.com/spf13/afero"
)

func SaveReport(workDir, name string, data []byte) error {
    // 真实文件系统只在边界创建一次，业务函数只接触虚拟根。
    osFS := afero.NewOsFs()
    scopedFS := afero.NewBasePathFs(osFS, filepath.Clean(workDir))

    // WriteFile 不负责补齐多级父目录，先准备 reports/。
    if err := scopedFS.MkdirAll("reports", 0o755); err != nil {
        return fmt.Errorf("create export directory: %w", err)
    }

    // name 只能作为工作目录内的相对路径使用。
    output := filepath.Join("reports", name)
    if err := afero.WriteFile(scopedFS, output, data, 0o640); err != nil {
        return fmt.Errorf("write report %q: %w", output, err)
    }
    return nil
}

这里的关键不是把字符串拼得更复杂，而是让所有文件操作都经过同一个 scopedFS。真实路径只在构造边界时出现一次，后续的创建、写入、读取和删除都复用这层接口。

写入导出文件时，先建目录再处理错误

如果 name 是 2026/10/report.csv，就要先创建对应的目录层级。更稳妥的做法是把“准备目录”和“写文件”分开，并给错误补上操作上下文。测试时可以用 MemMapFs 替换 OsFs，验证同一段导出逻辑而不碰磁盘。

func SaveScoped(fs afero.Fs, name string, data []byte) error {
    dir := filepath.Dir(name)
    // 当前文件就在根目录时，Dir 会返回“.”，无需创建额外目录。
    if dir != "." {
        if err := fs.MkdirAll(dir, 0o755); err != nil {
            return fmt.Errorf("mkdir %q: %w", dir, err)
        }
    }
    // 让上层知道是哪个相对路径失败，保留底层错误便于判断。
    if err := afero.WriteFile(fs, name, data, 0o640); err != nil {
        return fmt.Errorf("write %q: %w", name, err)
    }
    return nil
}

怎么确认边界真的生效

不要只测试一个成功文件，至少要覆盖根目录、嵌套目录和父级跳转。Afero 的 BasePathFs 会对路径做清理并计算相对关系；当结果是 .. 或以 ../ 开头时，操作会被视为不存在。测试可以这样写：

func TestExportBoundary(t *testing.T) {
    // 内存文件系统让边界测试不依赖开发机目录。
    base := afero.NewMemMapFs()
    scoped := afero.NewBasePathFs(base, "/work")

    if err := SaveScoped(scoped, "reports/a.csv", []byte("ok")); err != nil {
        t.Fatal(err)
    }
    // 父级跳转不应被当成另一个合法导出文件。
    if _, err := scoped.Stat("../outside.csv"); err == nil {
        t.Fatal("expected traversal path to fail")
    }
}

这里验证的是 Afero 的路径层行为，不是线上权限审计。若工作目录下存在 symlink、需要阻挡恶意进程，或导出内容来自不可信插件，还应结合操作系统权限、符号链接策略和独立进程/容器隔离；不能把 BasePathFs 单独当成完整安全边界。

相关问题

BasePathFs 能直接替代 filepath.Join 做安全校验吗？

它可以把实际文件操作统一放到限定根目录，但仍建议业务层只生成相对路径，并检查空文件名、扩展名和业务命名规则。

为什么写入嵌套文件时还要调用 MkdirAll？

路径边界和目录存在是两件事。BasePathFs 只负责把操作映射到根目录内，父目录不存在时仍会由底层文件系统返回错误。

测试环境应该使用哪种文件系统？

只验证导出逻辑时使用 MemMapFs 更快、更隔离；需要确认真实权限、文件模式或 symlink 行为时，再补充针对 OsFs 的集成测试。