encoding/hex Dump 输出如何用于调试二进制协议

调试二进制协议时，最实用的第一步通常不是把每个字段都解析出来，而是先把收到的 []byte 变成稳定、可对照的文本。Go 的 encoding/hex 包提供了 hex.Dump，输出包含偏移、十六进制字节和 ASCII 侧栏，格式与命令行 hexdump -C 相近。

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

小块数据直接用 hex.Dump(data)；已有字符串先转成 []byte 再调用 hex.Dump；数据来自持续读取的流时，使用 hex.Dumper(writer)，并在写入结束后调用 Close。这篇只讨论可读输出，不讨论抓包。

• 偏移列帮助把日志位置和协议文档中的字节位置对上。
• 十六进制列适合观察标记位、长度和固定字节。
• ASCII 侧栏适合快速确认可读字段，但不能替代协议解析。

用 Dump 生成协议字节的可读输出

hex.Dump 接收字节切片并返回一个字符串。每行最多展示 16 个字节，左侧是该行起始偏移，中间是十六进制表示，右侧把可打印字符显示出来，不可打印字节用点号占位。下面的示例把一段“类型、长度、文本、校验占位”的协议片段交给 Dump；字段含义只是示例，实际项目仍要以自己的协议定义为准。

package main

import (
	"encoding/hex"
	"fmt"
)

func main() {
	// 示例字节按“类型、长度、正文、校验占位”组织，仅用于说明观察位置。
	packet := []byte{0x01, 0x00, 0x05, 'H', 'e', 'l', 'l', 'o', 0x7f}

	// Dump 返回带偏移、十六进制列和 ASCII 侧栏的多行字符串。
	fmt.Print(hex.Dump(packet))
}

排查时先看左侧偏移是否与字段起点一致，再看长度字段是否覆盖了预期范围，最后用 ASCII 侧栏确认文本区域。不要把右侧能显示出字母理解成“字段一定是字符串”：二进制数值碰巧落在可打印范围内也会出现字母。

字符串先转 []byte 再查看字节形态

encoding/hex 标准库没有名为 hex.DumpString 的函数。输入本来是字符串时，可以显式写成 hex.Dump([]byte(text))，这样读者能看到字符串被按底层字节查看，而不是误以为发生了字符集转换。对于 UTF-8 文本，一个中文字符通常会对应多个字节；因此 ASCII 侧栏可能显示点号，这并不表示原字符串为空或损坏。

package main

import (
	"encoding/hex"
	"fmt"
)

func main() {
	text := "ID=42;状态=ready"
	// 先把字符串视为字节，再生成诊断视图；Dump 不负责字符集转换。
	fmt.Print(hex.Dump([]byte(text)))
}

在协议调试中，hex.Dump([]byte(text)) 适合查看已经由上游转换成字符串的字段；如果手里是网络帧、文件块或压缩前的原始数据，优先保留 []byte，避免中间转换影响你对字节位置的判断。不要直接调用不存在的 hex.DumpString。

按三列输出定位字段边界

一行十六进制转储可以拆成三个观察区域：偏移列告诉你位置，十六进制列告诉你真实字节，ASCII 侧栏告诉你哪些区域具备直观文本。把这三列和协议文档放在一起，就能快速发现“长度比实际正文短”“标记位错了一字节”或“文本编码和预期不一致”等问题。

一个稳妥的排查记录应同时保留“从哪个偏移开始、看到了哪些字节、按哪份协议解释”。不要只复制 ASCII 侧栏，因为不可打印字节会被压成点号，重要的长度和标志位仍然在十六进制列里。

数据较大时用 Dumper 写入 Writer

hex.Dump 会返回完整字符串，适合小块数据或已经在内存里的报文。若输入持续来自 io.Reader，或者你希望直接写入日志缓冲区，可以使用 hex.Dumper(w)。它返回一个 io.WriteCloser，写入结束后必须调用 Close，这样最后不足 16 字节的行也会补出右侧字符区域。

package main

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

func main() {
	// bytes.Buffer 只是示例 Writer，生产环境可以替换成受控日志或文件输出。
	var out bytes.Buffer
	dumper := hex.Dumper(&out)

	packet := []byte{0x01, 0x00, 0x05, 'H', 'e', 'l', 'l', 'o'}
	if _, err := io.Copy(dumper, bytes.NewReader(packet)); err != nil {
		// 写入失败时保留错误，不把不完整的诊断文本当成完整结果。
		panic(fmt.Errorf("写入十六进制转储失败: %w", err))
	}
	if err := dumper.Close(); err != nil {
		// Close 负责收尾，尾行写失败同样需要向上返回。
		panic(fmt.Errorf("关闭十六进制转储失败: %w", err))
	}
	fmt.Print(out.String())
}

这里的 Close 不是“可有可无的资源清理”。对于不满一整行的输入，它负责把剩余字节的十六进制列和 ASCII 尾部写完；忘记关闭可能让日志看起来像是少了数据。

常见误区与日志边界

hex.Dump 只负责把字节排成可读布局，不负责校验协议长度、判断大小端、验证校验和，也不会替你识别抓包来源。调试结束后应把完整转储限制在受控环境；对长期日志，优先记录偏移、长度和脱敏后的字段，避免把原始敏感字节永久保存。

常见问题

已有字符串时应该怎么生成转储？

标准库没有 hex.DumpString。可以把字符串显式转换为 []byte 后调用 hex.Dump；这只查看字符串的底层字节，不做字符集转换。

为什么 ASCII 侧栏和原文本看起来不一样？

侧栏只把可打印字节直接显示，不可打印字节用点号代替；UTF-8 中文等多字节字符也不一定能在 ASCII 区域直观呈现，应回到十六进制列解释。

什么时候应该用 Dumper？

输入来自持续读取的 Reader，或希望直接写入 Writer 时用 Dumper。写入结束要调用 Close，并处理写入和关闭错误。