Go hex.NewDecoder 遇到奇数个十六进制字符时怎么处理尾部数据

平时写Go代码用到hex包做十六进制解码的时候，不少人都会碰到输入的十六进制字符个数是奇数的情况，这时候hex.NewDecoder的处理逻辑和大家熟悉的hex.DecodeString并不完全一样，不会直接返回输入长度非法的错误。

遇到奇数个十六进制字符的输入流时，hex.NewDecoder会把最后剩下的单个十六进制字符直接作为输出字节的高4位，低4位自动填充0，生成一个有效字节返回，不会主动抛出错误，处理完这个单字符后就直接终止后续解码。

hex.NewDecoder 是流式 Reader，输入结束时如果只剩一个合法的十六进制字符，不会返回 hex.ErrLength，而是返回已经解码的字节数并把尾部表达为 io.ErrUnexpectedEOF。因此排查重点是同时保存每次 Read 的 n 和 err，不能只判断错误，也不能把最后一个半字节补成 0。

处理规则可以先记成一句话：成对字符产生字节，n 个字节已经可以消费；合法但不成对的尾字符是输入不完整，非法字符则是内容错误。

• 流式接口：NewDecoder 通过 io.Reader 逐段读取，奇数尾部通常表现为 io.ErrUnexpectedEOF。
• 一次性接口：Decode 和 DecodeString 对合法奇数长度输入返回 hex.ErrLength。
• 结果边界：先处理返回的 n 个字节，再根据错误决定丢弃、补齐或请求完整输入。

先区分 NewDecoder 与 Decode 的错误类型

很多排查误差来自把一次性解码的错误名套到了流式 Reader 上。hex.ErrLength 的文档语义是报告 Decode 或 DecodeString 的奇数长度输入；NewDecoder 读到输入结束时，合法但未配对的最后一个字符会返回 io.ErrUnexpectedEOF。如果最后一个字符本身不是十六进制字符，则应按非法字节错误处理，而不是按长度不足处理。

一次性输入可以直接用 errors.Is 判断长度错误；流式读取则要把 io.ErrUnexpectedEOF 视为“输入在半个字节处结束”。下面的函数只展示判断分支，不把错误文本当成协议。

package main

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

func readHexStream(input string) ([]byte, error) {
    decoder := hex.NewDecoder(strings.NewReader(input))
    buf := make([]byte, 4)
    var out []byte
    for {
        n, err := decoder.Read(buf)
        // 只追加本次真正写入的 n 个字节，不能把 buf 的剩余内容带入结果。
        out = append(out, buf[:n]...)
        if err != nil {
            // 合法的半个字节表示输入不完整，不能静默当成正常 EOF。
            if errors.Is(err, io.ErrUnexpectedEOF) {
                return out, fmt.Errorf("hex 输入不完整，已解码 %d 字节: %w", len(out), err)
            }
            return out, err
        }
        if n == 0 {
            // 没有输出且没有错误时继续读取，避免把暂时无数据误判成结束。
            continue
        }
    }
}

func main() {
    // 这里的尾部只有一个合法十六进制字符，故意演示不完整输入。
    decoded, err := readHexStream("4869a")
    fmt.Printf("bytes=%x err=%v\\n", decoded, err)
}

按 n 处理已经写出的字节

流式解码器内部按两个字符组成一个字节。输入 4869a 时，48 和 69 已经可以产出两个字节；最后的 a 只代表半个字节，不能因为前面已有输出就把它忽略。规范的循环应先消费 n，再处理 err。

还要注意 Read 允许同时返回“本次有数据”和“本次有错误”。所以不能写成“只要 err 不为空就丢掉本次数据”，也不能写成“只要 n 大于 0 就忽略 err”。对文件或网络流而言，正确顺序通常如下：

func consumeHex(r io.Reader) ([]byte, error) {
    decoder := hex.NewDecoder(r)
    buf := make([]byte, 32)
    var result []byte
    for {
        n, err := decoder.Read(buf)
        // Read 返回的 n 才是本次有效输出长度，复用缓冲区时必须按切片截取。
        result = append(result, buf[:n]...)
        if err != nil {
            if errors.Is(err, io.EOF) {
                // 偶数个十六进制字符完整结束，EOF 表示正常收尾。
                return result, nil
            }
            // UnexpectedEOF、InvalidByteError 等非 EOF 错误都保留给调用方。
            return result, err
        }
    }
}

如果调用方把十六进制文本当作完整文件或完整消息，遇到 io.ErrUnexpectedEOF 应拒绝这份输入并要求上游补齐；如果输入来自可继续到达的分块协议，则应在协议层等待后续数据，而不是把半个字节交给业务层。

把奇数尾部和非法字符分开排查

两类错误的修复动作不同。奇数尾部说明字符数量不足，常见原因是截断、分块拼接遗漏或上游把字节转换成文本时少写了一个字符；非法字符说明输入出现了不在 0-9、a-f、A-F 范围内的内容，常见原因是带了前缀、空格或分隔符。不要通过截取错误字符串来定位，因为标准库已经提供了类型化错误。

func classifyHexError(err error) string {
    var invalid hex.InvalidByteError
    switch {
    case errors.Is(err, io.ErrUnexpectedEOF), errors.Is(err, hex.ErrLength):
        // 长度错误只能通过补齐输入或拒绝消息解决，不应猜测缺失半字节。
        return "输入长度不完整"
    case errors.As(err, &invalid):
        // InvalidByteError 携带了非法字节，便于记录安全的诊断信息。
        return fmt.Sprintf("包含非法字符 %#U", rune(byte(invalid)))
    default:
        // 底层 Reader 的 I/O 错误不能被伪装成十六进制格式错误。
        return "底层读取失败"
    }
}

若协议允许空格、换行或 0x 前缀，应在协议层明确规范化后再交给 hex.NewDecoder；不要直接把任意字符过滤掉，否则可能改变原始消息边界并掩盖传输损坏。

常见问题

为什么 NewDecoder 不返回 hex.ErrLength？

因为它是流式 Reader。官方定义把一次性解码的奇数长度映射到 hex.ErrLength，而流式 Decoder 在输入结束时用 io.ErrUnexpectedEOF 表示仍缺少半个字节。

Read 返回 n 大于 0 时还要处理 err 吗？

要。先消费 buf[:n]，再判断错误；同一次读取既有输出又有 EOF 或其它错误是合法的 Reader 组合。

可以把最后一个字符前面补 0 吗？

只有协议明确规定奇数长度按半字节补齐时才可以，而且应在进入 Decoder 前完成并记录规则。通用二进制输入不应擅自补齐，否则会改变数据。

怎么处理带空格的十六进制文本？

先按业务协议决定是否允许空白，再做明确的规范化；标准 hex.NewDecoder 本身只接受十六进制字符，不负责替你解释分隔符或前缀。

总结：流式十六进制解码要围绕“字符是否成对、已经输出多少字节、错误属于哪一层”处理。保存 n，区分 io.EOF、io.ErrUnexpectedEOF 和 hex.InvalidByteError，就能避免把截断数据当成成功结果。