Go encoding/hex 怎样生成可读的十六进制转储

如果输入已经完整放在一个 []byte 里，直接调用 hex.Dump(data) 就能得到接近命令行 hexdump -C 的可读字符串；如果数据会分段到达，或者你希望边读边把结果写入日志、文件或网络连接，则使用 hex.Dumper(writer) 更合适。

Dumper 返回的是 io.WriteCloser：Write 接收原始字节并持续输出转储行，Close 负责把最后一行不足 16 字节的内容补齐。官方地址：https://pkg.go.dev/encoding/hex#Dumper

可以把三者记成一个小流程：Dumper 负责格式状态，Write 负责提交输入，Close 负责收尾。尤其是最后一个动作，不能只当成形式上的资源释放。

Dump 和 Dumper 的输出模型有什么区别

hex.Dump 接收完整的字节切片并返回字符串，调用方不需要管理关闭动作。它适合数据量较小、已经完整在内存中、并且需要立即拼接到日志或错误信息里的情况。

hex.Dumper 则接收一个 io.Writer，返回一个写入适配器。它会为每一行维护偏移量、十六进制字节列和右侧可打印字符列。输入可以分多次 Write，输出仍然保持同一份连续转储的格式。

用 Write 按块生成连续转储

Dumper.Write 的参数仍然是原始数据，不是已经编码好的十六进制文本。它会把收到的每个字节放进当前输出行，左侧显示从零开始的偏移量，右侧把可打印 ASCII 字符保留下来，不可打印字节显示为点号。

下面的例子故意把一段消息拆成三次写入。拆分只影响调用边界，不应该让每一块各自重新开始偏移量或格式；三个 Write 共同组成一份转储。

package main

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

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

	// 分段提交原始字节，Dumper 会维护同一份偏移量和十六进制列。
	chunks := [][]byte{[]byte("header:"), {0x00, 0x01, 0x7f}, []byte("payload")}
	for _, chunk := range chunks {
		// Write 返回已接收的输入字节数，错误必须立即保留。
		written, err := dumper.Write(chunk)
		if err != nil {
			panic(fmt.Errorf("写入十六进制转储失败: %w", err))
		}
		if written != len(chunk) {
			// 对 Writer 而言，短写意味着本次输入没有完整交给 Dumper。
			panic(io.ErrShortWrite)
		}
	}

	// Close 会补齐尚未满 16 字节的尾行，不能省略。
	if err := dumper.Close(); err != nil {
		panic(fmt.Errorf("关闭十六进制转储失败: %w", err))
	}
	fmt.Print(out.String())
}

这个例子选择 bytes.Buffer 只是为了把结果打印出来。真实场景可以换成文件、带缓冲的日志 Writer 或自定义的采集 Writer，但 Dumper 看到的仍然只是 io.Writer 接口。

为什么 Close 会影响最后一行

完整的 16 字节行在 Write 过程中就能输出换行和右侧字符列；如果最后一块数据不足 16 字节，Write 会先保留这行的状态。此时如果直接读取目标 Writer，可能看不到一个完整、对齐的尾行。

Close 会把剩余十六进制列补空格，再写出右侧字符列和换行。它不会凭空增加输入字节，只是把已经写入但尚未结束的一行完成。因此，Close 的调用时机就是“输入结束”的标记。

package main

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

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

	// 用一个 Write 提交不足 16 字节的数据，故意留下半行状态。
	if _, err := dumper.Write(data); err != nil {
		return "", fmt.Errorf("写入数据失败: %w", err)
	}
	// Close 才会把尾行的空白列、ASCII 区域和换行写入 out。
	if err := dumper.Close(); err != nil {
		return "", fmt.Errorf("完成转储尾行失败: %w", err)
	}
	return out.String(), nil
}

func main() {
	// 非 ASCII 字节会在右侧字符区以点号表示，便于阅读二进制内容。
	result, err := dump([]byte{'G', 'o', 0, 0xff, '!'})
	if err != nil {
		panic(err)
	}
	fmt.Print(result)
}

Write 和 Close 的错误怎样分开处理

Dumper 并不替目标 Writer 吞掉错误。底层 Writer 在写左侧偏移量、十六进制列或右侧字符列时出错，错误会从当前的 Write 或 Close 返回。特别是最后一行，错误可能直到 Close 才暴露。

因此，简单的 defer dumper.Close() 适合“尽力收尾”的日志路径，但如果转储要作为文件、协议帧或审计记录的一部分，就应该显式接住关闭错误。下面的写法把主流程错误和收尾错误都保留下来。

package main

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

func writeDump(dst io.Writer, parts ...[]byte) (err error) {
	dumper := hex.Dumper(dst)
	defer func() {
		// 若主体没有报错，Close 的错误就是最终结果；若已有错误则不覆盖原始原因。
		if closeErr := dumper.Close(); err == nil && closeErr != nil {
			err = fmt.Errorf("完成转储时关闭失败: %w", closeErr)
		}
	}()

	for _, part := range parts {
		// Write 的 n 表示已经被 Dumper 接收的原始字节数，短写不能静默忽略。
		written, writeErr := dumper.Write(part)
		if writeErr != nil {
			return fmt.Errorf("写入转储失败: %w", writeErr)
		}
		if written != len(part) {
			return fmt.Errorf("转储短写: got %d, want %d: %w", written, len(part), io.ErrShortWrite)
		}
	}
	return nil
}

func main() {
	// 这里传入多个片段，调用方只关心 Writer 是否完整收到结果。
	if err := writeDump(io.Discard, []byte("one"), []byte("two")); err != nil {
		panic(err)
	}
}

关闭后继续调用 Write 也不会恢复一个新的转储。Dumper 会返回“dumper closed”错误；如果还需要继续记录，应创建新的 Dumper，或者让同一个实例覆盖完整的输入生命周期。

怎样选择 Dump、Dumper 和分段写入

选择的关键不是“哪一个更快”，而是输入何时完整以及输出要去哪里：

1. 数据已经是完整切片，只需要一个字符串：使用 hex.Dump。
2. 数据会从文件、网络或多个业务阶段逐步到达：使用 hex.Dumper，把各段交给同一个实例。
3. 输出必须可靠落到目标 Writer：检查每次 Write，并把 Close 当成可能失败的最终写入。
4. 只想得到连续的小写十六进制字符，不需要偏移量和 ASCII 列：考虑 hex.Encode 或 hex.NewEncoder，不要把转储格式当成编码格式。

常见问题

Dumper.Write 写入的是十六进制字符串吗？

不是。参数是原始字节，Dumper 负责生成偏移量、十六进制列和右侧字符列。如果输入已经是十六进制文本，再交给 Dumper 会得到“文本的转储”，而不是二次解码。

Close 一定要调用吗？

只要最后一次 Write 可能留下不足 16 字节的尾行，就应该调用。完整行可能已经输出，但跳过 Close 仍然会漏掉半行收尾，并且无法获得关闭阶段的底层写入错误。

可以对同一个 Dumper 多次调用 Close 吗？

可以把 Close 设计成幂等的收尾动作，但业务代码不应依赖重复关闭来推进输出。第一次 Close 后实例已结束，之后继续 Write 会返回关闭错误。

为什么 Dump 不需要 Close？

Dump 在函数内部创建临时输出缓冲区、写入全部数据并完成收尾，最后直接返回字符串。它把 Dumper 的生命周期封装在一次调用里。

小结

Go 的 encoding/hex 里，Dump 适合完整数据的一次性转储，Dumper 适合把分段输入持续写到指定 io.Writer。实际使用时让同一个 Dumper 承担完整输入周期，检查每次 Write 的错误和字节数，最后显式处理 Close。这样既不会把普通十六进制编码误当作可读转储，也不会在尾行或底层 Writer 出错时丢失信息。