Go encoding/hex.Dumper 怎样调试二进制流的十六进制输出

如果二进制数据是分块到达的，想在日志里同时看到偏移、十六进制字节和可打印字符，Go 的 encoding/hex.Dumper 比先把全部数据拼成一个大切片更合适。它返回一个 io.WriteCloser：每次 Write 追加输入，输出采用 hexdump -C 风格；最后必须调用 Close，让不足 16 字节的尾行完成排版。

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

hex.Dumper 解决的是“连续字节流怎样写成可读的调试记录”，不是“怎样得到一行十六进制字符串”。正确用法是创建一次、分块写入、检查每次写入错误，再检查 Close 的收尾错误。

Dumper 和 Dump 的使用边界

hex.Dump(data) 适合已经在内存中的一段完整数据，返回一个字符串；hex.Dumper(w) 适合数据还会继续到达的场景，把格式化结果直接写入目标 io.Writer。目标可以是文件、缓冲区、网络包装器或自定义的测试 Writer。

两者的选择可以先看数据生命周期：

怎样把分块数据写成十六进制调试记录

创建 Dumper 时传入目标 Writer，之后可以多次调用 Write。Dumper 会自己维护累计偏移；数据是否分成两次、三次写入，不会改变最终每行 16 字节的格式边界。

package main

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

func main() {
	var output bytes.Buffer
	dumper := hex.Dumper(&output)

	// 模拟网络包分成两块到达，Dumper 会连续维护偏移和当前行。
	chunks := [][]byte{
		{0x47, 0x6f, 0x20, 0x62, 0x79, 0x74, 0x65, 0x73},
		{0x20, 0x61, 0x72, 0x65, 0x20, 0x75, 0x73, 0x65, 0x66, 0x75, 0x6c},
	}
	for _, chunk := range chunks {
		// Write 的错误表示目标 Writer 是否接受了这一块数据。
		if _, err := dumper.Write(chunk); err != nil {
			log.Fatal(err)
		}
	}

	// Close 负责把不足 16 字节的尾行补齐并写入 ASCII 侧栏。
	if err := dumper.Close(); err != nil {
		log.Fatal(err)
	}
	fmt.Print(output.String())
}

输出的每行包含三部分：左侧是当前行起始偏移，中间是十六进制字节，右侧是可打印字符；不可打印字节会显示为点号。下面只是格式示意，文章中的插图同样是概念说明，不代表本机执行结果。

00000000  47 6f 20 62 79 74 65 73  20 61 72 65 20 75 73 65  |Go bytes are use|
00000010  66                                             |f|

这里使用 bytes.Buffer 只是为了让示例可以把结果继续交给测试或日志组件；生产代码也可以把文件或其他实现了 io.Writer 的目标直接传给 hex.Dumper。

为什么最后一定要调用 Close

完整的 16 字节行在写入最后一个字节时就能结束，但尾部不足 16 字节时，Dumper 仍保留当前行状态。Close 会补齐十六进制区域、补上右侧分隔符和换行，然后把最后的 ASCII 侧栏写出去。

package main

import (
	"encoding/hex"
	"os"
)

func dumpFileLikeStream(dst *os.File, chunks [][]byte) error {
	dumper := hex.Dumper(dst)
	for _, chunk := range chunks {
		// 中途写失败时立即返回，避免把后续数据误认为已记录。
		if _, err := dumper.Write(chunk); err != nil {
			_ = dumper.Close()
			return err
		}
	}

	// Close 的错误可能来自最后一行的补齐写入，不能只依赖前面的 Write。
	return dumper.Close()
}

调用方如果用 defer dumper.Close()，要注意一个常见问题：被 defer 忽略的返回值无法报告尾行写入失败。只要目标 Writer 可能返回错误，就应该把 Close 写成显式返回值，或者使用一个能保存收尾错误的清理函数。

关闭后的调用和重复关闭怎么处理

关闭以后再调用 Write，Dumper 会返回“dumper closed”错误；因此它不是可以反复开启和复用的格式化器。需要记录下一段独立数据时，重新用同一个目标 Writer 创建新的 Dumper，并明确是否需要新的偏移起点。

package main

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

func main() {
	var output bytes.Buffer
	dumper := hex.Dumper(&output)

	// 先写入一段数据并完成尾行收尾。
	_, _ = dumper.Write([]byte{0x01, 0x02, 0x03})
	_ = dumper.Close()

	// 关闭后写入会得到错误，调用方不能继续把它当成活跃 Writer。
	_, err := dumper.Write([]byte{0x04})
	fmt.Println(err)
}

若用 Close 后的错误来判断一段诊断记录是否完整，建议将每段数据的创建、写入和关闭放在同一个函数中。这样不会把某一段已关闭的 Dumper 误传给下游。

错误处理和 Writer 选择建议

hex.Dumper 本身不负责重试、落盘或并发同步，它只是把格式化后的字节写到传入的 Writer。生产代码可以按下面的方式分层：

• 输出到文件时，检查每个 Write 和最终 Close，必要时再由文件层负责同步或关闭。
• 输出到网络或管道时，把返回错误视为诊断记录可能不完整，不要继续发送同一段数据的后半部分。
• 输出到 bytes.Buffer 时，写入通常不会失败，但仍保留统一的错误处理结构，方便替换目标 Writer。
• 多个 goroutine 同时写同一个 Dumper 前，先在外层做串行化；不要把并发安全假设交给 io.Writer 接口。

小结

需要调试连续二进制流时，hex.Dumper 的关键用法只有三点：创建一次并传入目标 Writer，按任意分块顺序检查 Write，最后显式检查 Close。Write 负责持续追加，Close 负责最后不足 16 字节的尾行；关闭后再次写入则是调用边界错误。

常见问题

Dumper 和 hex.EncodeToString 有什么区别？

EncodeToString 只生成连续的十六进制字符；Dumper 还会输出偏移、分组空格和 ASCII 侧栏，更适合人工排查原始字节。

分两次 Write 会不会让偏移重新从零开始？

不会。只要还是同一个 Dumper，它会维护累计字节数；只有创建新的 Dumper，才会开始新的格式化状态。

只检查 Write 不检查 Close 可以吗？

不建议。最后一行可能在 Close 时才写出，忽略其错误会让调用方误以为整段调试记录已经完整。

Close 后可以继续复用 Dumper 吗？

不可以。关闭后继续 Write 会返回错误；需要新的独立记录时，应重新创建 Dumper。

hex.Dumper 会自动把结果写入日志吗？

不会。它只写入创建时传入的 io.Writer，日志格式、文件生命周期和并发控制仍由调用方负责。

把它记成一个小协议：Write 记录流，Close 封口；只要目标 Writer 可能失败，两处返回值都要保留。