Go hex.Dumper 怎样流式打印二进制调试信息

我第一次排查一个分块到达的二进制协议时，最容易写出的代码是先把所有数据读进 []byte，再调用 hex.Dump。这在小样本里很直观，但面对长连接或大文件，调试数据会被迫等到“全部读完”才出现。hex.Dumper 更适合这个场景：它把自己伪装成一个 io.WriteCloser，接收每个数据块，并持续把偏移、十六进制字节和右侧 ASCII 对照写到另一个 io.Writer。

结论：把 hex.Dumper 放在输出端，把每次读取到的字节直接 Write 进去；输入结束后一定调用 Close，尤其是最后一块不足 16 字节时。官方文档地址：https://pkg.go.dev/encoding/hex

先把一次性转储和流式转储分开

hex.Dump(data) 接收完整的 []byte 并返回一个字符串，调用方式短，适合测试样本、错误字段和小型报文。hex.Dumper(w) 则返回 io.WriteCloser，所有写入它的数据都会转成 hexdump 写到 w；它不要求调用方先把整个输入拼成一块内存。

这里的“流式”指写入方式，不代表 Dumper 会替你读取网络连接。读取仍由调用方负责，Dumper 只接收已经读出的字节，并把格式化结果发送到目标写入器。

先接一个可观察的输出端

为了在程序内部保留调试文本，可以把 bytes.Buffer 作为目标；如果希望直接写文件，则把同一位置换成打开的文件即可。下面的示例把读取端和转储端分开，便于把同一套逻辑接到连接、文件或测试数据源上：

package main

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

func dumpReader(r io.Reader) (result string, err error) {
    var out bytes.Buffer
    dumper := hex.Dumper(&out)

    // 用 defer 兜底收尾，同时把 Close 错误传回调用方。
    defer func() {
        if closeErr := dumper.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("close dumper: %w", closeErr)
        }
    }()

    buf := make([]byte, 8*1024)
    for {
        n, readErr := r.Read(buf)
        if n > 0 {
            // 只把本次实际读到的字节交给 Dumper，不能写整个 buf。
            if _, writeErr := dumper.Write(buf[:n]); writeErr != nil {
                return "", fmt.Errorf("write hexdump: %w", writeErr)
            }
        }
        if readErr == io.EOF {
            break
        }
        if readErr != nil {
            return "", fmt.Errorf("read input: %w", readErr)
        }
    }

    // 返回前由 defer 关闭 Dumper，末尾不足一行的数据也会完成格式化。
    return out.String(), nil
}

这个函数展示了三个容易漏掉的点：Read 返回的 n 即使伴随错误也可能大于零，所以先处理数据再判断错误；写入时只传 buf[:n]；关闭错误不能被无条件丢弃。这里用命名返回值让 defer 统一完成收尾，避免“显式关闭一次、延迟关闭一次”的重复调用。

分块写入时，Dumper 负责格式化而不是读取

实际接入连接时，读取循环可以来自 net.Conn、文件或自定义 io.Reader。每次调用 Write 后，输出会继续维护十六进制列和右侧字符列；输入块的边界不需要刚好落在 16 字节处。下面用多个小块表达“报文分段到达”的形状：

func dumpChunks(chunks [][]byte, dst io.Writer) error {
    dumper := hex.Dumper(dst)

    // 生命周期由调用方管理，所有块写完后显式关闭它。

    for _, chunk := range chunks {
        // 小块可以连续写入，Dumper 会在内部维护当前行的格式。
        if _, err := dumper.Write(chunk); err != nil {
            return fmt.Errorf("write chunk: %w", err)
        }
    }

    // 把收尾错误返回给上层，避免静默丢失最后一行。
    return dumper.Close()
}

调用方需要特别留意底层目标的性质：写文件时，文件本身的 Close 仍然要由文件拥有者负责；写网络连接时，Dumper 的 Close 只结束格式化器，不等于关闭连接。两种生命周期不要混在一起。

用一组可复现的指标判断是否值得接入

我在调试小型报文时会把观察成本拆成三个数字：单块读取大小、累计输出字节数和调试持续时间。Dumper 的价值是让“第一块输入到第一段可读输出”的等待时间接近一次写入，而不是等整个输入结束；它并不会让格式化文本比原始数据更省空间。

因此，Dumper 更适合短时诊断、协议样本、测试失败上下文和受控的开发日志。如果把它常驻在高吞吐生产链路上，建议加长度上限、采样或明确的调试开关；否则输出膨胀本身可能成为新的 I/O 瓶颈。

常见问题

hex.Dumper 和 hex.Dump 的输出格式一样吗？

格式目标一致，都匹配 hexdump -C 风格；区别在输入和输出形态：Dump 接收完整字节并返回字符串，Dumper 接收分块写入并把文本发往 io.Writer。

为什么最后一小段数据没有按预期显示？

先确认写入时使用了实际长度 buf[:n]，再确认在输入结束时调用了 Close。不要把 defer dumper.Close() 当成可以忽略关闭错误的理由。

关闭 Dumper 会关闭底层文件或连接吗？

不会把它当成底层资源的统一关闭动作。Dumper 的 Close 负责结束自己的格式化状态；文件、连接等资源仍由创建它们的代码按各自生命周期关闭。

能否直接把 Dumper 接到标准输出？

可以，标准输出实现了 io.Writer。但在生产环境中要控制调试开关和输出量，避免二进制内容被持续写入日志。