Go encoding/hex.Dumper 怎样把十六进制转储接到日志流

排查二进制协议或文件片段时，单纯打印 []byte 往往看不出偏移和可读字符的对应关系。Go 标准库的 encoding/hex.Dumper 可以把写入的字节流转换成接近 hexdump -C 的格式，再接到日志缓冲区、文件或自定义 io.Writer。它返回的是 io.WriteCloser，所以最后的 Close 不能省略。

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

如果目标是持续观察一段字节流，就让 hex.Dumper 包住日志写入器；每次调用 Write 写入原始字节，完成后调用 Close 收尾。不要把 Dumper 当成解码器，它只负责生成诊断用的十六进制转储。

这次遇到的症状通常是“日志里只有一串不可读字符”或“最后半行没有出现在转储中”。根因分别是输出目标不适合直接阅读，以及把 WriteCloser 当成普通 io.Writer 使用后没有收尾。

先确认日志需要的是流式转储

hex.Dump(data) 适合手里已经有完整的 []byte，会直接返回字符串；hex.Dumper(w) 则适合数据分批到达的场景。后者不会要求调用方先把全部数据拼成一个大切片，偏移、十六进制列和右侧 ASCII 区域会随写入内容组织起来。

两者的输出格式目标相同，但生命周期不同：Dump 返回普通字符串，Dumper 需要维护一个写入状态，并通过关闭动作完成最后一行的整理。排查网络帧、压缩文件头或短消息拼接问题时，流式方式更容易放在现有复制链路里。

把 hex.Dumper 接到日志 Writer

下面的例子把转储结果写入内存缓冲区，实际项目中可以换成文件、带前缀的日志 Writer 或测试用的自定义 Writer。关键点是：业务数据写给 Dumper，转储文本才写给最终日志目标。

func dumpBytes(dst io.Writer, chunks [][]byte) (string, error) {
	// 用缓冲区承接转储文本，便于一次性附加到结构化日志字段。
	var buf bytes.Buffer
	dumper := hex.Dumper(&buf)

	for _, chunk := range chunks {
		// Write 的输入是原始字节，不要先转成十六进制字符串。
		if _, err := dumper.Write(chunk); err != nil {
			// 目标写入失败时保留原错误，方便上层决定是否降级日志。
			_ = dumper.Close()
			return "", err
		}
	}
	// Close 负责结束转储并整理最后一行，调用结果也必须被处理。
	if err := dumper.Close(); err != nil {
		return "", err
	}

	// 把已经完成的转储文本交给真正的日志目标。
	if _, err := io.WriteString(dst, buf.String()); err != nil {
		return "", err
	}
	return buf.String(), nil
}

这里的 dst 只接收已经完成的文本，便于在日志系统里统一加时间、请求 ID 或级别。若直接把 dst 传给 hex.Dumper，也可以减少一次缓冲，但就要确认日志 Writer 能承受多次小写入，并能正确处理 Dumper 的关闭错误。

写入错误和 Close 错误要分开看

Dumper.Write 的错误通常来自底层 io.Writer，例如文件写满、网络日志管道中断或自定义 Writer 拒绝写入。此时应保留写入错误，不要用一次 Close 的结果覆盖它。另一方面，最后不足一整行的数据可能要在 Close 时补齐排版，因此正常写入结束后必须单独判断关闭结果。

func writeDump(w io.Writer, payload []byte) error {
	// Dumper 返回 WriteCloser，不能只用 defer 忽略 Close 的错误。
	dumper := hex.Dumper(w)
	if _, err := dumper.Write(payload); err != nil {
		// 写入已经失败，记录原始错误；Close 只做尽力收尾。
		_ = dumper.Close()
		return fmt.Errorf("写入十六进制转储失败: %w", err)
	}
	if err := dumper.Close(); err != nil {
		// 关闭阶段的错误说明转储收尾或底层 Writer 仍未成功完成。
		return fmt.Errorf("关闭十六进制转储失败: %w", err)
	}
	return nil
}

如果底层目标只是 bytes.Buffer，关闭通常不会产生业务上可见的故障；但把代码写成显式处理，换成文件或网络 Writer 时仍然成立。不要把所有错误都改写成“hex 格式错误”，因为 Dumper 本身不是解析器。

生产日志要设边界

十六进制转储非常适合短片段诊断，但不适合不加限制地记录整个请求、文件或密钥材料。接入前至少明确三件事：只截取必要的字节范围；对可能包含凭据、令牌或个人数据的内容先脱敏；给日志字段设置长度和采样边界。

最终可以记住一个简单边界：hex.Dumper 负责把“写入的字节”变成“便于人读的转储”，不负责判断协议是否合法，也不负责保护敏感数据。把写入、收尾、错误和日志范围分别处理，问题就不会集中到最后一行缺失或日志爆量上。

相关问题

hex.Dumper 和 hex.Dump 有什么区别？

Dump 接收完整字节切片并返回字符串；Dumper 返回写入器，适合把分段数据持续写进某个 io.Writer。

为什么写完后还要调用 Close？

Dumper 需要在结束时整理尚未组成完整行的尾部输出，而且关闭阶段也可能暴露底层 Writer 的错误。

能不能把 Dumper 直接用于生产访问日志？

可以用于受控的短片段诊断，但应先限制长度、采样并脱敏。完整请求体或密钥材料不应直接转成十六进制日志。