Go hex.Dumper 写入失败时怎样保留底层 Writer 的错误

使用 hex.Dumper 输出二进制诊断信息时，真正需要检查的是两处：Write 是否把数据交给了底层 io.Writer，以及 Close 是否成功补完了最后一行。只看 Write 的返回值会漏掉不足 16 字节数据的收尾错误；只看 Close 又可能覆盖更早出现的写入错误。

稳妥的做法是保留 Write 返回的首个错误，再调用一次 Close 完成收尾；如果首个错误为空，才使用 Close 的错误。hex.Dumper 只关闭自己的格式化状态，不会替调用方关闭底层 Writer。

官方文档：https://pkg.go.dev/encoding/hex#Dumper

先分清 hex.Dumper 与底层 Writer 的职责

hex.Dumper(w) 返回的是一个 io.WriteCloser。它把输入字节组织成类似 hexdump -C 的文本，再多次调用传入的 io.Writer。因此，诊断输出失败不是“十六进制转换失败”，而是格式化层把结果写入日志文件、缓冲区或网络流时失败。

Write 的错误从哪里返回

一次 Write 并不等于底层 Writer 只被调用一次。实现可能先写行头，再写字节区域，完整一行时还要写 ASCII 区域。只要其中一次返回错误，Write 就会把错误带回调用方，n 只代表已经被 Dumper 接受并处理的输入字节数。

排查时不要把 n == len(data) 当成持久化成功的证明，也不要忽略一个非空错误。底层 Writer 如果违反 io.Writer 约定，返回短写却给出 nil，上层无法凭空修复；应先修正这个 Writer，或在边界处使用符合契约的包装器。

// 这个 Writer 用于说明：底层失败应把错误原样交给 Dumper。
type failWriter struct {
    limit int
    wrote int
}

func (w *failWriter) Write(p []byte) (int, error) {
    // 达到上限后停止写入，避免诊断输出继续覆盖失败现场。
    if w.wrote >= w.limit {
        return 0, errors.New("diagnostic sink is full")
    }
    left := w.limit - w.wrote
    if len(p) > left {
        w.wrote += left
        // io.Writer 发生短写时必须同时返回非 nil 错误。
        return left, io.ErrShortWrite
    }
    w.wrote += len(p)
    return len(p), nil
}

Close 负责补齐最后一行

当输入长度不是 16 的整数倍时，Dumper 会保留当前行状态。Close 才会写入空白填充、右侧 ASCII 内容和换行符；因此底层磁盘已满、网络断开或自定义 Writer 在收尾阶段失败，都可能只在 Close 返回。

另外，Close 会把 Dumper 标记为已关闭，重复调用不会再次补写。不要用两个不同的 defer 分别处理同一个 Dumper，也不要在忽略返回值的 defer d.Close() 后声称日志已完整。

用包装函数保留首个错误

下面的写法适合把诊断输出作为一次可判断的操作：先记录 Write，再调用 Close；只有前面没有错误时才返回收尾错误。底层 Writer 如果自己实现了 Close，则仍需由外层单独关闭。

// dumpHex 只负责 Dumper 生命周期，不接管底层 Writer 的关闭。
func dumpHex(w io.Writer, data []byte) error {
    d := hex.Dumper(w)
    _, writeErr := d.Write(data)
    closeErr := d.Close() // Close 可能补写最后一行，不能省略。

    // 首个错误最接近根因，避免收尾错误掩盖它。
    if writeErr != nil {
        return writeErr
    }
    return closeErr
}

// 文件等底层资源由调用方负责关闭，并单独处理其错误。
func writeFile(path string, data []byte) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    if err := dumpHex(f, data); err != nil {
        _ = f.Close() // 先保留 Dumper 的根因，再释放文件描述符。
        return err
    }
    return f.Close()
}

如果业务需要同时保留两个错误，可在 Go 1.20 及更高版本用 errors.Join(writeErr, closeErr)；但日志、告警或重试分类通常仍应把 Write 失败作为主因记录。

常见边界与简短问答

• Close 会关闭传入的文件吗？不会。它只结束 Dumper 自己的格式化生命周期，文件或网络连接仍由调用方管理。
• 只输出整行数据还要检查 Close 吗？要。即使当前输入恰好填满一行，统一检查 Close 才能覆盖未来改成分块写入、Writer 收尾失败等变化。

把 Write 和 Close 看作同一次诊断输出的两个错误出口，文章标题中的“保留底层 Writer 的错误”就落到了可执行的代码边界：不吞错、不重复关闭，也不把格式化层的完成误认为底层资源已经成功落盘。