Go io/fs文件不存在与权限错误的分类处理

使用 io/fs 读取文件时，最容易误判的是把所有失败都当成“文件不存在”。更稳妥的做法是保留错误链，用 errors.Is 判断 fs.ErrNotExist、fs.ErrPermission 和 fs.ErrInvalid，再用 errors.As 取出 *fs.PathError 的操作名与路径。这样，缺文件可以走默认值或未找到分支，权限问题可以提示授权，非法路径则回到输入校正。

分类判断看哨兵错误，不看错误字符串；日志保留 PathError 上下文，业务层按类别决定是否重试。

io/fs错误为什么要沿着错误链判断

fs.FS 的核心接口是 Open(name)。按照标准库约定，失败通常由 *fs.PathError 携带 Op、Path 和底层 Err。底层错误可能还会被业务层再次包装，所以判断时要让 errors.Is 沿着 Unwrap 链查找。

直接写 err == fs.ErrNotExist 只适合没有任何包装的偶然情况；面对 PathError 或 fmt.Errorf("读取失败: %w", err)，它就可能漏判。错误文本同样不稳定，不能拿“no such file”或“permission denied”做程序分支。

用errors.Is写一个稳定的分类函数

把分类集中到一个小函数，调用方只消费有限的类别，能避免每个业务入口各写一套近似判断。

package main

import (
    "errors"
    "fmt"
    "io/fs"
)

// classifyFSError 只返回业务需要的稳定类别，不依赖系统错误文本。
func classifyFSError(err error) string {
    if err == nil {
        return "ok"
    }
    switch {
    case errors.Is(err, fs.ErrNotExist):
        return "not-exist"
    case errors.Is(err, fs.ErrPermission):
        return "permission"
    case errors.Is(err, fs.ErrInvalid):
        return "invalid-path"
    default:
        return "unknown"
    }
}

func main() {
    // 示例错误带有一层PathError，分类函数仍能找到底层哨兵错误。
    err := &fs.PathError{Op: "open", Path: "config/app.toml", Err: fs.ErrNotExist}
    fmt.Println(classifyFSError(err)) // not-exist
}

判断顺序可以按业务优先级调整，但不要把未知错误归入缺失文件。自定义文件系统也应尽量返回能被 errors.Is 识别的哨兵错误，调用方才不必绑定某个实现的具体类型。

用errors.As补上路径和操作上下文

分类解决“是什么”，errors.As 解决“在哪一步发生”。拿到 *fs.PathError 后，日志至少保留 Op 和 Path；但展示给终端用户时要注意路径可能包含敏感目录，不能把内部绝对路径原样回显。

func describeFSError(err error) string {
    var pathErr *fs.PathError
    if errors.As(err, &pathErr) {
        // PathError给出操作和相对路径；业务日志可再加请求编号。
        return fmt.Sprintf("op=%s path=%s kind=%s", pathErr.Op, pathErr.Path, classifyFSError(err))
    }
    // 非PathError也保留原始错误，避免把实现异常悄悄吞掉。
    return "kind=" + classifyFSError(err)
}

fs.ErrInvalid 通常表示路径不符合 io/fs 的约束，例如空路径、绝对路径或包含 .. 的元素；它和目标文件尚未创建不是一回事。先修正输入，再重新发起读取，比重试同一个非法参数更有效。

把错误类别映射成可执行动作

错误判断的价值不在于打印一个更漂亮的字符串，而在于让后续动作不同。可以把决策收敛到如下表格：

用fstest.MapFS覆盖分类边界

测试缺失文件时不需要依赖本机目录。testing/fstest.MapFS 可以构造稳定的内存文件系统；权限错误则适合在自定义FS或适配层中返回包装过的 fs.ErrPermission，重点验证调用方是否仍用 errors.Is 判断。

func TestMissingFile(t *testing.T) {
    fsys := fstest.MapFS{"present.txt": &fstest.MapFile{Data: []byte("ok")}}
    _, err := fs.ReadFile(fsys, "missing.txt")
    // 断言错误类别，而不是绑定完整错误字符串。
    if !errors.Is(err, fs.ErrNotExist) {
        t.Fatalf("want ErrNotExist, got %v", err)
    }
}

回归测试至少覆盖：存在文件返回 nil、缺失文件命中 ErrNotExist、非法路径命中 ErrInvalid，以及包装后的权限错误仍能命中 ErrPermission。真实系统权限测试可以另放在平台相关测试中，避免让主测试依赖开发机目录权限。

延伸问答

为什么不直接判断“permission denied”？

错误文本受操作系统、文件系统实现和包装方式影响。errors.Is 判断的是约定的错误语义，稳定性更适合程序分支。

PathError能否代替errors.Is？

不能。PathError 适合提取操作与路径，底层类别仍应通过 errors.Is 判断，二者职责不同。

ErrNotExist命中后一定要创建文件吗？

不一定。配置读取可以使用默认值，资源查询可以返回未找到；是否创建取决于业务权限和幂等性，不能由错误类别单独决定。