Go hex.Dumper 关闭前为什么必须处理剩余字节

我第一次把二进制数据写进 hex.Dumper 时，误以为每次 Write 都会产生一整行输出。实际情况是：Dumper 按 16 个字节组织一行，最后不足 16 个字节的部分要等 Close 才会补齐右侧 ASCII 区和换行。忘记关闭时，尾部看起来就像“少了一截”。

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

只要使用 hex.Dumper，就把它当作 io.WriteCloser 管理：检查 Write 的错误，最后一定调用 Close，并单独处理 Close 的错误。Close 负责收尾当前未满一行的字节，但不会替你关闭底层的 io.Writer。

hex.Dumper 先把字节分配到当前行

hex.Dumper 返回的是 io.WriteCloser，输出格式与命令行 hexdump -C 相同。它内部会记录当前行已经使用的字节数 used、总偏移 n，同时准备十六进制列和 ASCII 列。满 16 个字节时，整行才会写出并把 used 归零。

因此，Write 返回的 n 表示已经从调用方数据中消费了多少字节，不等于“已经在目标 writer 上形成了完整可读行”。下面的写法保留了两个错误出口，并把关闭动作放在所有写入之后：

package main

import (
	"bytes"
	"encoding/hex"
	"fmt"
)

func dump(data []byte) (string, error) {
	var dst bytes.Buffer
	d := hex.Dumper(&dst)

	// Write 可能只消费部分输入，先记录 n 和 err，避免静默丢失数据。
	n, err := d.Write(data)
	if err != nil {
		return "", fmt.Errorf("写入十六进制转储失败，已消费 %d 字节: %w", n, err)
	}
	// Close 负责补齐最后一行；它不会关闭 bytes.Buffer。
	if err := d.Close(); err != nil {
		return "", fmt.Errorf("关闭十六进制转储失败: %w", err)
	}
	return dst.String(), nil
}

Close 怎样补齐尾行

当输入长度不是 16 的倍数时，最后一行只有部分字节。Close 会把十六进制列剩余位置填成空白，再写入 ASCII 右栏和换行；这样最后一行仍保持固定的可读布局。若恰好没有剩余字节，Close 不需要再写尾行，但仍会把 Dumper 标记为关闭。

这也是为什么不能把 Close 当成可有可无的“资源礼貌动作”。它承担的是输出格式的最后一段写入。尤其是写入文件、网络响应或自定义 writer 时，尾行是否完整会直接影响后续读取者能否按固定格式观察数据。

写入时如何把错误传出去

Dumper 的底层目标仍是普通 io.Writer。如果目标 writer 在写十六进制列、ASCII 列或尾行时返回错误，Dumper 会把错误交给调用方。生产代码不要只写 defer d.Close() 就结束，因为这样很容易丢掉 Close 的返回值。

如果要用 defer，可以让函数使用命名返回值，在关闭阶段只补充尚未出现的错误；如果关闭动作本身失败，就应保留这个错误。对于已经发生的 Write 错误，不要继续把更多数据写入同一个 Dumper。Write 成功后也不能跳过 Close，因为成功只说明输入字节被接收，不说明不完整尾行已经落到 writer。

和 hex.Dump 的职责区别

只需要把一段已经在内存中的字节转换成字符串时，hex.Dump(data) 更简单。标准库实现内部同样会创建 Dumper，执行一次写入并调用 Close，所以调用者不需要自己管理尾行。

需要把大数据分片写到文件、日志或网络目标时，再选择 hex.Dumper(writer)。这时要记住三点：

• Write 负责接收输入并维护当前行，不保证每次调用形成完整行。
• Close 负责最后不足 16 字节的格式化，并让后续写入返回关闭错误。
• 底层 io.Writer 的生命周期由调用者决定，关闭 Dumper 不等于关闭它。

常见问题

为什么 Write 返回成功，输出却没有最后一行？

因为最后一行可能仍保存在 Dumper 的内部状态里。输入被接收不代表尾行已经完成，写入结束后调用 Close 才会补齐它。

Close 调用两次会重复写尾行吗？

不会。第一次 Close 会封存 Dumper；再次 Close 不重复输出。真正需要避免的是 Close 之前继续写，因为关闭后再写会得到错误。

把 Dumper 看成“带行状态的写入器”就不容易遗漏收尾：检查每次写入、最后关闭一次，并根据场景选择流式 Dumper 或一次性的 hex.Dump。