Go os.File 怎样保留错误信息

Go os.File 的错误应保留为 error 对象向上传递。要增加业务说明，用 fmt.Errorf("写入报告: %w", err) 包装；要同时保留写入失败和关闭失败，用 errors.Join 合并。调用方再用 errors.Is 判断错误种类、errors.As 提取 PathError，避免根据错误字符串分支。

官方地址：https://pkg.go.dev/os

使用场景：既要说明失败任务，也要知道底层原因

文件错误通常有两个读者：日志需要知道哪个业务任务失败，程序需要决定是否提示文件已存在、权限不足或采取其他处理。只补一句“保存失败”会丢掉原因；只返回底层错误，又可能缺少业务上下文。包装可以同时满足两者。

遇到 err 后立即决定如何返回，不要继续使用失败操作产生的文件句柄。打开成功后，关闭文件的职责也必须明确。下面以创建新报告为例，不读取私人文件，不展示真实运行日志。

候选方案：直接返回、文本转换、包装与合并

errors.New(err.Error()) 也只得到一个新文本错误，不会保留原有类型或原因关系。%w 应传入非空的真实错误，先判断 err != nil，再包装；不要对 nil 无条件构造所谓成功错误。

PathError 含 Op、Path、Err，os.PathError 是 fs.PathError 的别名。保留它能让内部诊断继续读取这些信息，但是否对外显示完整路径应由接口层决定。错误链也不是自动堆栈追踪，%w 不会自动记录所有调用位置。

推荐写法：写入和关闭失败都保留

示例使用 Go 1.20 及以上提供的 errors.Join。它丢弃 nil 参数；所有参数为 nil 时返回 nil。下面只在 Close 失败时调用 Join，因此主错误正常、关闭失败也会得到非空结果。

package fileops

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

// CreateReport 只创建新文件，不覆盖已有文件；目录须预先存在。
func CreateReport(path string, data []byte) (err error) {
    f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
    if err != nil {
        return fmt.Errorf("创建报告: %w", err)
    }
    defer func() {
        if closeErr := f.Close(); closeErr != nil {
            // 命名返回值承接主错误，关闭错误作为独立分支保留。
            err = errors.Join(err, fmt.Errorf("关闭报告: %w", closeErr))
        }
    }()

    n, writeErr := f.Write(data)
    if writeErr != nil {
        return fmt.Errorf("写入报告（%d/%d 字节）: %w", n, len(data), writeErr)
    }
    return nil // 返回前仍会执行上面的关闭操作。
}

func Describe(err error) string {
    if err == nil {
        return "成功"
    }
    if errors.Is(err, fs.ErrExist) {
        return "目标已存在；原文件未由本次创建操作覆盖"
    }
    var pe *os.PathError
    if errors.As(err, &pe) {
        // 只展示操作，不把内部文件路径交给外部用户。
        return fmt.Sprintf("文件操作失败，操作=%s", pe.Op)
    }
    return "报告处理失败"
}

代码选用 O_EXCL，已有目标会使创建失败，避免示例直接覆盖文件。创建成功后，如果 Write 失败，命名返回值 err 先接住写入错误，defer 再把关闭错误加入。不要在 defer 中无条件写 err = f.Close()，否则关闭成功的 nil 会覆盖原始失败。

os.File.Write 会返回写入数量和错误；短写时有非 nil 错误。示例把 n 和目标长度纳入上下文，但保留 writeErr 本身，不根据文本重新猜测错误种类。CreateReport 内不使用 os.Exit 或 log.Fatal，以免跳过当前函数尚未执行的 defer；退出策略留给上层。

调用方怎么选：原因判断和类型提取分工

判断“是否属于已存在”使用 errors.Is(err, fs.ErrExist)，比查找字符串里的英文提示稳定。需要 PathError 的结构信息时，用 errors.As(err, &pe)；直接 err.(*os.PathError) 无法穿过外层包装。

对于 Join 构成的错误树，errors.As 找到第一个匹配项便返回，并不会收集所有 PathError。若业务一定要分别报告写入和关闭的详细字段，可以定义具有明确字段的业务错误类型；不要把一次 As 的结果当成全部原因。

errors.Unwrap 只处理 Unwrap() error，不会展开 Join 的 Unwrap() []error。一般的原因判断交给 Is、As，避免手写一个只认识单链的循环而遗漏分支。

不适用情况：错误保留不等于事务保存

这个函数失败时可能已经创建文件，甚至写入一部分内容。它不负责失败回滚，也不保证原子发布或断电持久化。返回 nil 只表明这里检查的创建、写入、关闭没有报告错误；需要更强的保存协议时，应另外设计临时文件、同步和替换策略，不能由“保留错误”推导出保证。

如果使用 bufio.Writer，还需要处理 Flush 的返回错误；只检查底层 File.Close 不会自动冲刷那个独立缓冲对象。若把 File 的所有权交给别的层，关闭位置也应随所有权转移，不能两边都关闭。

选择表与常见问题

只写 defer f.Close() 可以吗？

能执行关闭，但返回的关闭错误被忽略。对写入完成结果有要求的函数，应显式处理关闭错误，并说明它与主错误的优先级。

每一层都需要记录日志吗？

不一定。常见做法是在处理边界统一记录完整错误，中间层只包装与自己有关的上下文，避免同一失败重复产生多份日志。

Join 后错误文字为什么有换行？

Join 的文字表示会用换行连接各原因的文字。结构化日志应把它作为一个错误字段保存，不要把每行都当成不同请求。

官方依据：File.Write 与文件错误、Errorf 包装、Join、Is、As 与 Unwrap。